Frontend V2.0

See here for the current frontend V2.0 prototype

As of May 2013, we are revamping our frontend display/functionality to allow:

• URL routing for a given view
• Smooth integration of exploration, learning, and editing displays
• Allow graphical changes based on the desired depth of understanding
• New exploration mode options such as expanding/collapsing nodes, showing paths between nodes
• Frontend (javascript) calculation of graph placement
• Display user contributed content next to "original" content

We will strive for a modular MVP frontend, where initially we will use backbone.js to help eliminate ambiguity in design choices and streamline the development of the core kmap functionality. Backbone.js also has a large community base and strong documentation, which bode well for future frontend contributors.

User Flow

1. user searches for foo
2. if foo is ambiguous present user with disambiguation display
3. present the user with the exploration-view, with the foo node highlighted and parents and grandparents visible (two level hierarchy)

• the user can expand/collapse the parents or expand/collapse foo to see/hide its children (expand/collapse and expand-all/collapse-all functionality)
• the user can mark nodes they already understand (collapsed nodes do not assume the user understands all collapsed dependencies but these concepts are dimmed in the learning view)

1. at any point (e.g. once the appropriate nodes are expanded/collapsed/maked-as-known) the user can switch to the learning view
2. the learning view presents a linear list of topics that can be expanded and marked as learned (turn green, add a checkmark, etc)

NB: in addition, both the exploration view and the learning view will have an "edit" button that will pull up the editing view for the selected content

Frontend Technical Flow

1. the user query is an ajax request to the server that returns the complete data (title, summary, dependencies) for all ancestors and children of the searched node (further descendents/ancestors will require additional ajax queries)
2. asynchronously: use js-graphviz to obtain coordinates of edges and nodes for initial view
3. populate an ancilliary view object that maintains (client-id, coordinates) pairs for both the nodes and edges
4. draw the graph view on the svg display
5. asynchronously: populate the models described below
6. select the searched node in the exploration view and load the sidebar at a 75 (canvas) 25 (sidebar) split (adjustable by the user to a reasonable max/min value) (no sidebar, exploration view will be minimalist and encourage the user to use the learning view when trying to learn the concepts)
7. collapsing/expanding nodes will involve recomputing the coordinates from js-graphviz, where smooth animation transitions for already present nodes should help ease disorientation for the user (TODO unless we can modify graphviz so that it keeps some nodes at the same coordinates)
8. marking nodes as "known" will simply dim them (light gray display) and add a checkmark of some type and then propagate this information to the server for registered users
9. transition to the learning view will take place when the user clicks a small "learning view" button that slides the learning view into the main focus but allows the user the ability to easily transition between the learning view and the exploration view

Models

• Node : the node is the central model

  • title [text]: human-readable title
  • id [text]: server-side id for the node
  • summary [text]: human-readable summary
  • pointers [markdown text]: directives to other nodes (may change to a model with combination text/collection)
  • questions [model collection]: collection of "Question" models
  • resources [text] [model collection]: collection of "Resource" models
  • inlinks [model collection]: collection of "DirectedEdge" models
  • outlinks [model collection]: collection of "DirectedEdge" models
  • visible [boolean]: is the node current visible to the user
  • learned [boolean]: whether the user understands this concept

• Question: contains comprehension question text and meta information for a given node

  • text [text]: comprehension question text
  • node [text]: pointer to the node that uses this question

• Resource: contains information regarding a given resource

  • title [text]: title for the given resource
  • node [text]: pointer to the node that uses this question
  • location [text]: location for the resource (should be a verbal description, if applicable)
  • url [text]: url to the given resource
  • resource type [text]: description of resource type, e.g. textbook
  • free [bool]: binary indicator of whether the resource is free
  • edition [text]: resource edition details
  • authors [list]: list of text values, one for each author
  • dependencies [list]: list of dependencies for the resource if different than node dependencies
  • mark [list]: list of strings indicatings marks for the resource
  • extra [list]: list of strings of extra information for the given resource
  • note [list]: list of strings of notes for a given resource

• DirectedEdge: represents directed edges between nodes

  • end [text]: destination node
  • origin [text]: origin node
  • reason [text]: reason for directed edge
  • visible [boolean]: is the node current visible to the user

Views

AGFK interaction will primarily take place through two views: an exploration and a learning view, where the exploration view shows the DAG and the learning view shows a linear list of topics that can be expanded to reveal all content

TODO this section will become a detailed technical list of all general purpose views and specific purpose sub-views

Template view

The general AGFK view will have a top toolbar with search functionality, access to the user account, Sign-in/Sign-up, etc.

Exploration view

The main exploration view will contain a full screen svg display of the knowledge map embedded within the template view and with an "invisible" sidebar that switches between learning and exploration view

Learning view

The learning view will be a linear list of topics from the exploration view, where each of the main data elements of a node (title, summary, pointers, questions, resources, dependencies) will have its own subview.

URL routing

The guiding principle for agfk URL routing will be to provide users with a direct URL to any specific expanded/collapsed version of a given graph but user-specific details (learned concepts) will be saved on the server for registered users

Why should we use the X JS library rather than "rolling our own"

• backbone.js: avoid two scenarios (1) spending a lot of time/effort designing our own MV* framework that syncs with the server, display, and handles user events/interactions (2) future developers will probably be familiar with backbone architecture rather than our own architecture
  • underscore.js: dependency for backbone.js and has a lot of useful helper functions (each, map, bind, bindAll)
• d3.js: lower-level library for creating visualizations/transitions with data from the server and from the user; it's a well-tested/developed method for working directly with SVG elements and transitions
• jquery.js: pseudo-dependency for backbone.js and generally useful library

As the project progresses we may remove some of these libraries for our own implementation