-
-
Save yurivish/5826ca35f8d8f96536fc to your computer and use it in GitHub Desktop.
Documentation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
# 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