Extension:VIKI/Developer Notes

Below are notes on the structure and code path of the VIKI extension.

Files

• VIKI.php - legacy for MW 1.24 and earlier
• VikiJS.class.php - PHP side, hooks, sets up VIKI.js to run, also load resource modules for VIKI plugins
• vex.js (version 2.0.1) used for modals, spin.min.js (version 2.0.1) for the spinner, contextmenu.js (version r2) for the right-click menu
• VIKI.js: where all the action takes place; most of the functions are already documented in the file
  • entry point: initialize(), sets up a lot of the views, calls InitializationCompleteHook and GetAllWikis hook and/or GetAllWikis hookCompletion(), which then calls fetchContentNamespaces()
  • fetchContentNamespaces() fetches all content namespaces, and on completion, calls populateInitialGraph()
  • populateInitialGraph() -> startElaboratingNodes() creates nodes from the initial set, adds them to graph, visits them (to verify existence, get categories, etc), and calls elaborateWikiNode() on each of the elaborate-able nodes

Node management

• Node objects are created in createExternalNode(), createWikiNodeFromWiki(), and createWikiNodeFromExternalLink()
• They're not added to the graph until addNode() is called
• addNode() does not automatically redraw the graph, because redraws can be expensive; redraw() calls are explicit and generally only after a batch of nodes are added
• D3 doesn't have (very easy) built-in support for hiding and showing nodes and links, which makes for tricky code scattered throughout VIKI related to carefully hiding and showing nodes and links by removing them from the node and link arrays... this is a limitation of D3.

Node Elaboration

• probably needs to be refactored, it's pretty ugly
• elaborateWikiNode() takes parameters: node, completionHandler block, and elaborationType (initial population, normal, or 2nd order)
• makes three AJAX calls to get links out, links in, and external links
  • checkElaborationQueriesComplete() only proceeds when all three calls have returned, then completeElaboration() called once
  • completeElaboration() calls the success handlers of all three AJAX types, then conditionally calls findSecondOrderLinks() (if this wasn't already a 2nd order link query and the flag is set to find 2nd order links)
  • findSecondOrderLinks() calls elaborateWikiNode() on all these nodes again to find 2nd order links, this time with the elaborationType for 2nd order links
  • these three success handlers are very similar, probably have duplicate code and probably could be combined with some logic
    • there are tons of conditionals that handle a lot of edge cases
    • there is careful logic to add a new node only if the node's not already in the graph, and to add links if they're not already in the graph

Node Hiding

• each node maintains boolean flags for reasons it may want to be hidden: hidden category, explicitly hidden by user, hidden as part of a hub, or is an incoming/outgoing link (and the user selected "hide incoming links" or "hide outgoing links")
• hiding functions will filter for the appropriate nodes, set their appropriate flag, and call hideNode()
• unhiding functions will call unhideNodesIfValid() to selectively un-hide nodes
• hideNode() does not explicitly call redraw() on the graph - the calling hide function (e.g. hideCluster() ) must do the redraw() afterward.