Developer guide =============== Getting started --------------- ### Pre-requisites - [Git][1] - [node.js/npm][2] - [Grunt][3] - [Bower][4] ### Before debugging - Download development tools: npm install - Download dependencies: bower install - Serve **StackEdit** at `http://localhost/`: (export PORT=80 && node server.js) - Run Chrome without application cache: chrome --disable-application-cache - Run **StackEdit** in debug mode (serve original files instead of minified): http://localhost/?debug ### Add new dependencies > **NOTE:** StackEdit uses [RequireJS][5] for asynchronous module definition ([AMD][6]). - Install new dependencies using [Bower][7]: bower install --save - Add the new dependency to [RequireJS][8] configuration file (`main.js`): grunt bower ### Build/minify grunt ### Deploy - on Heroku: heroku create my-stackedit-instance git push heroku master - in a Docker container: docker build -t my-stackedit-image . docker run -p 3000 my-stackedit-image > **NOTE:** OAuth authorizations work out of the box for address `http://localhost/` except for WordPress. To allow another address, you have to add specific keys at the end of `constants.js` and eventually to set up specific proxies with the corresponding key/secret pairs ([WordPress Proxy][9], [Tumblr Proxy][10] and [Gatekeeper][11]). Architecture ------------ ![Architecture diagram][12] The modules are loaded by RequireJS in the following order: 1. The 3rd party libraries (jQuery, underscore.js...) 2. The `Extension` modules 3. The `eventMgr` module 4. The `core` module 5. The `fileMgr` module and the helpers modules 6. The `Provider` modules 7. The `publisher` and `synchronizer` modules This is important to notice in order to avoid circular dependencies. For instance, if an `Extension` is declared with the `core` module as a dependency, RequireJS will inject `undefined` instead of the actual module. Any module though can access any dependencies by implementing the proper [injection listener][13] provided by the `eventMgr`. ---------- ### core The `core` module is responsible for: - creating the [UI Layout][14], the [ACE][15] editor and the [PageDown][16] 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()`][17] because it ensures that all AMD modules are loaded by [RequireJS][18]. - `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][19] editor with a given [`FileDescriptor`][20] object. ---------- ### fileMgr The `fileMgr` module is responsible for: - creating and deleting local files, - switching from one file to another. **Attributes:** - `currentFile`: the [`FileDescriptor`][21] object that is currently edited. **Methods:** - `createFile(title, content)`: creates a [`FileDescriptor`][22] object, add it in the [`fileSystem`][23] map and returns it. - `deleteFile(fileDesc)`: deletes a [`FileDescriptor`][24] object from the [`fileSystem`][25] map. - `selectFile(fileDesc)`: selects a [`FileDescriptor`][26] 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`][27] objects with their `syncIndex` as a key. - `publishLocations`: a map containing all the associated [`publishAttributes`][28] objects with their `publishIndex` as a key. And the following methods: - `addSyncLocation(syncAttributes)`: associates a [`syncAttributes`][29] object with the file. - `removeSyncLocation(syncAttributes)`: unassociates a [`syncAttributes`][30] object with the file. - `addPublishLocation(publishAttributes)`: associates a [`publishAttributes`][31] object with the file. - `removePublishLocation(publishAttributes)`: unassociates a [`publishAttributes`][32] object with the file. #### fileSystem The `fileSystem` module is a map containing all the [`FileDescriptor`][33] 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`][34] 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`][35] 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`][36] module can be associated with the `publisher` module if it implements the following functions: - `newPublishAttributes()`: returns a new [`publishAttributes`][37] 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`][38] 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. ---------- ### eventMgr The `eventMgr` module is responsible for receiving and dispatching events. Below is the list of all events signatures. Most events (those that are not triggered by the `eventMgr` module) can be triggered by calling methods of the same name in the `eventMgr` module. For example: ```js eventMgr.onMessage('StackEdit is awesome!'); ``` The method `addListener(eventName, callback)` of the `eventMgr` module can be used to listen to these events (except those that can only be handled by `Extension` modules). For example: ```js eventMgr.addListener('onMessage', function(message) { alert(message); }); ``` `Extension` modules have the possibility to listen to those events by implementing methods of the same name. For example: ```js myExtension.onMessage = function(message) { alert(message); }; ``` ---------- #### Core events - **`onReady()`** All the modules are loaded and the DOM is ready. > Triggered by the `core` module. > This is preferred over [jQuery's `.ready()`][39] because it ensures that all modules have been loaded by RequireJS. - **`onMessage(message)`** A message destined to the user has been produced. - `message`: the text string of the message. - **`onError(error)`** An error has been thrown. - `error`: an error object or a string. - **`onOfflineChanged(isOffline)`** The off-line status has changed. - `isOffline`: the off-line status. > Triggered by the `core` module. - **`onUserActive()`** The user has just moved the mouse or pressed the keyboard. > Triggered by the `core` module. - **`onAsyncRunning(isRunning)`** Some asynchronous tasks have just started or stopped. - `isRunning`: true if started, false if stopped. > Triggered by the `AsyncTask` module. - **`onPeriodicRun()`** A hook that is called periodically (every 1 second if user is active). > Triggered by the `core` module. - **`onLoadSettings()`** A hook that is called when the settings dialog has to be refreshed. Every `Extension` module that has configuration inputs in the settings dialog has to implement a listener for this event. > Triggered by the `core` module. Only `Extension` modules can handle this event. - **`onSaveSettings(newConfig, event)`** A hook that is called when the settings dialog has to be validated. Every `Extension` module that has configuration inputs in the settings dialog has to implement a listener for this event. - `newConfig`: the new configuration object, deduced from the settings dialog inputs. - `event`: the submit event object. `stopPropagation` has to be called in case of an error when parsing settings dialog inputs. > Triggered by the `core` module. Only `Extension` modules can handle this event. - **`onInit()`** A hook allowing enabled extensions to initialize. > Triggered by the `eventMgr` module. Only `Extension` modules can handle this event. > This event is triggered before `onReady` event and just after the `config` and `enabled` extensions properties have been set by the `eventMgr`. ---------- #### Module injection events - **`onFileMgrCreated(fileMgr)`** The `fileMgr` module has been created. - `fileMgr`: the `fileMgr` module. > Triggered by the `fileMgr` module. - **`onSynchronizerCreated(synchronizer)`** The `synchronizer` module has been created. - `synchronizer`: the `synchronizer` module. > Triggered by the `synchronizer` module. - **`onPublisherCreated(publisher)`** The `publisher` module has been created. - `publisher`: the `publisher` module. > Triggered by the `publisher` module. - **`onEventMgrCreated()`** The `eventMgr` module has been created. - `eventMgr`: the `eventMgr` module. > Triggered by the `eventMgr` module. ---------- #### file operation events - **`onFileCreated(fileDesc)`** A [`FileDescriptor`][41] object has been created. - `fileDesc`: the [`FileDescriptor`][42] object. > Triggered by the `fileMgr` module. - **`onFileDeleted(fileDesc)`** A [`FileDescriptor`][43] object has been removed from the `fileSystem` module. - `fileDesc`: the [`FileDescriptor`][44] object. > Triggered by the `fileMgr` module. - **`onFileSelected(fileDesc)`** A [`FileDescriptor`][45] object has been selected. - `fileDesc`: the [`FileDescriptor`][46] object. > Triggered by the `fileMgr` module. This event is triggered before `onFileClosed` (if another document is open) and `onFileOpen` events. - **`onFileClosed(fileDesc)`** The current [`FileDescriptor`][47] object is about to be detached from the editor. - `fileDesc`: the [`FileDescriptor`][48] object. > Triggered by the `fileMgr` module. This event is triggered after `onFileSelected` event and before `onFileClosed` event. - **`onFileOpen(fileDesc)`** The selected [`FileDescriptor`][49] object has been attached to the editor. - `fileDesc`: the [`FileDescriptor`][50] object. > Triggered by the `fileMgr` module. This event is triggered after `onFileSelected` and `onFileClosed` (if another document is open) events. - **`onContentChanged(fileDesc)`** The content of a [`FileDescriptor`][51] object has been modified. - `fileDesc`: the [`FileDescriptor`][52] object. - **`onTitleChanged(fileDesc)`** The content of a [`FileDescriptor`][53] object has been modified. - `fileDesc`: the [`FileDescriptor`][54] object. - **`onFoldersChanged()`** The folders structure has changed. ---------- #### Sync events - **`onSyncRunning(isRunning)`** A synchronization job has just started or stopped. - `isRunning`: true if started, false if stopped. > Triggered by the `synchronizer` module. > A synchronization job is the action to download and upload all detected changes for all sync locations of all documents. - **`onSyncSuccess()`** A synchronization job has successfully finished. > Triggered by the `synchronizer` module. > A synchronization job is the action to download and upload all detected changes for all sync locations of all documents. - **`onSyncImportSuccess(fileDescList, provider)`** The import of documents has successfully finished. - `fileDescList`: the list of [`FileDescriptor`][55] objects that have been created. - `provider`: the [`provider`][56] module that handled the import. > Triggered by the [`provider`][57] module that handled the import. > An import is the action to download multiple files and to create, for each, one [`FileDescriptor`][55] objects with one sync location. - **`onSyncExportSuccess(fileDesc, syncAttributes)`** The export of one document has successfully finished. - `fileDesc`: the [`FileDescriptor`][58] object that has been exported. - `syncAttributes`: the descriptor object of the new sync location. > Triggered by the `synchronizer` module. > An export is the action to upload one file and to create one new sync location associated with one existing `FileDescriptor`][55] object. - **`onSyncRemoved(fileDesc, syncAttributes)`** A sync location has been removed from a [`FileDescriptor`][59] object. - `fileDesc`: the [`FileDescriptor`][60] object. - `syncAttributes`: the descriptor object of the removed sync location. ---------- #### Publish events - **`onPublishRunning(isRunning)`** A document publication job has just started or stopped. - `isRunning`: true if started, false if stopped. > Triggered by the `publisher` module. > A publication job is the action to upload changes on multiple publish locations associated with one `FileDescriptor`][55] object. - **`onPublishSuccess(fileDesc)`** A document publication job has successfully finished. - `fileDesc`: the [`FileDescriptor`][60] object that has been published. > Triggered by the `publisher` module. > A publication job is the action to upload changes on multiple publish locations associated with one `FileDescriptor`][55] object. - **`onNewPublishSuccess(fileDesc, publishAttributes)`** A new publish location has been successfully created. - `fileDesc`: the [`FileDescriptor`][60] object that has been published. - `publishAttributes`: the descriptor object of the new publish location. > Triggered by the `publisher` module. - **`onPublishRemoved(fileDesc, publishAttributes)`** A publish location has been removed from a [`FileDescriptor`][59] object. - `fileDesc`: the [`FileDescriptor`][60] object. - `publishAttributes`: the descriptor object of the removed publish location. > Triggered by the `publisher` module. ---------- #### UI Layout events - **`onLayoutConfigure(layoutConfig)`** The layout is about to be configured. - `layoutConfig`: the configuration object of the UI Layout library. > Triggered by the `core` module. - **`onLayoutCreated(layout)`** The layout has just been created. - `layout`: the layout object of the UI Layout library. > Triggered by the `core` module. - **`onLayoutResize(paneName)`** One pane of the layout has been resized. - `paneName`: the name of the resized layout pane. > Triggered by the `core` module. - **`onCreateButton()`** Allows extensions to add their own buttons in the navigation bar. Implemented listeners have to return an HTML button element. For example: myExtension.onCreateButton = function() { var button = $(''); button.click(function() { eventMgr.onMessage('Booom!'); }); return button[0]; }; > Triggered by the `eventMgr` module. Only `Extension` modules can handle this event. - **`onCreateEditorButton()`** Allows extensions to add their own buttons in the side bar. Implemented listeners have to return an HTML button element. See `onCreateButton` for a concrete example. > Triggered by the `eventMgr` module. Only `Extension` modules can handle this event. - **`onCreatePreviewButton()`** Allows extensions to add their own buttons over the preview. Implemented listeners have to return an HTML button element. See `onCreateButton` for a concrete example. > Triggered by the `eventMgr` module. Only `Extension` modules can handle this event. ---------- #### PageDown events - **`onPagedownConfigure(editor)`** The Pagedown editor is about to be created. - `editor`: the Pagedown editor object before `run` has been called. > Triggered by the `core` module. - **`onAsyncPreview(callback)`** Called after Pagedown's synchronous rendering to trigger extra asynchronous rendering (such as MathJax). Implemented listeners have to call the callback parameter after processing in order other `onAsyncPreview` listeners to run. - `callback`: the callback to call at the end of the asynchronous processing. > Triggered by the `eventMgr` module. Only `Extension` modules can handle this event. - **`onPreviewFinished(html)`** Called after every `onAsyncPreview` listeners have been called. - `html`: the finally rendered HTML. - **`onSectionsCreated(sectionList)`** The Markdown has been split into sections before rendering. - `sectionList`: the list of section objects. Each section object contains: - `text`: the markdown substring contained in the section. - `textWithDelimiter`: the text with an added delimiter. > Triggered by the `markdownSectionParser` extension. - **`onMarkdownTrim(offset)`** The Markdown has been left trimmed by a certain number of character. - `offset`: the number of characters that have been removed. > Triggered by the `yamlFrontMatterParser` extension. ---------- #### ACE events - **`onAceCreated(aceEditor)`** The ACE editor has just been created. - `aceEditor`: the ACE editor object. > Triggered by the `core` module. > Written with [StackEdit](https://stackedit.io/). [1]: http://git-scm.com/ [2]: http://nodejs.org/ [3]: http://gruntjs.com/ [4]: http://bower.io/ [5]: http://requirejs.org/ "RequireJS" [6]: http://en.wikipedia.org/wiki/Asynchronous_module_definition "Asynchronous module definition" [7]: http://bower.io/ [8]: http://requirejs.org/ "RequireJS" [9]: https://github.com/benweet/stackedit-wordpress-proxy [10]: https://github.com/benweet/stackedit-tumblr-proxy [11]: https://github.com/prose/gatekeeper [12]: https://lh6.googleusercontent.com/-sr6zRtyaoUk/Un5qSakOzPI/AAAAAAAAFC0/oI5If5fI9Gw/s0/StackEdit%252520architecture%252520-%252520New%252520Page%252520%2525283%252529.png "StackEdit architecture" [13]: #module-injection [14]: http://layout.jquery-dev.net/ "UI Layout" [15]: http://ace.c9.io [16]: https://code.google.com/p/pagedown/ "PageDown" [17]: http://api.jquery.com/ready/ [18]: http://requirejs.org/ "RequireJS" [19]: https://code.google.com/p/pagedown/ "PageDown" [20]: #filedescriptor [21]: #filedescriptor [22]: #filedescriptor [23]: #filesystem [24]: #filedescriptor [25]: #filesystem [26]: #filedescriptor [27]: #syncattributes [28]: #publishattributes [29]: #syncattributes [30]: #syncattributes [31]: #publishattributes [32]: #publishattributes [33]: #filedescriptor [34]: #provider [35]: #provider [36]: #provider [37]: #publishattributes [38]: #provider [39]: http://api.jquery.com/ready/ [40]: http://requirejs.org/ "RequireJS" [41]: #filedescriptor [42]: #filedescriptor [43]: #filedescriptor [44]: #filedescriptor [45]: #filedescriptor [46]: #filedescriptor [47]: #filedescriptor [48]: #filedescriptor [49]: #filedescriptor [50]: #filedescriptor [51]: #filedescriptor [52]: #filedescriptor [53]: #filedescriptor [54]: #filedescriptor [55]: #filedescriptor [56]: #provider [57]: #provider [58]: #filedescriptor [59]: #filedescriptor [60]: #filedescriptor