Skip to content

Instantly share code, notes, and snippets.

@yurivish
Created February 23, 2015 16:47
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
Save yurivish/5826ca35f8d8f96536fc to your computer and use it in GitHub Desktop.
Documentation
# V5 Documentation
V5 is built using [React](reactjs.org). The overall architecture of the V5 application follows Facebook’s standard [Flux](http://facebook.github.io/flux/docs/overview.html) model for organizing React-based systems.
Briefly, data is stored in **stores** which subscribe to **events** dispatched by a **Dispatcher**. Dispatches usually occur in response to a user interface interaction. **UI components** subscribe to **change events** on the **stores** they care about. They respond to change events by rerendering to reflect the current state.
The entry point is **main.coffee**. That is where project data for the chosen project is loaded from the cache, or, if not present there, from the server. It is also the location of the other assorted initialization tasks like kicking off the rendering of the UI.
* * *
## cloudcore.coffee
This file houses the core word cloud layout computation. The code was written by Andrew and ported to CoffeeScript from [Jason Davies](http://www.jasondavies.com/)’ [word cloud plugin](https://github.com/jasondavies/d3-cloud) for d3.
* * *
## cloudlayout.coffee
This file contains the `CloudLayout` React component based on the cloud core and provides additional functionality such as zooming, resizing, and colorizing by selections and tags.
* * *
## components.coffe
This file contains most of the React components used for rendering V5.
* `App` is the top-level component. It contains the sidebars, the main area, and shows lightbox overlays when necessary.
* `IntroSection` is the introductory documentation shown in a lightbox on first load.
* `LoadingSection` is the loading screen that displays progress while a project loads.
* `Sidebars` contains the sidebars.
* `VennDiagramSection` renders the Venn diagram of overlapping tags and the outer circle indicating all of the project’s documents.
* `DocSelectionSection` contains the “3,400 documents in both tags” label and its associated dropdowns and export button.
* `Main` is the main area, currently occupied by the Concept Cloud. It is written in a way that allows for swapping in different types of visualizations.
* `CloudAxisControls` is exactly what it sounds like.
* `AxisControl` is a single axis selection dropdown.
* `TopInfoSection` is the portion of the screen on top of the concept cloud. It contains links to miscellaneous functionality and the cloud axis controls.
* `MiscLinksSection` has links to the settings and introduction overlay.
* `ActiveTagsSection` is what you see in the left sidebar; it contains a list of the active tags. (Right now all tags are active; the name was in expectation of a tag-picking interface that allowed you to focus on groups of tags at a time.
* `SelectedDocumentsSection` is what you see in the right sidebar; it contains a list of the currently selected documents and resets its scroll position to the top when there’s a change to its contents.
* `SelectionSection` is the component on top of the right sidebar; it contains a `PrimarySelection` and a `SecondarySelection`.
* `PrimarySelection` is the “Searching within [tag]” dropdown. that allows you to choose a primary selection.
* `SecondarySelection` indicates the secondary selection and lets you select new concepts with a search input.
* `Tag` is a simple class wrapping a tag circle, tag text, and optionally a label indicating the number of documents in the tag.
* `TagCircle` is a circle icon whose color is designated by the tag.
* `Documents` is a list of 50 document snippets.
* `RangesByTagMixin` is an object providing a `rangesByTag` function that takes tags and a document and produces an ordered list of {tag, ranges} objects sorted in order of first appearance in the document.
* `DocumentSnippet` is a small wrapper around `Snippets` (below) that has a title and also computes the tags and ranges to highlight. It also stores the state corresponding to the snippet tag-dot that was hovered.
* `Snippets` contains `Dots` and a `SnippetWithHighlights`.
* `Dots` has some dots. The dot for the visible snippet is filled in.
* `Document` is a display view for a full document along with a list of the tags present inside it.
* `DocumentSpan` is used to underline the terms that match a given tag. There’s a bit of DOM manipulation to get them to bounce using CSS animations.
* `SettingsSection` is an overlay containing the local storage setting.
* * *
## conversions.coffee
This file contains a single function that preprocess terms to standardize our terminology. In V5, `term` means a term object (with a score, surface text, and so on) and `label` means a string of the form `stem|lang`.
* * *
## d3_with_mixins.coffee
This file exports d3 after augmenting it with a `moveToFront` convenience method.
* * *
## debug.coffee
This file contains a convenience method that makes debug calls less verbose by aliasing `console.log` to `d` and `_d`. The latter is useful when you’re inside of a d3-style anonymous accessor function where the standard convention is to name the argument `d` for “data”.
For example: `circles.attr(‘r’, (d) -> scale(d.value))`
* * *
## dev_auth.coffee
This file adds `login` and `logout` functions to the `window` object so that it’s easy to log in from the development console.
* * *
## dispatcher.coffee
This file contains the Dispatcher. It dispatches events to all stores that register with it.
Internally it keeps a list of promises for the callbacks it intends to make. This allows one store to `waitFor` another store when they both process the same event, regardless of the order in which their callbacks were registered.
* * *
## idb.coffee
This file contains our interface to IndexedDB, a local key-value store. Christina wrote it.
It is used when storing projects locally. The API to IndexedDB is asynchronous, so the interface of `LumiIDB` is also asynchronous.
* * *
## lightbox.coffee
This is a tiny file that wraps a passed-in element in a lightbox container.
* * *
## loader.coffee
This file contains a high-level interface to the API for loading tags, terms, and promises.
* * *
## loadingscreen.coffee
This file implements the loading animation, wherein variegated polygons zoom around a heptagon while a progress bar slowly circles around.
* * *
## lodash_with_mixins.coffee
This file is exactly what it sounds like. We add a few convenience methods to lodash through its mixing functionality here.
* * *
## matrixvis.coffee
This is an unused and partly-finished React component that wraps the correlation matrix view in V4.
* * *
## meta.coffee
This file contains a few simple classes that specify the behaviors and storage requirements of our various types of tags:
* `Tag` is a simple tag specified by a set of documents.
* `ExactTag` is a tag created from a set of term labels.
* `ConceptualTag` is like `ExactTag` but also includes conceptual matches.
* `MetadataTag` is based on a document’s subsets.
* `CombinedTag` takes any number of tags and combines them with a given set operation.
* * *
## projectstore.coffee
This file contains the ProjectStore, which was split out from `stores.coffee` because we were in the process of separating all stores out into their own files.
It contains information about the current project, including its ID, name, documents, terms, as well as a search index on those documents and terms.
* * *
## api.coffee
This file contains a Luminoso API client that supports token auth. Right now it is capable of `get`, `put`, and `post` requests.
* * *
## react_with_aliases.coffee
This file exports `React` as `React`, `React.DOM` as `D`, and `React.addons.classSet` as `classSet`.
* * *
## relevance.coffee
This file implements the relevance computation for terms. The code is heavily based on the Python code from the V4 API.
* * *
## searchindex.coffee
This file implements a simple search index to speed up term searches. It maintains a map from term labels to a list of the documents containing that term label.
It also augments our document representation with term counts and term match ranges. This makes displaying highlighted search results more efficient.
* * *
## setops.coffee
This file exports a variety of set operations (intersection, difference, union) that operate on sorted lists.
* * *
## settings.coffee
This file holds dashboard settings (currently only `localProjectStorageEnabled`).
* * *
## snippet.coffee
This file contains a static class with several functions that make it easy to construct snippets around ranges of text indicated by indices. There are many parameters to play with, but the defaults are pretty good.
* * *
## stores.coffee
This file contains all of the data stores that contain the information displayed in the UI.
### TagStore
The TagStore stores tags and contains functionality for adding and removing tags.
### SelectionStore
The SelectionStore holds information about tags of current interest.
The **primary selection** corresponds to the active tag in the search box area. The **secondary selection** corresponds to the “Searching within” dropdown.
The **axis selections** correspond to the concepts used by the **CloudStore** to lay out the concept cloud.
When any selection updates, `updateDerivedSelections` is run. It computes the document sets corresponding to the active selections and combining set operation.
### CloudStore
The cloud store sells clouds. It also keeps information relating to the **terms in the cloud** and the results of the **word cloud layout** process.
Unlike in V4, the V5 cloud is recomputed dynamically when the primary selection is changed — term relevance, used for sizing the concepts, is recomputed on the fly for the subset of documents specified by the primary selection.
### Dispatch mixins
At the bottom of **stores.coffee** there are a number of one-line functions, called almost exclusively from UI components, which dispatch specific events (e.g., `addTag`, `changePrimarySelection`, `docsLoaded`) to all of the stores.
* * *
## tagcorrelationview.coffee
This file houses an unused attempt to make a correlation-matrix-like view that highlights cells depending on the amount of documents in the intersection of two tags. The idea was to eventually highlight based on interestingness, drawing attention to those places that have more or less documents than you’d expect.
* * *
## vennops.coffee
This file contains set operations wrapped in a way that makes them usable as options in the dropdown for choosing how to combine the primary and secondary selection.
* * *
## mixins.coffee
This file contains a lot of utility functions. Many of them should be elsewhere; their presence here indicates an opportunity for improvement through code reorganization.
Others are general utility functions.
* * *
## vector.coffee
This file contains a `Vector` “class” (it’s a pure Javascript object) with methods for adding, subtracting, normalizing, scaling, and doting vectors. Each function producing a vector takes an optional `out` vector. If the `out` vector is not specified, the input vector is modified in-place.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment