From 47a02b773548cd67dfefc716ecca69f7f71d87f8 Mon Sep 17 00:00:00 2001 From: Michael Brade Date: Fri, 15 Jan 2016 17:55:40 -0800 Subject: [PATCH] README - I like documentation, so I started writing.... --- README.md | 298 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) diff --git a/README.md b/README.md index e69de29..8fe6e4a 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,298 @@ + +# API + +`derby-templates` exports four members: + + * a context api (`contexts`) + * an expression api (`expressions`) + * operator functions (`operatorFns`) + * and a template api (`templates`) + +Each of those are explained in the following sections. + + +## Contexts + +The `contexts` member has two prototypes: + +* `ContextMeta` +* `Context` + +#### Context + +A context used for TODO + +A context always has two properties: + +* `meta`: properties which are globally inherited for the entire page +* `controller`: The page or component. Must have a `model` property with a `data` property. + + +Optionally, the following properties may be defined: + +* `parent`: containing context +* `unbound`: boolean set to true when bindings should be ignored +* `expression`: the expression for a block +* `alias`: alias name for the given expression (`ExpressionMeta::as`) +* `keyAlias`: alias name for the index or iterated key (`ExpressionMeta::keyAs`) +* `item`: for `Context::eachChild`: the index of the `each` at render time + +* for `Context::viewChild`: + + - `view`: reference to the current view + - `attributes`: attribute values passed to the view instance + - `hooks`: MarkupHooks to be called after insert into DOM of component + - `initHooks`: MarkupHooks to be called immediately before init of component + +* `_id`: used in `EventModel` + + + +## Expressions + +The `expressions` member has four functions: + +* lookup +* templateTruthy +* pathSegments +* renderValue + +and all possible expression prototypes: + +* literals +* paths +* relative paths +* aliases +* attribute paths +* bracket expressions +* ... + +See below for the details. + + +#### lookup +#### templateTruthy + + +#### pathSegments + +Iterate through an array of segments and return a new array with each `segment`, or `segment.item` if available. + +#### renderValue + + + +#### `_outerDependency` + + +#### `ExpressionMeta` + +In Derby, templates can contain expressions introduced by `{{ }}`. `ExpressionMeta` holds everything but the path of the +expression. + +* `source`: the full original expression between `{{ }}` +* `blockType`: if the expression starts a block, one of: `if`, `else if`, `else`, `unless`, `each`, `bound`, `unbound`, `with`, `on` +* `isEnd`: `true` if it was an end tag (`{{/}}` or `{{/if}}`), `false` otherwise +* `as`: the name of the alias to be created; starts with `#` (e.g. `#alias` if expression ended with `as #alias`) +* `keyAs`: in case of `each ... as #v, #i`, this is name for the index key or iterated key, `#i` in this case +* `unescaped`: +* `bindType`: +* `valueType`: + + +#### Expression + +Every expression inherits the `Expression` prototype. + +TODO: serialize() + + +#### LiteralExpression + +Represents any valid JavaScript literal expression. Examples: +```js +56.8e-4 // floating-point +"string" // String +["arr", "ay"] // Array +{ key: "value" } // Object +true // boolean +/a+b/ // RegExp +``` + + + +#### PathExpression + +Represents a simple JSON path expression to lookup a value in an object hierarchy. Steps in the hierarchy are called +"segment" and are separated by a dot. Example: +``` +_page.color +``` + +```js +new PathExpression(['_page', 'color']) +``` + + + +#### RelativePathExpression + +Relative view paths begin with `this`. They refer to the expression in the containing block. + +``` +this.color +``` + +```js +new RelativePathExpression(['color']) +``` + + +#### AliasPathExpression + +Aliases label path expressions. They must begin with a hash (`#`) character to make it more obvious whether a path is an +alias or a model value. Each of the block types support defining aliases with the `as` keyword. + +Aliases are more explicit than relative paths and make it possible to refer to the scope of a parent block. + +``` +#page.color +``` + +```js +new AliasPathExpression('#page', ['color']) +``` + +#### AttributePathExpression + +Views can be passed values as attributes. These attributes are accessed via paths that start with an at sign (`@`). +Example: + +``` +@style.width +``` + +creates the following `AttributePathExpression`: + +```js +new AttributePathExpression('style', ['width']) +``` + + +#### BracketsExpression + +Represents an expression that contains member access through brackets. The top-level `BracketsExpression` represents the +last set of brackets. + +CTOR: TODO + +Example: + +```js +obj[style].en[v] +``` + +would be represented by: + +```js +new BracketsExpression( + new BracketsExpression( + new PathExpression(['obj']), + new PathExpression(['style']), + ['en']), + new expressions.PathExpression(['v'])) +``` + + + +#### FnExpression + +#### OperatorExpression + +Inherits `FnExpression`. + +#### NewExpression + +Inherits `FnExpression`. + +#### SequenceExpression + +Inherits `OperatorExpression`. + + +#### ScopedModelExpression + + + + + + +## operatorFns + +Exports two members: `get` and `set`. + +get: +* !U -U +U ~U typeofU +* || && | ^ & == != === !== < > <= >= instanceof in << >> >>> + - * / % ? , [] {} + +set: +* !U -U +* == === in + - * / + + + + + + + +## templates + +Template objects can directly create HTML for server rendering or DOM nodes for client rendering. + +The `templates` member exposes the following properties. + +* all `saddle` properties + +#### View (inherits saddle.Template) + +* `View(views, name, source, options)`: CTOR, called by `Views::register()`, for instance. + * `views`: the `Views` object, there is only one per App. + * `name`: + * `source`: + * `options`: +* `type`: constant string: `'View'` +* `get(context, unescaped)`: return the html of the view in the given `context` +* `getFragment(context, binding)`: return the view as a DocumentFragment in the given `context`. `binding`: TODO +* `appendTo`: +* `attachTo`: +* `dependencies`: +* `parse`: implemented only if `derby-parsing` is loaded + + + + +#### ViewInstance +#### DynamicViewInstance +#### ParentWrapper + +#### Views + +Manages all views for a Derby app. + +* find +* `register(name, source, options)`: register a new view. See `View` CTOR for explanation of arguments. +* `serialize()` +* findErrorMessage + + +#### MarkupHook +#### ElementOn +#### ComponentOn +#### ComponentMarker +#### AsProperty +#### AsObject +#### AsObjectComponent +#### AsArray +#### AsArrayComponent + +#### emptyTemplate