-
Notifications
You must be signed in to change notification settings - Fork 150
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Initial atoms and Mobiledoc 0.3 design
- Loading branch information
Showing
6 changed files
with
217 additions
and
76 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # Mobiledoc Atoms | ||
|
|
||
| Atoms are effectively read-only inline cards. | ||
|
|
||
| ## Atom format | ||
|
|
||
| An atom is a javascript object with 3 *required* properties: | ||
|
|
||
| * `name` [string] - The name of this atom in the mobiledoc | ||
| * `type` [string] - The output of this atom. Valid values are 'dom', 'html', and 'text' | ||
| * `render` [function] - Invoked by the renderer to render this atom | ||
|
|
||
| ## Atom rendering | ||
|
|
||
| The `render` function on an atom is called by an instance of a renderer and passed an object with the following four properties: | ||
|
|
||
| * `env` [object] - A set of environment-specific properties | ||
| * `options` [object] - Rendering options that were passed to the renderer (as `cardOptions`) when it was instantiated | ||
| * `payload` [object] - The data payload for this atom from the mobiledoc | ||
| * `value` [string] - The textual representation to for this atom | ||
|
|
||
| The return value of the `render` function will be inserted by the renderer into the rendered mobiledoc. | ||
| The return value can be null if an atom does not have any output. If there is a return value it | ||
| must be of the correct type (a DOM Node for the dom renderer, a string of html or text for the html or text renderers, respectively). | ||
|
|
||
| #### `env` | ||
|
|
||
| `env` always has the following properties: | ||
|
|
||
| * `name` [string] - the name of the card | ||
| * `onTeardown` [function] - The atom can pass a callback function: `onTeardown(callbackFn)`. The callback will be called when the rendered content is torn down. | ||
|
|
||
| ## Atom Examples | ||
|
|
||
| Example dom atom that renders a mention: | ||
|
|
||
| ```js | ||
| export default { | ||
| name: 'mention', | ||
| type: 'dom', | ||
| render({ env, options, value, payload}) { | ||
| return document.createTextNode(`@${value}`); | ||
| } | ||
| }; | ||
| ``` | ||
|
|
||
| Example dom atom that registers a teardown callback: | ||
| ```js | ||
| let card = { | ||
| name: 'atom-with-teardown-callback', | ||
| type: 'dom', | ||
| render({env, options, value, payload}) { | ||
| env.onTeardown(() => { | ||
| console.log('tearing down atom named: ' + env.name); | ||
| }); | ||
| } | ||
| }; | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| # Renderers | ||
|
|
||
| All of the officially-supported mobiledoc renderers have the same signature and methods. | ||
| To instantiate a renderer, call its constructor with an object of options that has any of the following optional properties: | ||
|
|
||
| * `atoms` [array] - The atoms that your mobiledoc includes and that the renderer will encounter | ||
| * `cards` [array] - The cards that your mobiledoc includes and that the renderer will encounter | ||
| * `cardOptions` [object] - Options to be passed to the card `render` (or `edit`) function and atoms `render` function | ||
| * `unknownAtomHandler` [function] - This function is called (with the same arguments as `render`) whenever the renderer encounters an atom that doesn't | ||
| match one of the `atoms` it has been provided | ||
| * `unknownCardHandler` [function] - This function is called (with the same arguments as `render`) whenever the renderer encounters a card that doesn't | ||
| match one of the `cards` it has been provided | ||
|
|
||
| An instance of a renderer has one method, `render`. This method accepts a mobiledoc and returns an object with two properties: | ||
| * `result` [mixed] - The rendered result. Its type depends on the renderer, and can be a DOM Node (dom renderer) or a string (html or text renderers) | ||
| * `teardown` [function] - Call this function to tear down the rendered mobiledoc. The dom renderer will remove the rendered dom from the screen. All renderers will call | ||
| the card teardown callbacks that were registered using `env.onTeardown(callbackFunction)` | ||
|
|
||
| Example usage of a renderer: | ||
| ```js | ||
| let renderer = new DOMRenderer({atoms: [atom1, atom2], cards: [card1, card2], cardOptions: {foo: 'bar'}); | ||
| let rendered = renderer.render(mobiledoc); | ||
|
|
||
| document.body.appendChild(renderered.result); | ||
|
|
||
| // later... | ||
|
|
||
| rendered.teardown(); // removes the rendered items, calls teardown hooks | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters