Overview
This is a javascript library which aims at improving your project's documentation. If you're writing a library that can have plugins, using `mentDoc.js`, you can have all the documentation of your plugins in one place. This will make navigating your plugins' docs much easier, since they would be all on the same site.
`mentDoc.js` allows you to `compile` some html and then `execute` it. The html can have `commands` with `directives` in it, which can manipulate the page they're being executed in.
```html Test: This will be appended to ".example1" once executed ```
This is a live demo of the above example Test:Usage API
`mentDoc.js` exposes a global variable called `mentDoc`, which you can use do compile html into `Commands`. You can then your execute those `Commands` using their public API. The following sections detail all the methods and properties you have access to. If you're going to just use mentDoc, just read `mentDoc.compile` and `Command.execute()` in the API section If you want to develop plugins for mentDoc, read everything (though you can skip the `other` section)
## mentDoc ###> `mentDoc.compile( html )` Using this method, you can compile some `html`, which will return you a `Command` object. You can then execute that `Command` object as many times as you want.
```js var rootCommand = mentDoc.compile('Will be appended once executed'); ```
##### Parameters: * html – {String} – The `html` to parse and extract `commands` of. ##### Returns: * {Command} – a root `Command` that you can execute. ###> `other` A list of all other properties/methods on the `mentDoc` object, if you're curious: * `.addDirective(name, info)` – a method that allows you to add custom directives, more details in the [Adding Your Custom Directives](#adding-custom-directives) section * `.normalizeAttr(name)` – a method that normalizes attributes. Given `data-some-attr`, it returns `someAttr`. * `.Command(el, parent)` – the `Command` class * `.forEach(obj, iterator, context)` – allows you to iterate through an array or object * `.isArray(obj)` – returns whether `obj` is an array * `.isObject(obj)` – returns whether `obj` is an object. Doesn't include `null` * `.isFn(fn)` – returns whether `fn` is a function * `.makeInherit(obj)` – same thing as ES5's `Object.create(obj)` * `.priorityAlias` – an object used for priority aliasing, where `high` priority is stored to be `10` * `.regDirectives` – an object holding all registered directives (key: name => value: directiveInfo) - - -
##Command `Command` is a class which represents a `u` element. When some `html` is being compiled, each time a `u` element is encountered a new `Command` instance is created. ###> `.execute()` Executes the directives that were set on the `u` element, as well as any child `Command`
```js var rootCommand = mentDoc.compile('Will be appended once executed'); rootCommand.execute(); //this will append the text above to the body ```
##### Returns: * {Command} – itself, for chaining. ###> `.el` The `DOM` element that this `Command` instance represents. ###> `.parent` The parent `Command` of the current `Command`. Note This is NOT the `DOM parentNode`, but the parent `Command`: Independently of how many `DOM parentNodes` separate them. ###> `.attrs` A normalized list of the attributes specified on the `.el`. Any `data-` or `x-` is removed from the attribute name, and is transformed to camelCase. The `key` is the attribute `name`, and the `value` is the attribute `value`.
```js aCommand.attrs["appendTo"] === "body"; ```
###> `.children` An array of child `Commands`. Note This is NOT the `DOM childNodes`, but the child `Commands`: Independently of how many `DOM childNodes` separate them. ###> `.data` An object in which directives can store any data they want. Note `.data` prototypically inherits from `.parent.data`, so anything set on the parent's `.data` will be accessible from child `Commands`. ###> `other` A list of all other properties/methods on the `Command` object and its instances, if you're curious: * `.isRoot` – a boolean indicating whether this `Command` is a root command or not * `.refreshAttrs()` – refreshes the `.attrs` object. Called by the constructor * `.updateChildren()` – refreshes the `.children` array. Called by the constructor * `.executeChildren()` – executes the child `Commands`. Called by `.execute` * `._loopThroughEl()` – used by `.updateChildren()` to iterate through `childNodes` * `._sortedDirectives()` – used by `.execute()` to get a list of directives sorted by their priority * `Command.isCommandEl(el)` – a static method that returns true if the `el` represents a `Command` element
Default Directives
Here is a list of the directives that are bundled in `mentDoc.js` by default. You can always overwrite them or add your own if you want to, simply read the [Adding Your Custom Directives](#adding-custom-directives) section to know how. ###> `in-el="{selector}"` Using the `in-el` directive, you can specify the context of all DOM manipulations that occur inside the element.
```html [external] ```
###> `append-to="{selector}"` Using the `append-to` directive, you can appended content to elements in the page. You may specify the scope using the `in-el` directive.
```html ```
###> `empty="{selector}"` Using the `empty` directive, you can empty the content of elements on the page. You may specify the scope using the `in-el` directive.
```html ```
###> `remove="{selector}"` Using the `remove` directive, you can remove elements from the page. You may specify the scope using the `in-el` directive.
```html ```
###> `markdown` Using the `markdown` directive, you can write `markdown` instead of `html` for your docs. This directives uses [PageDown](https://code.google.com/p/pagedown/) to convert `markdown` to `html` It also uses [PageDown's Sanitizer](https://code.google.com/p/pagedown/source/browse/Markdown.Sanitizer.js), as well as [PageDown Extra](https://github.com/jmcmanus/pagedown-extra) for awesome goodness. It also assumes you have [Google Code Prettify](https://code.google.com/p/google-code-prettify/) if you ever want to use \`\`\` for code blocks in your `markdown` Since having indentation in `markdown` forces the text to be interpreted as code, a new `markdown` feature is added by this directive. The directive searches for the first line with text on it, and shift all indentation to the left, making that the text on that line have 0 indentation.
```html ## This wouldn't become a h2 with the indentation behind it The directives makes the indentation start ← RIGHT HERE even though in the source code it's written after 9 level of indentation ```
- `.markdown.convertHtml(markdown)` – Added by the `markdown` directive, it converts `markdown` to `html`
Live demo `mentDoc.markdown.convertHtml(markdown)` is defined by this directive's code. So I decided to write a `mentDoc` document, compile it, and execute it.
- `.markdown.convertHtml(markdown)` – Added by the `markdown` directive, it [...]
This means that if I remove this section that covers the `markdown` directive, the documentation of `mentDoc.markdown.convertHtml(markdown)` is removed automatically from way up there.
Adding Your Custom Directives
Just like the `append-to="..."` and the `markdown` directives are included by default in `mentDoc`, you can add your own custom directives. To do so, you will need to use the `mentDoc.addDirective(name, info)` method. For a more detailed documentation of the parameters passed to `.addDirective`: ###> `name` {String} – The normalized name of your directive, in `camelCase`. Example: if you want your directive to be invoked with a `append-to` attribute in html, then pass in `appendTo` as a `name`. ###> `info` {Object|Function} – The info related to the directive. If an Object is passed, than it can have any of these properties: * priority _(default:`"default"`)_ – {Number|String} – the priority of the directive for when the `Command` is executed. A directive with a priority of `1` gets executed before a directive with a directive of `2`. Instead of passing a number, you can pass one of the following Strings: - `"high"` – equivalent to `10` - `"medium"` – equivalent to `20` - `"low"` – equivalent to `30` - `"default"` – equivalent to `30` Use Case `priority` makes sure that `empty` always gets executed before `append-to`. * execute(el, value, command) _(optional)_ – (Function) – a function that gets called every time the `Command` get executed. The function is passed the following parameters: - `el` – the `DOM` element the directive was set on - `value` – the value of the attribute the directive is associated with - `command` – the `Command` object the directive is associated with. (See the `Command`[ API section](#api-command)) * encounter(el, value, command) _(optional)_ – (Function) – a function that gets called every time the directive is encountered during compilation process. The function is passed the following parameters: - `el` – the `DOM` element the directive was encountered on - `value` – the value of the attribute the directive is associated with - `command` – the `Command` object the directive is associated with. (See the `Command`[ API section](#api-command)) Note The `command` would probably not be fully formed since `.encounter` is called in the `compile` process Passing a Function is a shorthand for passing an object with just an `execute` property.
```js mentDoc.addDirective("yourCustomDirective", { execute: function(el, value, command) { //... } }); // EQUIVALENT TO: mentDoc.addDirective("yourCustomDirective", function(el, value, command) { //... }); ```