Stackedit/doc/developer-guide.md

Developer guide

Getting started

Pre-requisites

• Git
• node.js/npm
• Grunt
• Bower

Before debugging

• Download dependencies using Bower:

    bower install
  

• To serve StackEdit in http://localhost/stackedit, add something like this in httpd.conf:

    Alias /stackedit /Users/benweet/workspace/stackedit 
  
    <Directory /Users/benweet/workspace/stackedit>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all
    </Directory>
  

• Open Chrome without application cache:

    chrome --disable-application-cache
  

• Run StackEdit in debug mode (serve original files instead of minified):

    http://localhost/stackedit/?debug
  

Add new dependencies

NOTE: StackEdit uses RequireJS for asynchronous module definition (AMD).

• Install new dependencies using Bower:

    bower install <library> --save
  

• Add the new dependency to RequireJS configuration file (main.js):

    grunt bower
  

Build/minify

grunt

Architecture

---

core

The core module is responsible for:

• creating the UI Layout,
• creating the PageDown editor,
• loading/saving the settings,
• running periodic tasks,
• detecting the user activity,
• checking the offline status.

Attributes:

• isOffline: indicates the offline status of the application.

Methods:

• onReady(callback): sets a callback to be called when all modules have been loaded and the DOM is ready.

NOTE: This is preferred over jQuery's .ready() because it ensures that all AMD modules are loaded by RequireJS).

• runPeriodically(callback): sets a callback to be called every second.

NOTE: The callback will not run if the user is inactive or in StackEdit Viewer. User is considered inactive after 5 minutes of inactivity (mouse or keyboard).

• setOffline(): can be called by any other modules when a network timeout occurs for instance.

NOTE: the offline status is also set by detecting the window offline event. core.isOffline is automatically set to false when the network is recovered.

• initEditor(fileDesc): creates or refreshes the PageDown editor with a given FileDescriptor object.

---

fileMgr

The fileMgr module is responsible for:

• creating and deleting local files
• switching from one file to another

Attributes:

• currentFile: the FileDescriptor object that is currently edited.

Methods:

• createFile(title, content): creates a FileDescriptor object, add it in the fileSystem map and returns it.
• deleteFile(fileDesc): deletes a FileDescriptor object from the fileSystem map.
• selectFile(fileDesc): selects a FileDescriptor object for editing.

FileDescriptor

The FileDescriptor class represents a local file. A FileDescriptor object has the following properties:

• fileIndex: the unique string index of the file in the file system
• title: the title of the document
• content: the content of the document
• syncLocations: a map containing all the associated syncAttributes objects with their syncIndex as a key
• publishLocations: a map containing all the associated publishAttributes objects with their publishIndex as a key

And the following methods:

• addSyncLocation(syncAttributes): associates a syncAttributes object with the file
• removeSyncLocation(syncAttributes): unassociates a syncAttributes object with the file
• addPublishLocation(publishAttributes): associates a publishAttributes object with the file
• removePublishLocation(publishAttributes): unassociates a publishAttributes object with the file

fileSystem

The fileSystem module is a map containing all the FileDescriptor objects with their fileIndex as a key.

---

synchronizer

The synchronizer module is responsible for:

• creating a new local file from a sync location (import)
• creating a new sync location from a local file (export)
• running 2 ways synchronization (upload and download) for all sync locations

synchronizer's providers

A provider module can be associated with the synchronizer module if it implements the following functions:

• importFiles(): downloads one or multiple files and create local files associated with the sync locations
• exportFile(): uploads a local file to a new sync location
• syncDown(): performs a download of all the changes operated on all sync locations
• syncUp(): performs an upload of a change to a sync location

syncAttributes

A syncAttributes object is an object that describes a sync location. Attributes differ from one provider to another except for the following:

• syncIndex: the unique string index of the publish location
• provider: the provider module that handles the sync location

---

publisher

The publisher module is responsible for:

• creating new publish locations
• updating existing publish locations

publisher's providers

A provider module can be associated with the publisher module if it implements the following functions:

• newPublishAttributes(): returns a new publishAttributes object in order to create a new publish location
• publish(): performs publishing of one publish location

publishAttributes

A publishAttributes object is an object that describes a publish location. Attributes differ from one provider to another except for the following:

• publishIndex: the unique string index of the publish location
• provider: the provider module that handles the publish location
• format: the publishing format for the publish location. It can be:
  • markdown for Markdown format
  • html for HTML format
  • template for template format

---

provider

Written with StackEdit.