From 1daef8b965661107b51007c009317319170e60c8 Mon Sep 17 00:00:00 2001 From: lsimone Date: Tue, 30 Sep 2014 18:22:24 +0200 Subject: [PATCH] completing api docs adding the missing paragraphs and some formatting --- docs/api/index.md | 170 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 136 insertions(+), 34 deletions(-) diff --git a/docs/api/index.md b/docs/api/index.md index ec3fbfd..ab98927 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -34,7 +34,28 @@ The `div` reference can be either: ## Compiler usage and options -TBD +This module compiles a template and returns the JS compiled string and a list of errors. + +It accepts 3 parameters: +* `template {String}` the template file content as a string. +* `path {String}` path of a file being compiled (optional - used for error messages). +* `options {Object}` supported options are: + * `includeSyntaxTree {Boolean}` if true, the result object will contain the syntax tree generated by the compiler. + * `bypassJSvalidation {Boolean}` if true, the validation of the generated JS file (including non-template code) is bypassed - default:false. + * `mode {String}` the type of module system the code shold comply with: either "commonJS" or "global" + * `globalRef {String}` the name of the runtime global reference when the "global" mode is used (default: "hsp") + + +The returned object contains: +* `errors {Array}` the error list - each error having the following structure: + * `description {String}` a message describing the error + * `line {Number}` the error line number + * `column {Number}` the error column number + * `code {String}` a code extract showing where the error occurs (optional) +* `code {String}` the generated JavaScript code +* `syntaxTree {JSON}` the syntax tree generated by the parser (optional) +* `lineMap {Array}` array of the new line indexes; i.e. lineMap[3] returns the new line index for line 4 in the orginal file (lineMap[0] is always 0 as all line count starts at 1 for both input and output values). + ## Template statements @@ -790,16 +811,34 @@ var Child = klass({ User method called to properly clean a _destroyed_ instance. -##### Accessing parent class methods +##### Calling an overridden parent class method -TBD +In order to call a method `fakeMethod` of a parent class `fakeClass`, when it has been overridden, it is sufficient to call `fakeClass.fakeMethod()`, without using the `prototype` property, as it is done for the `$constructor` method in the following example. +```javascript +var ClassC = klass({ + $extends : ClassB, + $constructor : function (incr) { + ClassB.$constructor.call(this); + this.idx += incr; + } +}); +``` #### Model updates ##### Object update -TBD +To implement data-binding, Hashspace reprocesses JavaScript to introduce a partial polyfill to Object.observe and detect changes that occur to JavaScript objects. Hashspace actually uses a transpiler to encapsulate assignments with an internal `$set()` method that performs the assignment and notifies the potential observers. + +In the mid-term the $set() utility will become obsolete, once the Object.observe feature is implemented by all web-browsers, and Hashspace will rely on the browser's Object.observe implementation. + +The $set function has the following signature: + +`$set(object_or_array, propertyName_or_index, value);` + +In order to let the transpiler introduce the logic to observe an object, the latter has to be specified in the assignment as its father's property (i.e. `a.b = 3`). + ##### Array update @@ -826,11 +865,13 @@ array.splice2(2, 0, ['c', 'd']); // => ['a', 'b', 'c', 'd', 'e', 'f'] ##### hsp.refresh() -TBD +The refresh method automatically refreshes all templates that may have been impacted by changes in data structures. +It is automatically triggered by a setTimeout, thus it may be explicitly used in some uncommon cases only (when a refresh has to be forced before performing another operation). + ##### hsp.template() -TBD +This method does not need to be explicitly called because it is internally used to create template functions from the ones generated by the transpiler. --- @@ -953,65 +994,126 @@ log.addLogger(function(entry) { #### Create a `new TestContext()` -TBD +In order to write tests with hashtester, you need to instantiate a `TestContext` object +```javascript +var ht = require("hsp/utils/hashtester"); +var testCtxt = ht.newTestContext(); +``` --- #### Test context usage -TBD +A test context is a function object that exposes the following properties and methods: -##### Selector accessor `.()` -* ###### `.find()` +* ##### container: {DOMElement} + It contains a DOM element to insert the template in. - TBD -* ###### `.text()` +* ##### $set(container, property, value) - TBD + It performs the assignment, notifies the potential observers and forces an hashspace refresh. -* ###### `.value()` + Parameters: + * {Object} `container` the object that contains a property to be set + * {String} `property` the property to be set + * {Object} `value` the value to be assigned to the given property - TBD -* ###### `.attribute()` +* ##### $dispose() - TBD + This method is used when the test context has to be disposed, in order to destroy all the logs and objects, managed by the `SelectionWrapper` instance. -* ###### `.hasClass()` - TBD +* ##### logs(idx) -* ###### `.item()` + This method returns an array (if the parameter is not specified), otherwise it returns the corresponding log message. - TBD + Parameters: + * {integer} `idx` the position of the log message (first index = 0) -* ###### `.click()` + Furthermore, the logs object exposes the following method: + * ###### `clear()` + It resets the log message list. - TBD -* ###### `.dblclick()` +#### Selector accessor `.(selector)` - TBD +Using the `TestContext` function it is possible to retrive an array of DOM elements, filtered according to the provided selector (as it is done in jQuery by means of the `$` object); it returns a `SelectionWrapper` object. -* ###### `.type()` +i.e: +```javascript +var HEAD = testCtxt(".panel .head"); +``` - TBD +--- +#### `SelectionWrapper` Class -##### logs() +An instance of `SelectionWrapper` provides the following methods: -* ###### `.clear()` +* ###### `find(selector)` - TBD + It permits to further refine the selection by applying a new selector. -##### $set() + Parameters: + * {String} `selector`: the selector expression (jquery selector syntax) -TBD -##### $dispose() +* ###### `text(trim)` + + It returns the textual content of the selection (by recursively going through all DOM sub-nodes) and concatenates the different text node content. + + Parameters: + * {Boolean} `trim`: whether the returned text has to be trimmed - true by default + + +* ###### `value()` + + This method returns the value of input or textarea elements. + + +* ###### `attribute(attName)` + + It returns the value of an attribute of the selected node (it only works on single-element selections). + + Parameters: + * {String} `attName` the name of the attribute - e.g. "title" + + +* ###### `hasClass(cssClassName)` + + This method tells if the first element in the selection is assigned a specified CSS class. + + Parameters: + * {String} `cssClassName` the class name to check + + +* ###### `item(idx)` + + It returns the selection corresponding to the nth element in the selection. + + Parameters: + * {integer} `idx` the position of the element (first index = 0) + + +* ###### `click()` + + It simulates a click event on the selected element and triggers an hashspace refresh. + + +* ###### `dblclick()` + + It simulates a double click event on the selected element and triggers an hashspace refresh. + + +* ###### `type(text)` + + It simulates a type event and triggers an hashspace refresh + + Parameters: + * {String} `text` the text to be typed -TBD [CONTENT_END]