Stackedit/doc/developer-guide.md

Developer guide

Architecture

NOTE:

• StackEdit uses RequireJS for asynchronous module definition (AMD).
• jQuery, Underscore.js or any other 3rd party libraries can be called from anywhere as long as they have been declared as module dependencies.

---

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:

• core.isOffline: indicates the offline status of the application.

Methods:

• core.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).

• core.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).

• core.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.

• core.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

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.