From 0c1e914fe04e1c03cdd9abfe982c89d1f6e3f120 Mon Sep 17 00:00:00 2001 From: Brian Moschel Date: Wed, 26 Mar 2014 23:48:16 -0500 Subject: [PATCH 01/66] setting up view/bindings for docco --- view/bindings/bindings.js | 84 ------------------- view/bindings/{ => doc}/bindings.md | 3 +- view/bindings/{ => doc}/can-event.html | 2 +- view/bindings/doc/can-event.md | 26 ++++++ view/bindings/doc/can-value.md | 51 +++++++++++ view/bindings/{ => doc}/hyperloop.html | 2 +- view/bindings/{ => doc}/input-checkbox.html | 2 +- view/bindings/{ => doc}/input-checkbox.md | 2 +- view/bindings/{ => doc}/input-radio.html | 2 +- view/bindings/{ => doc}/input-radio.md | 2 +- view/bindings/{ => doc}/input-text.html | 2 +- view/bindings/{ => doc}/select-multiple.md | 6 +- view/bindings/{ => doc}/select.html | 2 +- view/bindings/{ => doc}/select.md | 2 +- view/bindings/{ => doc}/select_multiple.html | 2 +- .../{ => doc}/select_multiple_string.html | 2 +- .../{ => doc}/select_multiple_undefined.html | 2 +- 17 files changed, 94 insertions(+), 100 deletions(-) rename view/bindings/{ => doc}/bindings.md (91%) rename view/bindings/{ => doc}/can-event.html (93%) create mode 100644 view/bindings/doc/can-event.md create mode 100644 view/bindings/doc/can-value.md rename view/bindings/{ => doc}/hyperloop.html (89%) rename view/bindings/{ => doc}/input-checkbox.html (93%) rename view/bindings/{ => doc}/input-checkbox.md (93%) rename view/bindings/{ => doc}/input-radio.html (93%) rename view/bindings/{ => doc}/input-radio.md (92%) rename view/bindings/{ => doc}/input-text.html (89%) rename view/bindings/{ => doc}/select-multiple.md (92%) rename view/bindings/{ => doc}/select.html (93%) rename view/bindings/{ => doc}/select.md (93%) rename view/bindings/{ => doc}/select_multiple.html (92%) rename view/bindings/{ => doc}/select_multiple_string.html (93%) rename view/bindings/{ => doc}/select_multiple_undefined.html (93%) diff --git a/view/bindings/bindings.js b/view/bindings/bindings.js index 9ef4ccc09c2..d9b5ca9e84e 100644 --- a/view/bindings/bindings.js +++ b/view/bindings/bindings.js @@ -1,59 +1,4 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { - - /** - * @function can.view.bindings.can-value can-value - * @parent can.view.bindings - * - * Sets up two way bindings in a template. - * - * @signature `can-value='KEY'` - * - * Binds the element's value or checked property to the value specified by - * key. Example: - * - * - * - * @param {can.Mustache.key} key A named value in the current scope. - * - * @body - * - * ## Use - * - * Add a `can-value="KEY"` attribute to an input or select element and - * the element's value will be cross-bound to an observable value specified by `KEY`. - * - * Depending on the element and the element's type, `can-value` takes on - * different behaviors. If an input element has a type - * not listed here, the behavior is the same as the `text` type. - * - * ## input type=text - * - * Cross binds the input's string text value with the observable value. - * - * @demo can/view/bindings/hyperloop.html - * - * ## input type=checkbox - * - * Cross binds the checked property to a true or false value. An alternative - * true and false value can be specified by setting `can-true-value` and - * `can-false-value` attributes. - * - * @demo can/view/bindings/input-checkbox.html - * - * ## input type='radio' - * - * If the radio element is checked, sets the observable specified by `can-value` to match the value of - * `value` attribute. - * - * @demo can/view/bindings/input-radio.html - * - * ## select - * - * Cross binds the selected option value with an observable value. - * - * @demo can/view/bindings/select.html - * - */ can.view.attr("can-value", function (el, data) { var attr = el.getAttribute("can-value"), @@ -111,35 +56,6 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { } }; - /** - * @function can.view.bindings.can-EVENT can-EVENT - * @parent can.view.bindings - * - * @signature `can-EVENT='KEY'` - * - * Specify a callback function to be called on a particular event. - * - * @param {String} EVENT A event name like `click` or `keyup`. If you are - * using jQuery, you can listen to jQuery special events too. - * - * @param {can.Mustache.key} key A named value in the current scope. The value - * should be a function. - * - * @body - * - * ## Use - * - * By adding `can-EVENT='KEY'` to an element, the function pointed to - * by `KEY` is bound to the element's `EVENT` event. The function - * is called back with: - * - * - `context` - the context of the element - * - `element` - the element that was bound - * - `event` - the event that was triggered - * - * @demo can/view/bindings/can-event.html - * - */ can.view.attr(/can-[\w\.]+/, function (el, data) { var attributeName = data.attributeName, diff --git a/view/bindings/bindings.md b/view/bindings/doc/bindings.md similarity index 91% rename from view/bindings/bindings.md rename to view/bindings/doc/bindings.md index 6b116abe275..b9f4dff9899 100644 --- a/view/bindings/bindings.md +++ b/view/bindings/doc/bindings.md @@ -1,5 +1,6 @@ @page can.view.bindings @parent canjs +@link ../docco/bindings.html docco Provides template event bindings and two-way bindings. @@ -25,4 +26,4 @@ call a function in a [can.Mustache Mustache] [can.view.Scope scope] when an even Two-way bindings are documented by [can.view.bindings.can-value can-value]. This lets you listen to when element changes its value and automatically update an observable property. -@demo can/view/bindings/hyperloop.html \ No newline at end of file +@demo can/view/bindings/doc/hyperloop.html \ No newline at end of file diff --git a/view/bindings/can-event.html b/view/bindings/doc/can-event.html similarity index 93% rename from view/bindings/can-event.html rename to view/bindings/doc/can-event.html index 5b69bcf0a01..5f06c4dc949 100644 --- a/view/bindings/can-event.html +++ b/view/bindings/doc/can-event.html @@ -1,5 +1,5 @@
- + + + - + + - + - + - + - + + + + diff --git a/view/bindings/doc/input-checkbox.md b/view/bindings/doc/input-checkbox.md index 3fda878427c..df1f3784592 100644 --- a/view/bindings/doc/input-checkbox.md +++ b/view/bindings/doc/input-checkbox.md @@ -5,9 +5,7 @@ Cross bind a value to a checkbox. @signature `` -Cross binds the checked property to a true or false value. An alternative -true and false value can be specified by setting `can-true-value` and -`can-false-value` attributes. +Cross binds the checked property to a true or false value. @param {can.Mustache.key} KEY A named value in the current scope. @@ -19,4 +17,16 @@ true and false value can be specified by setting `can-true-value` and ## Use -@demo can/view/bindings/doc/input-checkbox.html \ No newline at end of file +@demo can/view/bindings/doc/input-checkbox.html + +## Using can-true-value + +An alternative true and false value can be specified by setting `can-true-value` and +`can-false-value` attributes. This is used for setting up a "boolean" property that only has two possible valid values, +whose values are modelled by the true/false checked property of a checkbox, as in the following example: + + + +In this case, the data passed in contains a 'sex' property which is either 'male' or 'female'. Specifying the string values for true and false in the attributes forces the data to two way bind using these string properties. + +@demo can/view/bindings/doc/input-checkbox-trueval.html \ No newline at end of file From 64848e58e7719a496f2f784b70e06634d0a77fc1 Mon Sep 17 00:00:00 2001 From: Brian Moschel Date: Mon, 31 Mar 2014 00:45:53 -0500 Subject: [PATCH 10/66] fixing up docco for bindings.js --- view/bindings/bindings.js | 95 ++++++++++++++++++---------------- view/bindings/doc/can-event.md | 29 +---------- 2 files changed, 51 insertions(+), 73 deletions(-) diff --git a/view/bindings/bindings.js b/view/bindings/bindings.js index a1dcff4e772..acb44d55642 100644 --- a/view/bindings/bindings.js +++ b/view/bindings/bindings.js @@ -1,17 +1,21 @@ -// # bindings.js -// `can.view.bindings`: In-template event bindings and two-way bindings +// # can/view/bindings/bindings.js +// +// This file defines the `can-value` attribute for two-way bindings and the `can-EVENT` attribute +// for in template event bindings. These are usable in any mustache template, but mainly and documented +// for use within can.Component. steal("can/util", "can/view/mustache", "can/control", function (can) { // ## can-value // Implement the `can-value` special attribute // - // Usage: <input can-value="name" /> + // ### Usage + // + // // - // When a view engine finds this attribute, it will call this callback + // When a view engine finds this attribute, it will call this callback. The value of the attribute + // should be a string representing some value in the current scope to cross-bind to. can.view.attr("can-value", function (el, data) { - // What is the value of this attribute? It should be a string representing - // some value in the current scope to cross-bind to. var attr = el.getAttribute("can-value"), // Turn the attribute passed in into a compute. If the user passed in can-value="name" and the current // scope of the template is some object called data, the compute representing this can-value will be the @@ -23,14 +27,15 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { trueValue, falseValue; - // Depending on the type of element, this attribute has different behavior - // - // If we're an input type... + // Depending on the type of element, this attribute has different behavior. can.Controls are defined (further below + // in this file) for each type of input. This block of code collects arguments and instantiates each can.Control. There + // is one for checkboxes/radios, another for multiselect inputs, and another for everything else. if (el.nodeName.toLowerCase() === "input") { if (el.type === "checkbox") { // If the element is a checkbox and has an attribute called "can-true-value", // set up a compute that toggles the value of the checkbox to "true" based on another attribute. - // For example, <input type='checkbox' can-value='foo' can-true-value='trueVal' /> + // + // if (can.attr.has(el, "can-true-value")) { trueValue = el.getAttribute("can-true-value"); } else { @@ -124,16 +129,16 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { return scopeData.value.call(scopeData.parent, data.scope._context, can.$(this), ev); }; - // This code adds support for special event types, like can-enter="foo". + // This code adds support for special event types, like can-enter="foo". special.enter (or any special[event]) is + // a function that returns an object containing an event and a handler. These are to be used for binding. For example, + // when a user adds a can-enter attribute, we'll bind on the keyup event, and the handler performs special logic to + // determine on keyup if the enter key was pressed. if (special[event]) { - // special.enter (or any special[event]) is a function that returns an object containing an event and a handler. - // These are to be used for binding. For example, when a user adds a can-enter attribute, we'll bind on the - // keyup event, and the handler performs special logic to determine on keyup if the enter key was pressed. var specialData = special[event](data, el, handler); handler = specialData.handler; event = specialData.event; } - // bind the handler defined above to the element we're currently processing and the event name provided in this + // Bind the handler defined above to the element we're currently processing and the event name provided in this // attribute name (can-click="foo") can.bind.call(el, event, handler); }); @@ -152,33 +157,32 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { // on an input, the callback above instantiates this Value control on the input element. var Value = can.Control.extend({ init: function () { - // handle selects by calling set after this thread so the rest of the element can finish rendering + // Handle selects by calling `set` after this thread so the rest of the element can finish rendering. if (this.element[0].nodeName.toUpperCase() === "SELECT") { - // need to wait until end of turn ... setTimeout(can.proxy(this.set, this), 1); } else { this.set(); } }, - // if the live bound data changes, call set the reflect this in the dom + // If the live bound data changes, call set to reflect the change in the dom. "{value} change": "set", set: function () { - //this may happen in some edgecases, esp. with selects that are not in DOM after the timeout has fired + // This may happen in some edgecases, esp. with selects that are not in DOM after the timeout has fired if (!this.element) { return; } var val = this.options.value(); - // set the element's value to match the attribute that was passed in + // Set the element's value to match the attribute that was passed in this.element[0].value = (typeof val === 'undefined' ? '' : val); }, - // if the input value changes, ... + // If the input value changes, this will set the live bound data to reflect the change. "change": function () { - //this may happen in some edgecases, esp. with selects that are not in DOM after the timeout has fired + // This may happen in some edgecases, esp. with selects that are not in DOM after the timeout has fired if (!this.element) { return; } - // set the value of the attribute passed in to reflect what the user typed + // Set the value of the attribute passed in to reflect what the user typed this.options.value(this.element[0].value); } }), @@ -187,23 +191,22 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { // on a checkbox, the callback above instantiates this Checked control on the checkbox element. Checked = can.Control.extend({ init: function () { - // if its not a checkbox, its a radio input + // If its not a checkbox, its a radio input this.isCheckbox = (this.element[0].type.toLowerCase() === "checkbox"); this.check(); }, - // value is the compute representing the can-value for this element. For example can-value="foo" and current + // `value` is the compute representing the can-value for this element. For example can-value="foo" and current // scope is someObj, value is the compute representing someObj.attr('foo') "{value} change": "check", - "{trueValue} change": "check", - "{falseValue} change": "check", check: function () { if (this.isCheckbox) { var value = this.options.value(), trueValue = this.options.trueValue || true; - + // If `can-true-value` attribute was set, check if the value is equal to that string value, and set + // the checked property based on their equality. this.element[0].checked = (value === trueValue); } - // its a radio input type + // Its a radio input type else { var setOrRemove = this.options.value() === this.element[0].value ? "set" : "remove"; @@ -217,12 +220,11 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { "change": function () { if (this.isCheckbox) { - // If the checkbox is checked and the trueValue compute (if it was used) is true, set value to true. - // - // If its not checked and the falseValue compute (if it was used) is false, set value to false. + // If the checkbox is checked and can-true-value was used, set value to the string value of can-true-value. If + // can-false-value was used and checked is false, set value to the string value of can-false-value. this.options.value(this.element[0].checked ? this.options.trueValue : this.options.falseValue); } - // radio input type + // Radio input type else { if (this.element[0].checked) { this.options.value(this.element[0].value); @@ -243,26 +245,27 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { var newVal = this.options.value(); + + // When given a string, try to extract all the options from it (i.e. "a;b;c;d") if (typeof newVal === 'string') { - //when given a string, try to extract all the options from it (i.e. "a;b;c;d") newVal = newVal.split(this.delimiter); this.isString = true; - } else if (newVal) { - //when given something else, try to make it an array and deal with it + } + // When given something else, try to make it an array and deal with it + else if (newVal) { newVal = can.makeArray(newVal); } - // make an object containing all the options passed in for convenient lookup + // Make an object containing all the options passed in for convenient lookup var isSelected = {}; can.each(newVal, function (val) { isSelected[val] = true; }); - // go through each <option/> element + // Go through each <option/> element, if it has a value property (its a valid option), then + // set its selected property if it was in the list of vals that were just set. can.each(this.element[0].childNodes, function (option) { - // if it has a value property (meaning it is a valid option) if (option.value) { - // set its value to true if it was in the list of vals that were set option.selected = !! isSelected[option.value]; } @@ -285,7 +288,7 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { }, // Called when the user changes this input in any way. 'change': function () { - // get an array of the currently selected values + // Get an array of the currently selected values var value = this.get(), currentValue = this.options.value(); @@ -293,11 +296,13 @@ steal("can/util", "can/view/mustache", "can/control", function (can) { if (this.isString || typeof currentValue === "string") { this.isString = true; this.options.value(value.join(this.delimiter)); - } else if (currentValue instanceof can.List) { - // If the compute is a can.List, replace its current contents with the new array of values + } + // If the compute is a can.List, replace its current contents with the new array of values + else if (currentValue instanceof can.List) { currentValue.attr(value, true); - } else { - // Otherwise set the value to the array of values selected in the input. + } + // Otherwise set the value to the array of values selected in the input. + else { this.options.value(value); } diff --git a/view/bindings/doc/can-event.md b/view/bindings/doc/can-event.md index b441883411e..eb2cd0c9140 100644 --- a/view/bindings/doc/can-event.md +++ b/view/bindings/doc/can-event.md @@ -35,31 +35,4 @@ can-enter is a special event that calls its handler whenever the enter key is pr -The above template snippet would cause the save method (in the [can.Mustache Mustache] [can.view.Scope scope]) whenever the user hits the enter key on this input. - -### Create Your Own Special Event Type - -You can add your own special events to can.view.bindings. The AMD module returned by the can/view/bindings plugin is an object called `special`. It contains all the special events. To add your -own, add a property to special like the following: - - special.esc = function (data, el, original) { - return { - event: "keyup", - handler: function (ev) { - if (ev.keyCode === 27) { - return original.call(this, ev); - } - } - }; - } - -The above example adds a can-esc binding that can be used in a template like: - - - -The special object expects a function that is called with the mustache scope data, the element, and the original event handler (the 'cancel' method in our above example). - -It is expected to return an object containing: - - - `event`: which native DOM event type you want to bind to - - `handler`: a function which performs logic to determine if your special event requirements are met, and if so, call the original handler \ No newline at end of file +The above template snippet would cause the save method (in the [can.Mustache Mustache] [can.view.Scope scope]) whenever the user hits the enter key on this input. \ No newline at end of file From cab0a6ca941a296f1416f0d28e11024efddfb334 Mon Sep 17 00:00:00 2001 From: Veljko Dragsic Date: Mon, 31 Mar 2014 01:33:03 +0200 Subject: [PATCH 11/66] Inline docs for can/route/pushstate, #838 --- route/pushstate/pushstate.js | 81 +++++++++++++++++++++++------------- 1 file changed, 53 insertions(+), 28 deletions(-) diff --git a/route/pushstate/pushstate.js b/route/pushstate/pushstate.js index 4ece56234ee..c65961964cc 100644 --- a/route/pushstate/pushstate.js +++ b/route/pushstate/pushstate.js @@ -1,8 +1,19 @@ -/*jshint maxdepth:6*/ +// # can/route/pushstate/pushstate.js +// +// Plugin for `can.route` which uses browser `history.pushState` support +// to update window's pathname instead of the `hash`. +// +// Registers itself as handler on `can.route`, intercepts `click` events +// on `` elements across document and accordingly updates `can.route` state +// and window's pathname. + steal('can/util', 'can/route', function (can) { "use strict"; + // Initialize plugin only if browser supports pushstate. if (window.history && history.pushState) { + + // Registers itself within `can.route.bindings`. can.route.bindings.pushstate = { /** * @property {String} can.route.pushstate.root @@ -38,21 +49,26 @@ steal('can/util', 'can/route', function (can) { * http://domain.com/filemanager/file-34234 * */ + + // Start of `location.pathname` is the root. + // (Can be configured via `can.route.bindings.pushstate.root`) root: "/", paramsMatcher: /^\?(?:[^=]+=[^&]*&)*[^=]+=[^&]*/, querySeparator: '?', + + // Intercepts clicks on `` elements and rewrites original `history` methods. bind: function () { - // intercept routable links - can.delegate.call(can.$(document.documentElement), 'a', 'click', anchorClickFix); + // Intercept routable links. + can.delegate.call(can.$(document.documentElement), 'a', 'click', anchorClickHandler); - // popstate only fires on back/forward. - // To detect when someone calls push/replaceState, we need to wrap each method. - can.each(['pushState', 'replaceState'], function (method) { + // Rewrites original `pushState`/`replaceState` methods on `history` and keeps pointer to original methods + can.each(methodsToOverride, function (method) { originalMethods[method] = window.history[method]; window.history[method] = function (state, title, url) { - // avoid doubled history states (with pushState) + // Avoid doubled history states (with pushState). var absolute = url.indexOf("http") === 0; var searchHash = window.location.search + window.location.hash; + // If url differs from current call original histoy method and update `can.route` state. if ((!absolute && url !== window.location.pathname + searchHash) || (absolute && url !== window.location.href + searchHash)) { originalMethods[method].apply(window.history, arguments); can.route.setState(); @@ -60,17 +76,21 @@ steal('can/util', 'can/route', function (can) { }; }); - // Bind to popstate for back/forward + // Bind to `popstate` event, fires on back/forward. can.bind.call(window, 'popstate', can.route.setState); }, + + // Unbinds and restores original `history` methods unbind: function () { - can.undelegate.call(can.$(document.documentElement), 'click', 'a', anchorClickFix); + can.undelegate.call(can.$(document.documentElement), 'click', 'a', anchorClickHandler); - can.each(['pushState', 'replaceState'], function (method) { + can.each(methodsToOverride, function (method) { window.history[method] = originalMethods[method]; }); can.unbind.call(window, 'popstate', can.route.setState); }, + + // Returns matching part of url without root. matchingPartOfURL: function () { var root = cleanRoot(), loc = (location.pathname + location.search), @@ -78,8 +98,10 @@ steal('can/util', 'can/route', function (can) { return loc.substr(index + root.length); }, + + // Updates URL by calling `pushState`. setURL: function (path) { - // keep hash if not in path, but in + // Keeps hash if not in path. if (includeHash && path.indexOf("#") === -1 && window.location.hash) { path += window.location.hash; } @@ -87,30 +109,31 @@ steal('can/util', 'can/route', function (can) { } }; - var anchorClickFix = function (e) { + // Handler function for `click` events. + var anchorClickHandler = function (e) { if (!(e.isDefaultPrevented ? e.isDefaultPrevented() : e.defaultPrevented === true)) { - // YUI calls back events triggered with this as a wrapped object + // YUI calls back events triggered with this as a wrapped object. var node = this._node || this; - // Fix for ie showing blank host, but blank host means current host. + // Fix for IE showing blank host, but blank host means current host. var linksHost = node.host || window.location.host; - // if link is within the same domain + + // If link is within the same domain and descendant of `root` if (window.location.host === linksHost) { - // if link is a descendant of `root` var root = can.route._call("root"); if (node.pathname.indexOf(root) === 0) { - // remove `root` from url - var url = (node.pathname + node.search) - .substr(root.length); + + // Removes root from url. + var url = (node.pathname + node.search).substr(root.length); + // If a route matches update the data. var curParams = can.route.deparam(url); - // if a route matches if (curParams.hasOwnProperty('route')) { - // make it possible to have a link with a hash + // Makes it possible to have a link with a hash. includeHash = true; - // update the data window.history.pushState(null, null, node.href); - // test if you can preventDefault + + // Test if you can preventDefault // our tests can't call .click() b/c this - // freezes phantom + // freezes phantom. if (e.preventDefault) { e.preventDefault(); } @@ -119,6 +142,7 @@ steal('can/util', 'can/route', function (can) { } } }, + // Always returns clean root, without domain. cleanRoot = function () { var domain = location.protocol + "//" + location.host, root = can.route._call("root"), @@ -128,14 +152,15 @@ steal('can/util', 'can/route', function (can) { } return root; }, - // a collection of methods on history that we are overwriting + // Original methods on `history` that will be overwritten + methodsToOverride = ['pushState', 'replaceState'], + // A place to store pointers to original `history` methods. originalMethods = {}, - // used to tell setURL to include the hash because - // we clicked on a link + // Used to tell setURL to include the hash because we clicked on a link includeHash = false; + // Enables plugin, by default `hashchange` binding is used. can.route.defaultBinding = "pushstate"; - } return can; From ff33710ae46e9aa741bd2d54a5383d676ffd8105 Mon Sep 17 00:00:00 2001 From: Veljko Dragsic Date: Mon, 31 Mar 2014 14:42:05 +0200 Subject: [PATCH 12/66] jshint directive added back. --- route/pushstate/pushstate.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/route/pushstate/pushstate.js b/route/pushstate/pushstate.js index c65961964cc..c6ce50817ce 100644 --- a/route/pushstate/pushstate.js +++ b/route/pushstate/pushstate.js @@ -1,3 +1,5 @@ +/*jshint maxdepth:6*/ + // # can/route/pushstate/pushstate.js // // Plugin for `can.route` which uses browser `history.pushState` support From fd4f3bb6c324ff7c896b65d6ab14f73a6c79f14f Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Mon, 31 Mar 2014 09:43:06 -0500 Subject: [PATCH 13/66] doc updates for ejs #843 --- view/ejs/ejs.js | 109 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 95 insertions(+), 14 deletions(-) diff --git a/view/ejs/ejs.js b/view/ejs/ejs.js index 8311d7b7e82..957e8dd43b6 100644 --- a/view/ejs/ejs.js +++ b/view/ejs/ejs.js @@ -1,11 +1,18 @@ -steal('can/util', 'can/view', 'can/util/string', 'can/compute', 'can/view/scanner.js', 'can/view/render.js', function (can) { - // ## ejs.js - // `can.EJS` - // _Embedded JavaScript Templates._ - // Helper methods. +// # can/view/ejs/ejs.js +// +// `can.EJS`: Embedded JavaScript Templates +// +steal('can/util', + 'can/view', + 'can/util/string', + 'can/compute', + 'can/view/scanner.js', + 'can/view/render.js', +function (can) { + // ## Helper methods var extend = can.extend, EJS = function (options) { - // Supports calling EJS without the constructor + // Supports calling EJS without the constructor. // This returns a function that renders the template. if (this.constructor !== EJS) { var ejs = new EJS(options); @@ -25,12 +32,15 @@ steal('can/util', 'can/view', 'can/util/string', 'can/compute', 'can/view/scanne extend(this, options); this.template = this.scanner.scan(this.text, this.name); }; + // Expose EJS via the `can` object. can.EJS = EJS; /** * @add can.EJS * @prototype */ EJS.prototype. + // ## Render + // Render a view object with data and helpers. /** * @function can.EJS.prototype.render render * @parent can.EJS.prototype @@ -54,6 +64,19 @@ steal('can/util', 'can/view', 'can/util/string', 'can/compute', 'can/view/scanne return this.template.fn.call(object, object, new EJS.Helpers(object, extraHelpers || {})); }; extend(EJS.prototype, { + // ## Scanner + // Singleton scanner instance for parsing templates. See [scanner.js](scanner.html) + // for more information. + // + // ### Text + // + // #### Definitions + // + // * `outStart` - Wrapper start text for view function. + // + // * `outEnd` - Wrapper end text for view function. + // + // * `argNames` - Arguments passed into view function. /** * @hide * Singleton scanner instance for parsing templates. @@ -65,6 +88,9 @@ steal('can/util', 'can/view', 'can/util/string', 'can/compute', 'can/view/scanne argNames: '_CONTEXT,_VIEW', context: "this" }, + // ### Tokens + // + // An ordered token registry for the scanner. /** * @hide * An ordered token registry for the scanner. @@ -72,22 +98,34 @@ steal('can/util', 'can/view', 'can/util/string', 'can/compute', 'can/view/scanne * Each token is defined as: ["token-name", "string representation", "optional regexp override"] */ tokens: [ - ["templateLeft", "<%%"], // Template - ["templateRight", "%>"], // Right Template - ["returnLeft", "<%=="], // Return Unescaped - ["escapeLeft", "<%="], // Return Escaped - ["commentLeft", "<%#"], // Comment - ["left", "<%"], // Run --- this is hack for now - ["right", "%>"], // Right -> All have same FOR Mustache ... + // Template + ["templateLeft", "<%%"], + // Right Template + ["templateRight", "%>"], + // Return Unescaped + ["returnLeft", "<%=="], + // Return Escaped + ["escapeLeft", "<%="], + // Comment + ["commentLeft", "<%#"], + // Evaluate code + ["left", "<%"], + // Right -> All have same FOR Mustache ... + ["right", "%>"], ["returnRight", "%>"] ], + // ### Helpers helpers: [ /** * Check if its a func like `()->`. * @param {String} content */ { + // #### name + // Regex to see if its a func like `()->`. name: /\s*\(([\$\w]+)\)\s*->([^\n]*)/, + // #### fn + // Evaluate rocket syntax function with correct context. fn: function (content) { var quickFunc = /\s*\(([\$\w]+)\)\s*->([^\n]*)/, parts = content.match(quickFunc); @@ -96,6 +134,22 @@ steal('can/util', 'can/view', 'can/util/string', 'can/compute', 'can/view/scanne } } ], + // ### transform + // Transforms the EJS template to add support for shared blocks. + // Essentially, this breaks up EJS tags into multiple EJS tags + // if they contained unmatched brackets. + // + // For example, this doesn't work: + // + // `<% if (1) { %><% if (1) { %> hi <% } } %>` + // + // ...without isolated EJS blocks: + // + // `<% if (1) { %><% if (1) { %> hi <% } %><% } %>` + // + // The result of transforming: + // + // `<% if (1) { %><% %><% if (1) { %><% %> hi <% } %><% } %>` /** * @hide * Transforms the EJS template to add support for shared blocks. @@ -146,7 +200,8 @@ steal('can/util', 'can/view', 'can/util/string', 'can/compute', 'can/view/scanne } result.push(part.substring(last), '%>'); return result.join(''); - } // Otherwise return the original + } + // Otherwise return the original else { return '<%' + part + '%>'; } @@ -154,6 +209,32 @@ steal('can/util', 'can/view', 'can/util/string', 'can/compute', 'can/view/scanne } }) }); + + // ## Helpers + // By adding functions to can.EJS.Helpers.prototype, those functions will be available in the + // views. + // + // The following helper converts a given string to upper case: + // + // can.EJS.Helpers.prototype.toUpper = function(params) { + // return params.toUpperCase(); + // } + + // Use it like this in any EJS template: + + // `<%= toUpper('javascriptmvc') %>` + + // To access the current DOM element return a function that takes the element as a parameter: + + // can.EJS.Helpers.prototype.upperHtml = function(params) { + // return function(el) { + // $(el).html(params.toUpperCase()); + // } + // } + + // In your EJS view you can then call the helper on an element tag: + + // `
>
` EJS.Helpers = function (data, extras) { this._data = data; this._extras = extras; From 4386b2f21e751dd9d191b33cf17921cfa3059b00 Mon Sep 17 00:00:00 2001 From: Eli Morris-Heft Date: Mon, 31 Mar 2014 09:52:30 -0500 Subject: [PATCH 14/66] Docco documentation for can.Model. #839. --- model/model.js | 379 ++++++++++++++++++++++++++++++------------------- 1 file changed, 235 insertions(+), 144 deletions(-) diff --git a/model/model.js b/model/model.js index 4fbea13c916..a522b2601e5 100644 --- a/model/model.js +++ b/model/model.js @@ -1,70 +1,86 @@ -// this file should not be stolen directly steal('can/util', 'can/map', 'can/list', function (can) { - // ## model.js - // `can.Model` - // _A `can.Map` that connects to a RESTful interface._ - // - // Generic deferred piping function + // ## model.js + // (Don't steal this file directly in your code.) + + // ## pipe + // `pipe` lets you pipe the results of a successful deferred + // through a function before resolving the deferred. /** * @add can.Model */ - var pipe = function (def, model, func) { + var pipe = function (def, thisArg, func) { + // The piped result will be available through a new Deferred. var d = new can.Deferred(); def.then(function () { var args = can.makeArray(arguments), success = true; try { - args[0] = func.apply(model, args); + // Pipe the results through the function. + args[0] = func.apply(thisArg, args); } catch (e) { success = false; + // The function threw an error, so reject the Deferred. d.rejectWith(d, [e].concat(args)); } if (success) { + // Resolve the new Deferred with the piped value. d.resolveWith(d, args); } }, function () { + // Pass on the rejection if the original Deferred never resolved. d.rejectWith(this, arguments); }); + // `can.ajax` returns a Deferred with an abort method to halt the AJAX call. if (typeof def.abort === 'function') { d.abort = function () { return def.abort(); }; } + // Return the new (piped) Deferred. return d; }, + + // ## modelNum + // When new model constructors are set up without a full name, + // `modelNum` lets us name them uniquely (to keep track of them). modelNum = 0, + + // ## getId getId = function (inst) { - // Instead of using attr, use __get for performance. - // Need to set reading + // `can.__reading` makes a note that `id` was just read. can.__reading(inst, inst.constructor.id); + // Use `__get` instead of `attr` for performance. (But that means we have to remember to call `can.__reading`.) return inst.__get(inst.constructor.id); }, - // Ajax `options` generator function + + // ## ajax + // This helper method makes it easier to make an AJAX call from the configuration of the Model. ajax = function (ajaxOb, data, type, dataType, success, error) { var params = {}; - // If we get a string, handle it. + // A string here would be something like `"GET /endpoint"`. if (typeof ajaxOb === 'string') { - // If there's a space, it's probably the type. + // Split on spaces to separate the HTTP method and the URL. var parts = ajaxOb.split(/\s+/); params.url = parts.pop(); if (parts.length) { params.type = parts.pop(); } } else { + // If the first argument is an object, just load it into `params`. can.extend(params, ajaxOb); } - // If we are a non-array object, copy to a new attrs. + // If the `data` argument is a plain object, copy it into `params`. params.data = typeof data === "object" && !can.isArray(data) ? can.extend(params.data || {}, data) : data; - // Get the url with any templated values filled out. + // Substitute in data for any templated parts of the URL. params.url = can.sub(params.url, params.data, true); return can.ajax(can.extend({ @@ -74,84 +90,82 @@ steal('can/util', 'can/map', 'can/list', function (can) { error: error }, params)); }, - makeRequest = function (self, type, success, error, method) { + + // ## makeRequest + // This function abstracts making the actual AJAX request away from the Model. + makeRequest = function (modelObj, type, success, error, method) { var args; - // if we pass an array as `self` it it means we are coming from - // the queued request, and we're passing already serialized data - // self's signature will be: [self, serializedData] - if (can.isArray(self)) { - args = self[1]; - self = self[0]; + + // If `modelObj` is an Array, it it means we are coming from + // the queued request, and we're passing already-serialized data. + if (can.isArray(modelObj)) { + // In that case, modelObj's signature will be `[modelObj, serializedData]`, so we need to unpack it. + args = modelObj[1]; + modelObj = modelObj[0]; } else { - args = self.serialize(); + // If we aren't supplied with serialized data, we'll make our own. + args = modelObj.serialize(); } args = [args]; + var deferred, - // The model. - model = self.constructor, + model = modelObj.constructor, jqXHR; - // `update` and `destroy` need the `id`. - if (type !== 'create') { - args.unshift(getId(self)); + // When calling `update` and `destroy`, the current ID needs to be the first parameter in the AJAX call. + if (type === 'update' || type === 'destroy') { + args.unshift(getId(modelObj)); } - jqXHR = model[type].apply(model, args); - deferred = jqXHR.pipe(function (data) { - self[method || type + "d"](data, jqXHR); - return self; + // Make sure that can.Model can react to the request before anything else does. + deferred = pipe(jqXHR, modelObj, function (data) { + // `method` is here because `"destroyed" !== "destroy" + "d"`. + // TODO: Do something smarter/more consistent here? + modelObj[method || type + "d"](data, jqXHR); + return modelObj; }); - // Hook up `abort` - if (jqXHR.abort) { - deferred.abort = function () { - jqXHR.abort(); - }; - } - + // Attach the callbacks to the piped Deferred. deferred.then(success, error); return deferred; }, initializers = { - // makes a models function that looks up the data in a particular property + // ## models + // Returns a function that, when handed a list of objects, makes them into models and returns a model list of them. + // `prop` is the property on `instancesRawData` that has the array of objects in it (if it's not `data`). models: function (prop) { return function (instancesRawData, oldList) { - // until "end of turn", increment reqs counter so instances will be added to the store + // Increment reqs counter so new instances will be added to the store. + // (This is cleaned up at the end of the method.) can.Model._reqs++; + + // If there is no data, we can't really do anything with it. if (!instancesRawData) { return; } + // If the "raw" data is already a List, it's not raw. if (instancesRawData instanceof this.List) { return instancesRawData; } - // Get the list type. var self = this, + // `tmp` will hold the models before we push them onto `modelList`. tmp = [], - Cls = self.List || ML, - res = oldList instanceof can.List ? oldList : new Cls(), - // Did we get an `array`? - arr = can.isArray(instancesRawData), - - // Did we get a model list? - ml = instancesRawData instanceof ML, - // Get the raw `array` of objects. - raw = arr ? - - // If an `array`, return the `array`. - instancesRawData : - - // Otherwise if a model list. - (ml ? + // `ML` (see way below) is just `can.Model.List`. + ListClass = self.List || ML, + modelList = oldList instanceof can.List ? oldList : new ListClass(), - // Get the raw objects from the list. - instancesRawData.serialize() : + // Check if we were handed an Array or a model list. + rawDataIsArray = can.isArray(instancesRawData), + rawDataIsList = instancesRawData instanceof ML, - // Get the object's data. - can.getObject(prop || "data", instancesRawData)); + // Get the "plain" objects from the models from the list/array. + raw = rawDataIsArray ? instancesRawData : ( + rawDataIsList ? instancesRawData.serialize() : can.getObject(prop || "data", instancesRawData) + ); if (typeof raw === 'undefined') { throw new Error('Could not get any raw data while converting using .models'); @@ -163,34 +177,41 @@ steal('can/util', 'can/map', 'can/list', function (can) { } //!steal-remove-end - if (res.length) { - res.splice(0); + // If there was anything left in the list we were given, get rid of it. + if (modelList.length) { + modelList.splice(0); } + // If we pushed these directly onto the list, it would cause a change event for each model. + // So, we push them onto `tmp` first and then push everything at once, causing one atomic change event that contains all the models at once. can.each(raw, function (rawPart) { tmp.push(self.model(rawPart)); }); + modelList.push.apply(modelList, tmp); - // We only want one change event so push everything at once - res.push.apply(res, tmp); - - if (!arr) { // Push other stuff onto `array`. + // If there was other stuff on `instancesRawData`, let's transfer that onto `modelList` too. + if (!rawDataIsArray) { can.each(instancesRawData, function (val, prop) { if (prop !== 'data') { - res.attr(prop, val); + modelList.attr(prop, val); } }); } - // at "end of turn", clean up the store + // Clean up the store on the next turn of the event loop. (`this` is a model constructor.) setTimeout(can.proxy(this._clean, this), 1); - return res; + return modelList; }; }, + // ## model + // Returns a function that, when handed a plain object, turns it into a model. + // `prop` is the property on `attributes` that has the properties for the model in it. model: function (prop) { return function (attributes) { + // If there're no properties, there can be no model. if (!attributes) { return; } + // If this object knows how to serialize, parse, or access itself, we'll use that instead. if (typeof attributes.serialize === 'function') { attributes = attributes.serialize(); } @@ -201,20 +222,19 @@ steal('can/util', 'can/map', 'can/list', function (can) { } var id = attributes[this.id], + // 0 is a valid ID. model = (id || id === 0) && this.store[id] ? - this.store[id].attr(attributes, this.removeAttr || false) : new this(attributes); + // If this model is in the store already, just update it. + this.store[id].attr(attributes, this.removeAttr || false) : + // Otherwise, we need a new model. + new this(attributes); return model; }; } }, - // This object describes how to make an ajax request for each ajax method. - // The available properties are: - // `url` - The default url to use as indicated as a property on the model. - // `type` - The default http request type - // `data` - A method that takes the `arguments` and returns `data` used for ajax. - /** + /** * @static */ // @@ -224,6 +244,9 @@ steal('can/util', 'can/map', 'can/list', function (can) { }; }, + // ## parsers + // This object describes how to take the data from an AJAX request and prepare it for `models` and `model`. + // These functions are meant to be overwritten (if necessary) in an extended model constructor. parsers = { /** * @function can.Model.parseModel parseModel @@ -382,12 +405,14 @@ steal('can/util', 'can/map', 'can/list', function (can) { parseModels: parserMaker }, - // This object describes how to make an ajax request for each ajax method. - // The available properties are: - // `url` - The default url to use as indicated as a property on the model. - // `type` - The default http request type - // `data` - A method that takes the `arguments` and returns `data` used for ajax. + // ## ajaxMethods + // This object describes how to make an AJAX request for each ajax method (`create`, `update`, etc.) + // Each AJAX method is an object in `ajaxMethods` and can have the following properties: // + // - `url`: Which property on the model contains the default URL for this method. + // - `type`: The default HTTP request method. + // - `data`: A method that takes the arguments from `makeRequest` (see above) and returns a data object for use in the AJAX call. + /** * @function can.Model.bind bind * @parent can.Model.static @@ -413,7 +438,7 @@ steal('can/util', 'can/map', 'can/list', function (can) { * * new Task({name: "Dishes"}).save(); */ - // + // /** * @function can.Model.unbind unbind * @parent can.Model.static @@ -439,7 +464,7 @@ steal('can/util', 'can/map', 'can/list', function (can) { * You have to pass the same function to `unbind` that you * passed to `bind`. */ - // + // /** * @property {String} can.Model.id id * @parent can.Model.static @@ -644,14 +669,21 @@ steal('can/util', 'can/map', 'can/list', function (can) { * },{}); */ update: { + // ## update.data data: function (id, attrs) { attrs = attrs || {}; + + // `this.id` is the property that represents the ID (and is usually `"id"`). var identity = this.id; + + // If the value of the property being used as the ID changed, + // indicate that in the request and replace the current ID property. if (attrs[identity] && attrs[identity] !== id) { attrs["new" + can.capitalize(id)] = attrs[identity]; delete attrs[identity]; } attrs[identity] = id; + return attrs; }, type: "put" @@ -720,8 +752,10 @@ steal('can/util', 'can/map', 'can/list', function (can) { */ destroy: { type: 'delete', + // ## destroy.data data: function (id, attrs) { attrs = attrs || {}; + // `this.id` is the property that represents the ID (and is usually `"id"`). attrs.id = attrs[this.id] = id; return attrs; } @@ -989,25 +1023,32 @@ steal('can/util', 'can/map', 'can/list', function (can) { */ findOne: {} }, - // Makes an ajax request `function` from a string. - // `ajaxMethod` - The `ajaxMethod` object defined above. - // `str` - The string the user provided. Ex: `findAll: "/recipes.json"`. + // ## ajaxMaker + // Takes a method defined just above and a string that describes how to call that method + // and makes a function that calls that method with the given data. + // + // - `ajaxMethod`: The object defined above in `ajaxMethods`. + // - `str`: The string the configuration provided (such as `"/recipes.json"` for a `findAll` call). ajaxMaker = function (ajaxMethod, str) { - // Return a `function` that serves as the ajax method. return function (data) { - // If the ajax method has it's own way of getting `data`, use that. data = ajaxMethod.data ? + // If the AJAX method mentioned above has its own way of getting `data`, use that. ajaxMethod.data.apply(this, arguments) : - // Otherwise use the data passed in. - data; - // Return the ajax method with `data` and the `type` provided. + // Otherwise, just use the data passed in. + data; + + // Make the AJAX call with the URL, data, and type indicated by the proper `ajaxMethod` above. return ajax(str || this[ajaxMethod.url || "_url"], data, ajaxMethod.type || "get"); }; }; + // # can.Model + // A can.Map that connects to a RESTful interface. can.Model = can.Map.extend({ + // `fullName` identifies the model type in debugging. fullName: "can.Model", _reqs: 0, + // ## can.Model.setup /** * @hide * @function can.Model.setup @@ -1017,22 +1058,27 @@ steal('can/util', 'can/map', 'can/list', function (can) { * */ setup: function (base, fullName, staticProps, protoProps) { - // align args, this should happen in can.Construct + // Assume `fullName` wasn't passed. (`can.Model.extend({ ... }, { ... })`) + // This is pretty usual. if (fullName !== "string") { protoProps = staticProps; staticProps = fullName; } + // Assume no static properties were passed. (`can.Model.extend({ ... })`) + // This is really unusual for a model though, since there's so much configuration. if (!protoProps) { protoProps = staticProps; } - // create store here if someone wants to use model without inheriting from it + // Create the model store here, in case someone wants to use can.Model without inheriting from it. this.store = {}; + can.Map.setup.apply(this, arguments); - // Set default list as model list if (!can.Model) { return; } + + // `List` is just a regular can.Model.List that knows what kind of Model it's hooked up to. /** * @property {can.Model.List} can.Model.static.List List * @parent can.Model.static @@ -1086,73 +1132,89 @@ steal('can/util', 'can/map', 'can/list', function (can) { this.List = ML({ Map: this }, {}); + var self = this, clean = can.proxy(this._clean, self); - // go through ajax methods and set them up + // Go through `ajaxMethods` and set up static methods according to their configurations. can.each(ajaxMethods, function (method, name) { - // if an ajax method is not a function, it's either - // a string url like findAll: "/recipes" or an - // ajax options object like {url: "/recipes"} + // Check the configuration for this ajaxMethod. + // If the configuration isn't a function, it should be a string (like `"GET /endpoint"`) + // or an object like `{url: "/endpoint", type: 'GET'}`. if (!can.isFunction(self[name])) { - // use ajaxMaker to convert that into a function - // that returns a deferred with the data + // Etiher way, `ajaxMaker` will turn it into a function for us. self[name] = ajaxMaker(method, self[name]); } - // check if there's a make function like makeFindAll - // these take deferred function and can do special - // behavior with it (like look up data in a store) + + // There may also be a "maker" function (like `makeFindAll`) that alters the behavior of acting upon models + // by changing when and how the function we just made with `ajaxMaker` gets called. + // For example, you might cache responses and only make a call when you don't have a cached response. if (self["make" + can.capitalize(name)]) { - // pass the deferred method to the make method to get back - // the "findAll" method. + // Use the "maker" function to make the new "ajaxMethod" function. var newMethod = self["make" + can.capitalize(name)](self[name]); + // Replace the "ajaxMethod" function in the configuration with the new one. + // (`_overwrite` just overwrites a property in a given Construct.) can.Construct._overwrite(self, base, name, function () { - // increment the numer of requests + // Increment the numer of requests... can.Model._reqs++; + // ...make the AJAX call (and whatever else you're doing)... var def = newMethod.apply(this, arguments); + // ...and clean up the store. var then = def.then(clean, clean); + // Pass along `abort` so you can still abort the AJAX call. then.abort = def.abort; - // attach abort to our then and return it return then; }); } }); + // Set up the methods that will set up `models` and `model`. can.each(initializers, function (makeInitializer, name) { - var parseName = "parse" + can.capitalize(name); - if (typeof self[name] === "string") { + var parseName = "parse" + can.capitalize(name), + dataProperty = self[name]; - can.Construct._overwrite(self, base, parseName, parsers[parseName](self[name])); - - can.Construct._overwrite(self, base, name, makeInitializer(self[name])); + // If there was a different property to find the model's data in than `data`, + // make `parseModel` and `parseModels` functions that look that up instead. + if (typeof dataProperty === "string") { + can.Construct._overwrite(self, base, parseName, parsers[parseName](dataProperty)); + can.Construct._overwrite(self, base, name, makeInitializer(dataProperty)); } - // if there was no prototype, or no .models and no .parseModel + + // If there was no prototype, or no `model` and no `parseModel`, + // we'll have to create a `parseModel`. else if (!protoProps || (!protoProps[name] && !protoProps[parseName])) { - // create a parseModel can.Construct._overwrite(self, base, parseName, parsers[parseName]()); } }); + + // With the overridden parse methods, set up `models` and `model`. can.each(parsers, function (makeParser, name) { - // if parseModel is a string. + // If there was a different property to find the model's data in than `data`, + // make `model` and `models` functions that look that up instead. if (typeof self[name] === "string") { can.Construct._overwrite(self, base, name, makeParser(self[name])); } }); + // Make sure we have a unique name for this Model. if (self.fullName === "can.Model" || !self.fullName) { self.fullName = "Model" + (++modelNum); } - // Add ajax converters. + can.Model._reqs = 0; this._url = this._shortName + "/{" + this.id + "}"; }, _ajax: ajaxMaker, _makeRequest: makeRequest, + // ## can.Model._clean + // `_clean` cleans up the model store after a request happens. _clean: function () { can.Model._reqs--; + // Don't clean up unless we have no pending requests. if (!can.Model._reqs) { for (var id in this.store) { + // Delete all items in the store without any event bindings. if (!this.store[id]._bindings) { delete this.store[id]; } @@ -1255,15 +1317,18 @@ steal('can/util', 'can/map', 'can/list', function (can) { * @prototype */ { + // ## can.Model#setup setup: function (attrs) { - // try to add things as early as possible to the store (#457) - // we add things to the store before any properties are even set + // Try to add things as early as possible to the store (#457). + // This is the earliest possible moment, even before any properties are set. var id = attrs && attrs[this.constructor.id]; if (can.Model._reqs && id != null) { this.constructor.store[id] = this; } can.Map.prototype.setup.apply(this, arguments); }, + // ## can.Model#isNew + // Something is new if its ID is `null` or `undefined`. /** * @function can.Model.prototype.isNew isNew * @description Check if a Model has yet to be saved on the server. @@ -1280,8 +1345,12 @@ steal('can/util', 'can/map', 'can/list', function (can) { */ isNew: function () { var id = getId(this); + // 0 is a valid ID. + // TODO: Why not `return id === null || id === undefined;`? return !(id || id === 0); // If `null` or `undefined` }, + // ## can.Model#save + // `save` calls `create` or `update` as necessary, based on whether a model is new. /** * @function can.Model.prototype.save save * @description Save a model back to the server. @@ -1352,6 +1421,8 @@ steal('can/util', 'can/map', 'can/list', function (can) { save: function (success, error) { return makeRequest(this, this.isNew() ? 'create' : 'update', success, error); }, + // ## can.Model#destroy + // Acts like can.Map.destroy but it also makes an AJAX call. /** * @function can.Model.prototype.destroy destroy * @description Destroy a Model on the server. @@ -1390,17 +1461,23 @@ steal('can/util', 'can/map', 'can/list', function (can) { * }) */ destroy: function (success, error) { + // If this model is new, don't make an AJAX call. + // Instead, we have to construct the Deferred ourselves and return it. if (this.isNew()) { var self = this; var def = can.Deferred(); def.then(success, error); + return def.done(function (data) { self.destroyed(data); - }) - .resolve(self); + }).resolve(self); } + + // If it isn't new, though, go ahead and make a request. return makeRequest(this, 'destroy', success, error, 'destroyed'); }, + // ## can.Model#bind and can.Model#unbind + // These aren't actually implemented here, but their setup needs to be changed to account for the store. /** * @description Listen to events on this Model. * @function can.Model.prototype.bind bind @@ -1494,33 +1571,31 @@ steal('can/util', 'can/map', 'can/list', function (can) { delete this.constructor.store[getId(this)]; return can.Map.prototype._bindteardown.apply(this, arguments); }, - // Change `id`. + // Change the behavior of `___set` to account for the store. ___set: function (prop, val) { can.Map.prototype.___set.call(this, prop, val); - // If we add an `id`, move it to the store. + // If we add or change the ID, update the store accordingly. + // TODO: shouldn't this also delete the record from the old ID in the store? if (prop === this.constructor.id && this._bindings) { this.constructor.store[getId(this)] = this; } } }); - // ## Handler Logic - // - // The following setups how findAll, findOne, etc - // are handled. - - // Makes a getter response handler. + // Returns a function that knows how to prepare data from `findAll` or `findOne` calls. + // `name` should be either `model` or `models`. var makeGetterHandler = function (name) { var parseName = "parse" + can.capitalize(name); return function (data) { - // If there's a parse-function, call that and use its data. + // If there's a `parse...` function, use its output. if (this[parseName]) { data = this[parseName].apply(this, arguments); } + // Run our maybe-parsed data through `model` or `models`. return this[name](data); }; }, - // How these methods' responses are handled. + // Handle data returned from `create`, `update`, and `destroy` calls. createUpdateDestroyHandler = function (data) { if (this.parseModel) { return this.parseModel.apply(this, arguments); @@ -1682,20 +1757,24 @@ steal('can/util', 'can/map', 'can/list', function (can) { makeUpdate: createUpdateDestroyHandler }; - // Go through the response handlers and make the - // actual "make" methods. + // Go through the response handlers and make the actual "make" methods. can.each(responseHandlers, function (method, name) { can.Model[name] = function (oldMethod) { return function () { var args = can.makeArray(arguments), + // If args[1] is a function, we were only passed one argument before success and failure callbacks. oldArgs = can.isFunction(args[1]) ? args.splice(0, 1) : args.splice(0, 2), + // Call the AJAX method (`findAll` or `update`, etc.) and pipe it through the response handler from above. def = pipe(oldMethod.apply(this, oldArgs), this, method); + def.then(args[0], args[1]); return def; }; }; }); + // ## can.Model.created, can.Model.updated, and can.Model.destroyed + // Livecycle methods for models. can.each([ /** * @function can.Model.prototype.created created @@ -1722,44 +1801,56 @@ steal('can/util', 'can/map', 'can/list', function (can) { */ "destroyed" ], function (funcName) { + // Each of these is pretty much the same, except for the events they trigger. can.Model.prototype[funcName] = function (attrs) { - var stub, - constructor = this.constructor; + var constructor = this.constructor; - // Update attributes if attributes have been passed - stub = attrs && typeof attrs === 'object' && this.attr(attrs.attr ? attrs.attr() : attrs); + // If attrs was passed and is sane, update the model with those attrs. + if(attrs && typeof attrs === 'object') { + this.attr(attrs.attr ? attrs.attr() : attrs); + } - // triggers change event that bubble's like - // handler( 'change','1.destroyed' ). This is used - // to remove items on destroyed from Model Lists. - // but there should be a better way. + // Trigger a change event. This event bubbles up (for example, to Lists, + // where the changed property becomes something like `1.destroyed`). + // This event is used to remove items on `destroyed` from Model Lists, but there should be a better way. can.trigger(this, "change", funcName); //!steal-remove-start can.dev.log("Model.js - " + constructor.shortName + " " + funcName); //!steal-remove-end - // Call event on the instance's Class + // Trigger the appropriate event on the constructor. + // This lets code listen for any time a model of this type has a lifecycle event. can.trigger(constructor, funcName, this); }; }); - // Model lists are just like `Map.List` except that when their items are - // destroyed, it automatically gets removed from the list. + // # can.Model.List + // Model Lists are just like `Map.List`s except that when their items are + // destroyed, they automatically get removed from the List. var ML = can.Model.List = can.List({ + // ## can.Model.List.setup setup: function (params) { + // If there was a plain object passed to the List constructor, + // we use those as parameters for an initial findAll. if (can.isPlainObject(params) && !can.isArray(params)) { can.List.prototype.setup.apply(this); this.replace(this.constructor.Map.findAll(params)); } else { + // Otherwise, set up the list like normal. can.List.prototype.setup.apply(this, arguments); } }, + // ## can.Model.List._changes + // Because of the special behavior, we have to overwrite the default change handler. _changes: function (ev, attr) { can.List.prototype._changes.apply(this, arguments); + // On any change where an element was destroyed... if (/\w+\.destroyed/.test(attr)) { var index = this.indexOf(ev.target); + // ...check if the target was in the list... if (index !== -1) { + // ...and remove it if it was. this.splice(index, 1); } } From eab96d3f9733e874dbafcb952e05cf46ec57c7bd Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Mon, 31 Mar 2014 10:02:10 -0500 Subject: [PATCH 15/66] fixing ejs lint errors #843 --- view/ejs/ejs.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/view/ejs/ejs.js b/view/ejs/ejs.js index 957e8dd43b6..b11ef339622 100644 --- a/view/ejs/ejs.js +++ b/view/ejs/ejs.js @@ -217,7 +217,7 @@ function (can) { // The following helper converts a given string to upper case: // // can.EJS.Helpers.prototype.toUpper = function(params) { - // return params.toUpperCase(); + // return params.toUpperCase(); // } // Use it like this in any EJS template: @@ -227,9 +227,9 @@ function (can) { // To access the current DOM element return a function that takes the element as a parameter: // can.EJS.Helpers.prototype.upperHtml = function(params) { - // return function(el) { - // $(el).html(params.toUpperCase()); - // } + // return function(el) { + // $(el).html(params.toUpperCase()); + // } // } // In your EJS view you can then call the helper on an element tag: From aee875f35f821446525d270934e06bb05982ffcf Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Mon, 31 Mar 2014 10:33:05 -0500 Subject: [PATCH 16/66] moving docjs docs into separate md files #843 --- view/ejs/{ => doc}/demo.html | 4 +- view/ejs/{ => doc}/ejs.html | 2 +- view/ejs/{ => doc}/ejs.md | 0 view/ejs/doc/helpers.md | 27 +++++++++++ view/ejs/doc/prototype.render.md | 16 +++++++ view/ejs/{ => doc}/tags.comment.md | 0 view/ejs/{ => doc}/tags.escaped.md | 0 view/ejs/{ => doc}/tags.scriptlet.md | 0 view/ejs/{ => doc}/tags.templated.md | 0 view/ejs/{ => doc}/tags.unescaped.md | 0 view/ejs/ejs.js | 70 +--------------------------- 11 files changed, 48 insertions(+), 71 deletions(-) rename view/ejs/{ => doc}/demo.html (93%) rename view/ejs/{ => doc}/ejs.html (94%) rename view/ejs/{ => doc}/ejs.md (100%) create mode 100644 view/ejs/doc/helpers.md create mode 100644 view/ejs/doc/prototype.render.md rename view/ejs/{ => doc}/tags.comment.md (100%) rename view/ejs/{ => doc}/tags.escaped.md (100%) rename view/ejs/{ => doc}/tags.scriptlet.md (100%) rename view/ejs/{ => doc}/tags.templated.md (100%) rename view/ejs/{ => doc}/tags.unescaped.md (100%) diff --git a/view/ejs/demo.html b/view/ejs/doc/demo.html similarity index 93% rename from view/ejs/demo.html rename to view/ejs/doc/demo.html index d788fd76748..21858d50215 100644 --- a/view/ejs/demo.html +++ b/view/ejs/doc/demo.html @@ -2,7 +2,7 @@ can.view.ejs demo - + @@ -49,7 +49,7 @@
- + - + diff --git a/util/fixture/fixture_test.js b/util/fixture/fixture_test.js index b605bab9966..98bc0919080 100644 --- a/util/fixture/fixture_test.js +++ b/util/fixture/fixture_test.js @@ -470,18 +470,13 @@ steal('can/util/fixture', 'can/model', 'can/test', function () { can.fixture('GET /presetStore', store.findAll); stop(); - can.ajax({ - url: "/presetStore", - dataType: 'json', - data: {year: 2013, modelId:1} - }).done(function(response){ + $.get("/presetStore",{year: 2013, modelId:1}, function(response){ equal(response.data[0].id, 1, "got the first item"); equal(response.data.length, 1, "only got one item"); start(); }); - }); From 3e6be11f665a7b0ce3c22eff6215194bb66a6cf7 Mon Sep 17 00:00:00 2001 From: David Luecke Date: Tue, 1 Apr 2014 16:20:35 -0600 Subject: [PATCH 40/66] Fixing some tests. --- map/lazy/map_test.js | 7 ++++--- map/lazy/observe_test.js | 5 ++++- util/fixture/fixture_test.js | 2 +- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/map/lazy/map_test.js b/map/lazy/map_test.js index f4ec5d8524b..ccacb7d03d0 100644 --- a/map/lazy/map_test.js +++ b/map/lazy/map_test.js @@ -76,8 +76,9 @@ steal("can/map/lazy", "can/compute", "can/test", function (undefined) { }); - test("cyclical objects (#521)", function () { - + test("cyclical objects (#521)", 0, function () { + // Not supported by LazyMap + /* var foo = {}; foo.foo = foo; @@ -97,7 +98,7 @@ steal("can/map/lazy", "can/compute", "can/test", function (undefined) { var ref = new can.LazyMap(references) ok(ref.attr('husband') === ref.attr('friend'), "multiple properties point to the same thing") - + */ }) test('Getting attribute that is a can.compute should return the compute and not the value of the compute (#530)', function () { diff --git a/map/lazy/observe_test.js b/map/lazy/observe_test.js index f0ea498b4c0..eebf27d7c5c 100644 --- a/map/lazy/observe_test.js +++ b/map/lazy/observe_test.js @@ -784,7 +784,9 @@ steal('can/util', 'can/observe', 'can/map/lazy', 'can/test', function () { start(); }, 10); }); - test('dot separated keys (#257, #296)', function () { + test('dot separated keys (#257, #296)', 0, function () { + // Not supported by LazyMap + /* var ob = new can.LazyMap({ 'test.value': 'testing', other: { @@ -806,6 +808,7 @@ steal('can/util', 'can/observe', 'can/map/lazy', 'can/test', function () { test: 'value', stuff: 'thinger' }, 'Object set properly'); + */ }); test('cycle binding', function () { var first = new can.LazyMap(), diff --git a/util/fixture/fixture_test.js b/util/fixture/fixture_test.js index 98bc0919080..0f040e31a6c 100644 --- a/util/fixture/fixture_test.js +++ b/util/fixture/fixture_test.js @@ -470,7 +470,7 @@ steal('can/util/fixture', 'can/model', 'can/test', function () { can.fixture('GET /presetStore', store.findAll); stop(); - $.get("/presetStore",{year: 2013, modelId:1}, function(response){ + can.ajax({ url: "/presetStore", method: "get", data: {year: 2013, modelId:1} }).then(function(response){ equal(response.data[0].id, 1, "got the first item"); equal(response.data.length, 1, "only got one item"); From f4233fcf1656ff077c7e5ae493430fd0b7f21768 Mon Sep 17 00:00:00 2001 From: David Luecke Date: Tue, 1 Apr 2014 17:01:36 -0600 Subject: [PATCH 41/66] Resetting window.require for dist tests to pass everywhere. --- test/compatibility/dojo.html | 1 + test/compatibility/jquery-2.html | 1 + test/compatibility/jquery.html | 1 + test/compatibility/mootools.html | 1 + test/compatibility/yui.html | 1 + test/compatibility/zepto.html | 1 + test/dev/dojo.html | 1 + test/dev/jquery-2.html | 1 + test/dev/jquery.html | 1 + test/dev/mootools.html | 1 + test/dev/yui.html | 1 + test/dev/zepto.html | 1 + test/dist/dojo.html | 1 + test/dist/jquery-2.html | 1 + test/dist/jquery.html | 1 + test/dist/mootools.html | 1 + test/dist/yui.html | 1 + test/dist/zepto.html | 1 + test/templates/__configuration__-compat.html.ejs | 1 + test/templates/__configuration__-dev.html.ejs | 1 + test/templates/__configuration__-dist.html.ejs | 1 + 21 files changed, 21 insertions(+) diff --git a/test/compatibility/dojo.html b/test/compatibility/dojo.html index ab8b4a23515..770ad6a0958 100644 --- a/test/compatibility/dojo.html +++ b/test/compatibility/dojo.html @@ -59,6 +59,7 @@

diff --git a/test/compatibility/jquery-2.html b/test/compatibility/jquery-2.html index 7e51215f881..8130c9a5911 100644 --- a/test/compatibility/jquery-2.html +++ b/test/compatibility/jquery-2.html @@ -61,6 +61,7 @@

diff --git a/test/compatibility/jquery.html b/test/compatibility/jquery.html index d123ec04175..62e527a97fd 100644 --- a/test/compatibility/jquery.html +++ b/test/compatibility/jquery.html @@ -61,6 +61,7 @@

diff --git a/test/compatibility/mootools.html b/test/compatibility/mootools.html index d4f68b08ac4..428db048eb4 100644 --- a/test/compatibility/mootools.html +++ b/test/compatibility/mootools.html @@ -59,6 +59,7 @@

diff --git a/test/compatibility/yui.html b/test/compatibility/yui.html index da8524844a2..1903f190690 100644 --- a/test/compatibility/yui.html +++ b/test/compatibility/yui.html @@ -59,6 +59,7 @@

diff --git a/test/compatibility/zepto.html b/test/compatibility/zepto.html index 9cba278b843..91eae61d292 100644 --- a/test/compatibility/zepto.html +++ b/test/compatibility/zepto.html @@ -59,6 +59,7 @@

diff --git a/test/dev/dojo.html b/test/dev/dojo.html index c0809cf965c..2a1e6ba4f25 100644 --- a/test/dev/dojo.html +++ b/test/dev/dojo.html @@ -61,6 +61,7 @@

diff --git a/test/dev/jquery-2.html b/test/dev/jquery-2.html index 03c16e5d9ce..b3cb5830813 100644 --- a/test/dev/jquery-2.html +++ b/test/dev/jquery-2.html @@ -63,6 +63,7 @@

diff --git a/test/dev/jquery.html b/test/dev/jquery.html index 40bcb0d46b0..b33ac1b2805 100644 --- a/test/dev/jquery.html +++ b/test/dev/jquery.html @@ -63,6 +63,7 @@

diff --git a/test/dev/mootools.html b/test/dev/mootools.html index 2c99e618f51..3bede1ea748 100644 --- a/test/dev/mootools.html +++ b/test/dev/mootools.html @@ -61,6 +61,7 @@

diff --git a/test/dev/yui.html b/test/dev/yui.html index c02cb8ca2e7..883da4e8028 100644 --- a/test/dev/yui.html +++ b/test/dev/yui.html @@ -61,6 +61,7 @@

diff --git a/test/dev/zepto.html b/test/dev/zepto.html index 89f5f0c0d34..516c11e9278 100644 --- a/test/dev/zepto.html +++ b/test/dev/zepto.html @@ -61,6 +61,7 @@

diff --git a/test/dist/dojo.html b/test/dist/dojo.html index 6badf1fd963..0358b3a6f7d 100644 --- a/test/dist/dojo.html +++ b/test/dist/dojo.html @@ -59,6 +59,7 @@

diff --git a/test/dist/jquery-2.html b/test/dist/jquery-2.html index 08d2796d7ab..7d415bf738b 100644 --- a/test/dist/jquery-2.html +++ b/test/dist/jquery-2.html @@ -61,6 +61,7 @@

diff --git a/test/dist/jquery.html b/test/dist/jquery.html index db1ccf4b909..5da7ef94fc4 100644 --- a/test/dist/jquery.html +++ b/test/dist/jquery.html @@ -61,6 +61,7 @@

diff --git a/test/dist/mootools.html b/test/dist/mootools.html index 6aa05f2f9b6..8bd3e33fa00 100644 --- a/test/dist/mootools.html +++ b/test/dist/mootools.html @@ -59,6 +59,7 @@

diff --git a/test/dist/yui.html b/test/dist/yui.html index a742fbe4cc0..11e73dc93ea 100644 --- a/test/dist/yui.html +++ b/test/dist/yui.html @@ -59,6 +59,7 @@

diff --git a/test/dist/zepto.html b/test/dist/zepto.html index 5731fd5be7f..708d9761a57 100644 --- a/test/dist/zepto.html +++ b/test/dist/zepto.html @@ -59,6 +59,7 @@

diff --git a/test/templates/__configuration__-compat.html.ejs b/test/templates/__configuration__-compat.html.ejs index 557dc45e8d1..4e7e713c2e0 100644 --- a/test/templates/__configuration__-compat.html.ejs +++ b/test/templates/__configuration__-compat.html.ejs @@ -42,6 +42,7 @@ <% }); %> diff --git a/test/templates/__configuration__-dev.html.ejs b/test/templates/__configuration__-dev.html.ejs index 8c5ac5b0cc6..8d7a67c63ab 100644 --- a/test/templates/__configuration__-dev.html.ejs +++ b/test/templates/__configuration__-dev.html.ejs @@ -42,6 +42,7 @@ diff --git a/test/templates/__configuration__-dist.html.ejs b/test/templates/__configuration__-dist.html.ejs index e751b221478..c9b2ca92fa4 100644 --- a/test/templates/__configuration__-dist.html.ejs +++ b/test/templates/__configuration__-dist.html.ejs @@ -40,6 +40,7 @@ From 112456d0a6bf0a5545261245e35bf123622024c8 Mon Sep 17 00:00:00 2001 From: Andrew Holloway Date: Wed, 2 Apr 2014 11:13:26 -0400 Subject: [PATCH 42/66] Sprucing up the control.js docs after presentations yesterday. Cleaned up layout, content, and labeling. (#756) --- control/control.js | 107 ++++++++++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 45 deletions(-) diff --git a/control/control.js b/control/control.js index b441340047c..a71f738c3de 100644 --- a/control/control.js +++ b/control/control.js @@ -3,9 +3,12 @@ // Create organized, memory-leak free, rapidly performing, stateful // controls with declarative eventing binding. Used when creating UI // controls with behaviors, bound to elements on the page. +// ## helpers steal('can/util', 'can/construct', function (can) { - // Binds an element and returns a function that unbinds from that element. + // + // ### bind + // this helper binds to one element and returns a function that unbinds from that element. var bind = function (el, ev, callback) { can.bind.call(el, ev, callback); @@ -21,7 +24,10 @@ steal('can/util', 'can/construct', function (can) { paramReplacer = /\{([^\}]+)\}/g, special = can.getObject("$.event.special", [can]) || {}, - // Binds an element and returns a function that unbinds. + // ### delegate + // + // this helper binds to elements based on a selector and returns a + // function that unbinds. delegate = function (el, selector, ev, callback) { can.delegate.call(el, selector, ev, callback); return function () { @@ -29,6 +35,8 @@ steal('can/util', 'can/construct', function (can) { }; }, + // ### binder + // // Calls bind or unbind depending if there is a selector. binder = function (el, ev, callback, selector) { return selector ? @@ -42,21 +50,21 @@ steal('can/util', 'can/construct', function (can) { /** * @add can.Control */ + // ## *static functions* /** * @static */ { - // Setup pre-processes which methods are event listeners. + // ## can.Control.setup + // + // This function pre-processes which methods are event listeners and which are methods of + // the control. It has a mechanism to allow controllers to inherit default values from super + // classes, like `can.Construct`, and will cache functions that are action functions (see `_isAction`) + // or functions with an underscored name. setup: function () { - - // Allow contollers to inherit "defaults" from super-classes as it is - // done in `can.Construct` can.Construct.setup.apply(this, arguments); - // If you didn't provide a name, or are `control`, don't do anything. if (can.Control) { - - // Cache the underscored names, then the action functions from the prototype var control = this, funcName; @@ -68,7 +76,10 @@ steal('can/util', 'can/construct', function (can) { } } }, - // Moves `this` to the first argument, wraps it with `jQuery` if it's an element + // ## can.Control._shifter + // + // Moves `this` to the first argument, wraps it with `jQuery` if it's + // an element. _shifter: function (context, name) { var method = typeof name === "string" ? context[name] : name; @@ -83,33 +94,35 @@ steal('can/util', 'can/construct', function (can) { }; }, - // Return `true` if `methodName` refers to an action. + // ## can.Control._isAction + // + // Return `true` if `methodName` refers to an action. An action is a `methodName` value that + // is not the constructor, and is either a function or string that refers to a function, or is + // defined in `special`, `processors`. Detects whether `methodName` is also a valid method name. _isAction: function (methodName) { - var val = this.prototype[methodName], type = typeof val; - // if not the constructor + return (methodName !== 'constructor') && - // and is a function or links to a function (type === "function" || (type === "string" && isFunction(this.prototype[val]))) && - // and is in special, a processor, or has a funny character !! (special[methodName] || processors[methodName] || /[^\w]/.test(methodName)); }, - // Takes a method name and the options passed to a control - // and tries to return the data necessary to pass to a processor - // (something that binds things). + // ## can.Control._action + // + // Takes a method name and the options passed to a control and tries to return the data + // necessary to pass to a processor (something that binds things). // // For performance reasons, `_action` is called twice: // * It's called when the Control class is created. for templated method names (e.g., `{window} foo`), it returns null. For non-templated method names it returns the event binding data. That data is added to `this.actions`. // * It is called wehn a control instance is created, but only for templated actions. _action: function (methodName, options) { - // If we don't have options (a `control` instance), we'll run this - // later. + // If we don't have options (a `control` instance), we'll run this later. If we have + // options, run `can.sub` to replace the action template `{}` with values from the `options` + // or `window`. If a `{}` template resolves to an object, `convertedName` will be an array. + // In that case, the event name we want will be the last item in that array. paramReplacer.lastIndex = 0; if (options || !paramReplacer.test(methodName)) { - // If we have options, run `.sub` to replace templates `{}` with a - // value from the options or the window var convertedName = options ? can.sub(methodName, this._lookup(options)) : methodName; if (!convertedName) { //!steal-remove-start @@ -117,8 +130,6 @@ steal('can/util', 'can/construct', function (can) { //!steal-remove-end return null; } - // If a `{}` template resolves to an object, `convertedName` will be an array - // Take the event name from the end of that array. var arr = can.isArray(convertedName), name = arr ? convertedName[1] : convertedName, parts = name.split(/\s+/g), @@ -134,21 +145,28 @@ steal('can/util', 'can/construct', function (can) { _lookup: function (options) { return [options, window]; }, + // ## can.Control.processors + // // An object of `{eventName : function}` pairs that Control uses to - // hook up events auto-magically. + // hook up events automatically. processors: {}, + // ## can.Control.defaults // A object of name-value pairs that act as default values for a control instance defaults: {} }, { + // ## *prototype functions* /** * @prototype */ + // ## setup + // // Setup is where most of the Control's magic happens. It performs several pre-initialization steps: // - Sets `this.element` // - Adds the Control's name to the element's className // - Saves the Control in `$.data` // - Merges Options - // - Binds event handlers + // - Binds event handlers using `delegate` + // The final step is to return pass the element and prepareed options, to be used in `init`. setup: function (element, options) { var cls = this.constructor, @@ -162,10 +180,10 @@ steal('can/util', 'can/construct', function (can) { this.element.addClass(pluginname); } - // Set up the 'controls' data on the element + // Set up the 'controls' data on the element. If it does not exist, initialize + // it to an empty array. arr = can.data(this.element, 'controls'); if (!arr) { - // If it does not exist, initialize it to an empty array arr = []; can.data(this.element, 'controls', arr); } @@ -180,19 +198,19 @@ steal('can/util', 'can/construct', function (can) { // If no `options` value is used during creation, the value in `defaults` is used instead this.options = extend({}, cls.defaults, options); - // Bind all event handlers. this.on(); - // This gets passed into `init`. return [this.element, this.options]; }, - // `.on()` binds an event handler for an event to a selector under the scope of `this.element` - // If no options are specified, all events are rebound to their respective elements + // ## on + // + // This binds an event handler for an event to a selector under the scope of `this.element` + // If no options are specified, all events are rebound to their respective elements. The actions, + // which were cached in `setup`, are used and all elements are bound using `delegate` from `this.element`. on: function (el, selector, eventName, func) { if (!el) { this.off(); - // Go through the cached list of actions and use the processor to bind var cls = this.constructor, bindings = this._bindings, actions = cls.actions, @@ -209,8 +227,7 @@ steal('can/util', 'can/construct', function (can) { } } - // Setup to be destroyed... - // don't bind because we don't want to remove it. + // Set up the ability to `destroy` the control later. can.bind.call(element, "removed", destroyCB); bindings.push(function (el) { can.unbind.call(el, "removed", destroyCB); @@ -238,24 +255,25 @@ steal('can/util', 'can/construct', function (can) { } this._bindings.push(binder(el, eventName, func, selector)); - return this._bindings.length; }, + // ## off + // // Unbinds all event handlers on the controller. - // This should only be called in combination with .on() + // This should _only_ be called in combination with .on() off: function () { var el = this.element[0]; each(this._bindings || [], function (value) { value(el); }); - // Adds bindings. this._bindings = []; }, + // ## destroy + // // Prepares a `control` for garbage collection. // First checks if it has already been removed. Then, removes all the bindings, data, and - // the element from the Control. + // the element from the Control instance. destroy: function () { - // If the control is already destroyed, let the dev. know. if (this.element === null) { //!steal-remove-start can.dev.warn("can/control/control.js: Control already destroyed"); @@ -269,23 +287,22 @@ steal('can/util', 'can/construct', function (can) { this.off(); if (pluginName && pluginName !== 'can_control') { - // Remove the `className`. this.element.removeClass(pluginName); } - // Remove from `data`. controls = can.data(this.element, "controls"); controls.splice(can.inArray(this, controls), 1); - // Fire an event in case we want to know if the `control` is removed. can.trigger(this, "destroyed"); this.element = null; } }); - // Processors do the binding. This basic processor binds events. - // Each returns a function that unbinds when called. + // ## Processors + // + // Processors do the binding. This basic processor binds events. Each returns a function that unbinds + // when called. var processors = can.Control.processors; basicProcessor = function (el, event, selector, methodName, control) { return binder(el, event, can.Control._shifter(control, methodName), selector); From aa0278a5541db226d1013bfd1aeb6aafa83864fa Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Wed, 2 Apr 2014 10:29:24 -0500 Subject: [PATCH 43/66] test for #677 --- view/mustache/mustache_test.js | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/view/mustache/mustache_test.js b/view/mustache/mustache_test.js index 16eb0460e25..92efb3cc2a0 100644 --- a/view/mustache/mustache_test.js +++ b/view/mustache/mustache_test.js @@ -3570,4 +3570,22 @@ steal("can/model", "can/view/mustache", "can/test", function () { map.attr('showPeople', true); equal(ul.innerHTML, '
  • Curtis
  • Stan
  • David
    • ', 'List got updated'); }); + + test('Mustache helper: if w/ each removing all content', function () { + var expected = '123content', + container = new can.Map({ + items: [1,2,3] + }); + + var template = can.view.mustache('{{#if items.length}}{{#each items}}{{this}}{{/each}}content{{/if}}'); + var frag = template(container); + + var div = document.createElement('div'); + div.appendChild(frag); + + equal(div.innerHTML, expected); + + container.attr('items').replace([]); + equal(div.innerHTML, ''); + }); }); From 812af7f55dbdbe1eaa422fbe9404ad178f6d9038 Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Wed, 2 Apr 2014 10:34:37 -0500 Subject: [PATCH 44/66] fix for #771 --- model/model.js | 4 ++-- model/model_test.js | 20 ++++++++++++++++++++ 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/model/model.js b/model/model.js index 3da55c45002..141b5339b57 100644 --- a/model/model.js +++ b/model/model.js @@ -1764,8 +1764,8 @@ steal('can/util', 'can/map', 'can/list', function (can) { }, _destroyed: function (ev, attr) { if (/\w+/.test(attr)) { - var index = this.indexOf(ev.target); - if (index !== -1) { + var index; + while((index = this.indexOf(ev.target)) > -1) { this.splice(index, 1); } } diff --git a/model/model_test.js b/model/model_test.js index 55e3e571d6f..32b8b7eef2b 100644 --- a/model/model_test.js +++ b/model/model_test.js @@ -1455,4 +1455,24 @@ steal("can/model", 'can/map/attributes', "can/test", "can/util/fixture", functio }); + test('destroy called on multiple model references in a list (#771)', function() { + expect(2); + + var list = new can.Model.List(), + Thing = can.Model.extend({ + destroy: function() { + return new $.Deferred().resolve(); + } + }, {}); + + var a = new Thing({ name: 'a' }); + list.push(a, a); + + list.bind('remove', function(ev, items, i) { + ok('remove event triggered'); + }); + + a.destroy(); + }); + }); From 51ecc2248be1ccb1e9202198c62740a2d5ca910c Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Wed, 2 Apr 2014 11:57:13 -0500 Subject: [PATCH 45/66] Modified how inverse is created. Fixes #751 --- view/mustache/mustache.js | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/view/mustache/mustache.js b/view/mustache/mustache.js index 96fbeca4536..25676cae534 100644 --- a/view/mustache/mustache.js +++ b/view/mustache/mustache.js @@ -1257,6 +1257,7 @@ steal('can/util', } switch (mode) { // Truthy section + case '^': case '#': result.content += ('{fn:function(' + ARG_NAMES + '){var ___v1ew = [];'); break; @@ -1288,9 +1289,6 @@ steal('can/util', case 'else': result.content += 'return ___v1ew.join("");}},\n{inverse:function(' + ARG_NAMES + '){\nvar ___v1ew = [];'; break; - case '^': - result.content += '{inverse:function(' + ARG_NAMES + '){\nvar ___v1ew = [];'; - break; // Not a section, no mode default: @@ -1377,6 +1375,13 @@ steal('can/util', helperOptions.fn = makeConvertToScopes(helperOptions.fn, scope, options); helperOptions.inverse = makeConvertToScopes(helperOptions.inverse, scope, options); + // if mode is ^, swap fn and inverse + if(mode === '^') { + var tmp = helperOptions.fn; + helperOptions.fn = helperOptions.inverse; + helperOptions.inverse = tmp; + } + // Check for a registered helper or a helper-like function. if (helper = (getHelper && (typeof name === "string" && Mustache.getHelper(name, options)) || (can.isFunction(name) && !name.isComputed && { fn: name From 41b44671315dfb5f201bfb22463a49db77c81453 Mon Sep 17 00:00:00 2001 From: David Luecke Date: Wed, 2 Apr 2014 12:23:45 -0600 Subject: [PATCH 46/66] Add bubble to can.bubble to re-use it in LazyMap as a plugin. --- map/bubble.js | 2 +- map/lazy/bubble.js | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/map/bubble.js b/map/bubble.js index 3acd8a4fc1b..0160983ff9c 100644 --- a/map/bubble.js +++ b/map/bubble.js @@ -2,7 +2,7 @@ steal('can/util', function(can){ - var bubble = { + var bubble = can.bubble = { // Given a binding, returns a string event name used to set up bubbline. // If no binding should be done, undefined or null should be returned event: function(map, eventName) { diff --git a/map/lazy/bubble.js b/map/lazy/bubble.js index 270af82507f..b0288d8bded 100644 --- a/map/lazy/bubble.js +++ b/map/lazy/bubble.js @@ -1,4 +1,6 @@ -steal('can/util', 'can/map/bubble.js', function(can, bubble) { +steal('can/util', 'can/map/bubble.js', function(can) { + var bubble = can.bubble; + return can.extend({}, bubble, { childrenOf: function (parentMap, eventName) { if(parentMap._nestedReference) { From 913db1433ad4134413786257031e7adf20b3e09c Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Wed, 2 Apr 2014 14:36:31 -0500 Subject: [PATCH 47/66] Implementing reverse to trigger corresponding events and modify list in place. Fixes #851 --- list/list.js | 5 ++++- list/list_test.js | 13 +++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/list/list.js b/list/list.js index 7ef712df5c6..ee98177c9d4 100644 --- a/list/list.js +++ b/list/list.js @@ -871,7 +871,10 @@ steal("can/util", "can/map", function (can, Map) { * list === reversedList; // true * @codeend */ - reverse: [].reverse, + reverse: function() { + var list = can.makeArray([].reverse.call(this)); + this.replace(list); + }, /** * @function can.List.prototype.slice slice diff --git a/list/list_test.js b/list/list_test.js index 92e797ce114..9637e7e6085 100644 --- a/list/list_test.js +++ b/list/list_test.js @@ -166,4 +166,17 @@ steal("can/util", "can/list", "can/test", function () { l.splice(0, 1); ok(!l.attr(0), 'all props are removed'); }); + + test('reverse triggers add/remove events (#851)', function() { + expect(6); + var l = new can.List([1,2,3]); + + l.bind('change', function() { ok(true, 'change should be called'); }); + l.bind('set', function() { ok(false, 'set should not be called'); }); + l.bind('add', function() { ok(true, 'add called'); }); + l.bind('remove', function() { ok(true, 'remove called'); }); + l.bind('length', function() { ok(true, 'length should be called'); }); + + l.reverse(); + }); }); From 7ba668ad15a5e0f509647f8735f9ae383fea6170 Mon Sep 17 00:00:00 2001 From: Curtis Cummings Date: Thu, 3 Apr 2014 05:32:32 -0400 Subject: [PATCH 48/66] inline documentation for can.Map; Moving API docs to markdown files --- map/attributes/attributes.js | 218 +----- .../{ => doc}/attributes-assocations.html | 4 +- map/attributes/{ => doc}/attributes.html | 2 +- map/attributes/{ => doc}/attributes.md | 4 +- map/attributes/doc/prototype.serialize.md | 36 + map/attributes/doc/static.attributes.md | 13 + map/attributes/doc/static.convert.md | 126 ++++ map/attributes/doc/static.serialize.md | 32 + map/backup/backup.js | 167 ----- map/backup/{ => doc}/backup.html | 2 +- map/backup/{ => doc}/backup.md | 0 map/backup/doc/prototype.backup.md | 47 ++ map/backup/doc/prototype.isDirty.md | 54 ++ map/backup/doc/prototype.restore.md | 56 ++ map/delegate/delegate.js | 169 ----- map/delegate/{ => doc}/delegate.md | 0 map/delegate/doc/prototype.delegate.md | 152 ++++ map/delegate/doc/prototype.undelegate.md | 13 + map/{ => doc}/map.md | 4 +- map/doc/prototype.attr.md | 132 ++++ map/doc/prototype.bind.md | 99 +++ map/doc/prototype.compute-attr.md | 86 +++ map/doc/prototype.compute.md | 29 + map/doc/prototype.default-attr.md | 31 + map/doc/prototype.each.md | 37 + map/doc/prototype.removeAttr.md | 24 + map/doc/prototype.serialize.md | 22 + map/doc/prototype.unbind.md | 32 + map/doc/static.keys.md | 21 + map/map.js | 707 ++++-------------- map/setter/doc/can.classize.md | 19 + map/setter/{ => doc}/setter.md | 0 map/setter/setter.js | 22 +- .../{ => doc}/model_validations.html | 0 map/validations/doc/prototype.errors.md | 42 ++ map/validations/doc/static.validate.md | 48 ++ .../doc/static.validateFormatOf.md | 20 + .../doc/static.validateInclusionOf.md | 15 + .../doc/static.validateLengthOf.md | 15 + .../doc/static.validatePresenceOf.md | 13 + map/validations/doc/static.validateRangeOf.md | 15 + .../doc/static.validatesNumericalityOf.md | 12 + .../doc/static.validationMessages.md | 23 + map/validations/{ => doc}/validations.html | 0 map/validations/{ => doc}/validations.md | 0 map/validations/validations.js | 229 ------ 46 files changed, 1424 insertions(+), 1368 deletions(-) rename map/attributes/{ => doc}/attributes-assocations.html (96%) rename map/attributes/{ => doc}/attributes.html (97%) rename map/attributes/{ => doc}/attributes.md (98%) create mode 100644 map/attributes/doc/prototype.serialize.md create mode 100644 map/attributes/doc/static.attributes.md create mode 100644 map/attributes/doc/static.convert.md create mode 100644 map/attributes/doc/static.serialize.md rename map/backup/{ => doc}/backup.html (97%) rename map/backup/{ => doc}/backup.md (100%) create mode 100644 map/backup/doc/prototype.backup.md create mode 100644 map/backup/doc/prototype.isDirty.md create mode 100644 map/backup/doc/prototype.restore.md rename map/delegate/{ => doc}/delegate.md (100%) create mode 100644 map/delegate/doc/prototype.delegate.md create mode 100644 map/delegate/doc/prototype.undelegate.md rename map/{ => doc}/map.md (97%) create mode 100644 map/doc/prototype.attr.md create mode 100644 map/doc/prototype.bind.md create mode 100644 map/doc/prototype.compute-attr.md create mode 100644 map/doc/prototype.compute.md create mode 100644 map/doc/prototype.default-attr.md create mode 100644 map/doc/prototype.each.md create mode 100644 map/doc/prototype.removeAttr.md create mode 100644 map/doc/prototype.serialize.md create mode 100644 map/doc/prototype.unbind.md create mode 100644 map/doc/static.keys.md create mode 100644 map/setter/doc/can.classize.md rename map/setter/{ => doc}/setter.md (100%) rename map/validations/{ => doc}/model_validations.html (100%) create mode 100644 map/validations/doc/prototype.errors.md create mode 100644 map/validations/doc/static.validate.md create mode 100644 map/validations/doc/static.validateFormatOf.md create mode 100644 map/validations/doc/static.validateInclusionOf.md create mode 100644 map/validations/doc/static.validateLengthOf.md create mode 100644 map/validations/doc/static.validatePresenceOf.md create mode 100644 map/validations/doc/static.validateRangeOf.md create mode 100644 map/validations/doc/static.validatesNumericalityOf.md create mode 100644 map/validations/doc/static.validationMessages.md rename map/validations/{ => doc}/validations.html (100%) rename map/validations/{ => doc}/validations.md (100%) diff --git a/map/attributes/attributes.js b/map/attributes/attributes.js index 8a67deeb032..5409563893b 100644 --- a/map/attributes/attributes.js +++ b/map/attributes/attributes.js @@ -11,152 +11,9 @@ steal('can/util', 'can/map', 'can/list', function (can, Map) { return typeof obj === 'object' && obj !== null && obj; }; can.extend(clss, { - /** - * @property can.Map.attributes.static.attributes attributes - * @parent can.Map.attributes.static - * - * `can.Map.attributes` is a property that contains key/value pair(s) of an attribute's name and its - * respective type for using in [can.Map.attributes.static.convert convert] and [can.Map.prototype.serialize serialize]. - * - * var Contact = can.Map.extend({ - * attributes : { - * birthday : 'date', - * age: 'number', - * name: 'string' - * } - * }); - * - */ + attributes: {}, - /** - * @property can.Map.attributes.static.convert convert - * @parent can.Map.attributes.static - * - * You often want to convert from what the observe sends you to a form more useful to JavaScript. - * For example, contacts might be returned from the server with dates that look like: "1982-10-20". - * We can observe to convert it to something closer to `new Date(1982,10,20)`. - * - * Convert comes with the following types: - * - * - __date__ Converts to a JS date. Accepts integers or strings that work with Date.parse - * - __number__ An integer or number that can be passed to parseFloat - * - __boolean__ Converts "false" to false, and puts everything else through Boolean() - * - * The following sets the birthday attribute to "date" and provides a date conversion function: - * - * var Contact = can.Map.extend({ - * attributes : { - * birthday : 'date' - * }, - * convert : { - * date : function(raw){ - * if(typeof raw == 'string'){ - * //- Extracts dates formated 'YYYY-DD-MM' - * var matches = raw.match(/(\d+)-(\d+)-(\d+)/); - * - * //- Parses to date object and returns - * return new Date(matches[1], - * (+matches[2])-1, - * matches[3]); - * - * }else if(raw instanceof Date){ - * return raw; - * } - * } - * } - * },{}); - * - * var contact = new Contact(); - * - * //- calls convert on attribute set - * contact.attr('birthday', '4-26-2012') - * - * contact.attr('birthday'); //-> Date - * - * If a property is set with an object as a value, the corresponding converter is called with the unmerged data (the raw object) - * as the first argument, and the old value (a can.Map) as the second: - * - * var MyObserve = can.Map.extend({ - * attributes: { - * nested: "nested" - * }, - * convert: { - * nested: function(data, oldVal) { - * if(oldVal instanceof MyObserve) { - * return oldVal.attr(data); - * } - * return new MyObserve(data); - * } - * } - * },{}); - * - * ## Differences From `attr` - * - * The way that return values from convertors affect the value of an Observe's property is - * different from [can.Map::attr attr]'s normal behavior. Specifically, when the - * property's current value is an Observe or List, and an Observe or List is returned - * from a convertor, the effect will not be to merge the values into the current value as - * if the return value was fed straight into `attr`, but to replace the value with the - * new Observe or List completely. Because of this, any bindings you have on the previous - * observable object will break. - * - * If you would rather have the new Observe or List merged into the current value, call - * `attr` directly on the property instead of on the Observe: - * - * @codestart - * var Contact = can.Map.extend({ - * attributes: { - * info: 'info' - * }, - * convert: { - * 'info': function(data, oldVal) { - * return data; - * } - * } - * }, {}); - * - * var alice = new Contact({info: {name: 'Alice Liddell', email: 'alice@liddell.com'}}); - * alice.attr(); // {name: 'Alice Liddell', 'email': 'alice@liddell.com'} - * alice.info._cid; // '.observe1' - * - * alice.attr('info', {name: 'Allison Wonderland', phone: '888-888-8888'}); - * alice.attr(); // {name: 'Allison Wonderland', 'phone': '888-888-8888'} - * alice.info._cid; // '.observe2' - * - * alice.info.attr({email: 'alice@wonderland.com', phone: '000-000-0000'}); - * alice.attr(); // {name: 'Allison Wonderland', email: 'alice@wonderland.com', 'phone': '000-000-0000'} - * alice.info._cid; // '.observe2' - * @codeend - * - * ## Assocations and Convert - * - * If you have assocations defined within your model(s), you can use convert to automatically - * call serialize on those models. - * - * @codestart - * var Contact = can.Model.extend({ - * attributes : { - * tasks: Task - * } - * }, {}); - * - * var Task = can.Model.extend({ - * attributes : { - * due : 'date' - * } - * },{}); - * - * var contact = new Contact({ - * tasks: [ new Task({ - * due: new Date() - * }) ] - * }); - * - * contact.serialize(); - * //-> { tasks: [ { due: 1333219754627 } ] } - * @codeend - */ convert: { 'date': function (str) { var type = typeof str; @@ -205,41 +62,6 @@ steal('can/util', 'can/map', 'can/list', function (can, Map) { return typeof construct === 'function' ? construct.call(context, val, oldVal) : val; } }, - /** - * @property can.Map.attributes.static.serialize serialize - * @parent can.Map.attributes.static - * - * `can.Map.serialize` is an object of name-function pairs that are used to - * serialize attributes. - * - * Similar to [can.Map.attributes.static.convert can.Map.attributes.convert], in that the keys of this object correspond to - * the types specified in [can.Map.attributes]. - * - * By default every attribute will be passed through the 'default' serialization method - * that will return the value if the property holds a primitive value (string, number, ...), - * or it will call the "serialize" method if the property holds an object with the "serialize" method set. - * - * For example, to serialize all dates to ISO format: - * - * @codestart - * var Contact = can.Map.extend({ - * attributes : { - * birthday : 'date' - * }, - * serialize : { - * date : function(val, type){ - * return new Date(val).toISOString(); - * } - * } - * },{}); - * - * var contact = new Contact({ - * birthday: new Date("Oct 25, 1973") - * }).serialize(); - * //-> { "birthday" : "1973-10-25T05:00:00.000Z" } - * @codeend - * - */ serialize: { 'default': function (val, type) { return isObject(val) && val.serialize ? val.serialize() : val; @@ -295,44 +117,6 @@ steal('can/util', 'can/map', 'can/list', function (can, Map) { } return value === null || !type ? value : converter.call(Class, value, oldVal, function () {}, type); }; - /** - * @function can.Map.prototype.attributes.serialize serialize - * @parent can.Map.attributes.prototype - * - * @description Serializes the observe's properties using - * the [can.Map.attributes attribute plugin]. - * - * @signature `observe.serialize([attrName])` - * @param {String} [attrName] If passed, returns only a serialization of the named attribute. - * @return {String} A serialization of this Observe. - * - * @body - * You can set the serialization methods similar to the convert methods: - * - * var Contact = can.Map.extend({ - * attributes : { - * birthday : 'date' - * }, - * serialize : { - * date : function( val, type ){ - * return val.getYear() + - * "-" + (val.getMonth() + 1) + - * "-" + val.getDate(); - * } - * } - * },{}) - * - * var contact = new Contact(); - * contact.attr('birthday', new Date()); - * contact.serialize() - * //-> { birthday: 'YYYY-MM-DD' } - * - * You can also get and serialize an individual property by passing the attribute - * name to the `serialize` function. Building on the above demo, we can serialize - * the `birthday` attribute only. - * - * contact.serialize('birthday') //-> 'YYYY-MM-DD' - */ can.List.prototype.serialize = function (attrName, stack) { return can.makeArray(can.Map.prototype.serialize.apply(this, arguments)); }; diff --git a/map/attributes/attributes-assocations.html b/map/attributes/doc/attributes-assocations.html similarity index 96% rename from map/attributes/attributes-assocations.html rename to map/attributes/doc/attributes-assocations.html index 0c925b69137..b3d1323a90d 100644 --- a/map/attributes/attributes-assocations.html +++ b/map/attributes/doc/attributes-assocations.html @@ -14,11 +14,11 @@
    - + + + + + + + \ No newline at end of file diff --git a/list/list.js b/list/list.js index 7ef712df5c6..6dd8a7be11a 100644 --- a/list/list.js +++ b/list/list.js @@ -16,68 +16,8 @@ steal("can/util", "can/map", function (can, Map) { * @add can.List */ var list = Map( - /** - * @static - */ { - /** - * @property {can.Map} can.List.Map - * - * @description Specify the Map type used to make objects added to this list observable. - * - * @option {can.Map} When objects are added to a can.List, those objects are - * converted into can.Map instances. For example: - * - * var list = new can.List(); - * list.push({name: "Justin"}); - * - * var map = list.attr(0); - * map.attr("name") //-> "Justin" - * - * By changing [can.List.Map], you can specify a different type of Map instance to - * create. For example: - * - * var User = can.Map.extend({ - * fullName: function(){ - * return this.attr("first")+" "+this.attr("last") - * } - * }); - * - * User.List = can.List.extend({ - * Map: User - * }, {}); - * - * var list = new User.List(); - * list.push({first: "Justin", last: "Meyer"}); - * - * var user = list.attr(0); - * user.fullName() //-> "Justin Meyer" - * - * - * - */ Map: Map - /** - * @function can.Map.extend - * - * @signature `can.List.extend([name,] [staticProperties,] instanceProperties)` - * - * Creates a new extended constructor function. Learn more at [can.Construct.extend]. - * - * @param {String} [name] If provided, adds the extened List constructor function - * to the window at the given name. - * - * @param {Object} [staticProperties] Properties and methods - * directly on the constructor function. The most common property to set is [can.List.Map]. - * - * @param {Object} [instanceProperties] Properties and methods on instances of this list type. - * - * @body - * - * ## Use - * - * - */ }, /** * @prototype @@ -142,113 +82,9 @@ steal("can/util", "can/map", function (can, Map) { }, _bindsetup: Map.helpers.makeBindSetup("*"), // Returns the serialized form of this list. - /** - * @hide - * Returns the serialized form of this list. - */ serialize: function () { return Map.helpers.serialize(this, 'serialize', []); }, - /** - * @function can.List.prototype.each each - * @description Call a function on each element of a List. - * @signature `list.each( callback(item, index) )` - * - * `each` iterates through the Map, calling a function - * for each element. - * - * @param {function(*, Number)} callback the function to call for each element - * The value and index of each element will be passed as the first and second - * arguments, respectively, to the callback. If the callback returns false, - * the loop will stop. - * - * @return {can.List} this List, for chaining - * - * @body - * @codestart - * var i = 0; - * new can.Map([1, 10, 100]).each(function(element, index) { - * i += element; - * }); - * - * i; // 111 - * - * i = 0; - * new can.Map([1, 10, 100]).each(function(element, index) { - * i += element; - * if(index >= 1) { - * return false; - * } - * }); - * - * i; // 11 - * @codeend - */ - // - /** - * @function can.List.prototype.splice splice - * @description Insert and remove elements from a List. - * @signature `list.splice(index[, howMany[, ...newElements]])` - * @param {Number} index where to start removing or inserting elements - * - * @param {Number} [howMany] the number of elements to remove - * If _howMany_ is not provided, `splice` will all elements from `index` to the end of the List. - * - * @param {*} newElements elements to insert into the List - * - * @return {Array} the elements removed by `splice` - * - * @body - * `splice` lets you remove elements from and insert elements into a List. - * - * This example demonstrates how to do surgery on a list of numbers: - * - * @codestart - * var list = new can.List([0, 1, 2, 3]); - * - * // starting at index 2, remove one element and insert 'Alice' and 'Bob': - * list.splice(2, 1, 'Alice', 'Bob'); - * list.attr(); // [0, 1, 'Alice', 'Bob', 3] - * @codeend - * - * ## Events - * - * `splice` causes the List it's called on to emit _change_ events, - * _add_ events, _remove_ events, and _length_ events. If there are - * any elements to remove, a _change_ event, a _remove_ event, and a - * _length_ event will be fired. If there are any elements to insert, a - * separate _change_ event, an _add_ event, and a separate _length_ event - * will be fired. - * - * This slightly-modified version of the above example should help - * make it clear how `splice` causes events to be emitted: - * - * @codestart - * var list = new can.List(['a', 'b', 'c', 'd']); - * list.bind('change', function(ev, attr, how, newVals, oldVals) { - * console.log('change: ' + attr + ', ' + how + ', ' + newVals + ', ' + oldVals); - * }); - * list.bind('add', function(ev, newVals, where) { - * console.log('add: ' + newVals + ', ' + where); - * }); - * list.bind('remove', function(ev, oldVals, where) { - * console.log('remove: ' + oldVals + ', ' + where); - * }); - * list.bind('length', function(ev, length) { - * console.log('length: ' + length + ', ' + this.attr()); - * }); - * - * // starting at index 2, remove one element and insert 'Alice' and 'Bob': - * list.splice(2, 1, 'Alice', 'Bob'); // change: 2, 'remove', undefined, ['c'] - * // remove: ['c'], 2 - * // length: 5, ['a', 'b', 'Alice', 'Bob', 'd'] - * // change: 2, 'add', ['Alice', 'Bob'], ['c'] - * // add: ['Alice', 'Bob'], 2 - * // length: 5, ['a', 'b', 'Alice', 'Bob', 'd'] - * @codeend - * - * More information about binding to these events can be found under [can.List.attr attr]. - */ splice: function (index, howMany) { var args = can.makeArray(arguments), i; @@ -281,262 +117,6 @@ steal("can/util", "can/map", function (can, Map) { can.batch.stop(); return removed; }, - /** - * @description Get or set elements in a List. - * @function can.List.prototype.attr attr - * - * @signature `list.attr()` - * - * Gets an array of all the elements in this `can.List`. - * - * @return {Array} An array with all the elements in this List. - * - * @signature `list.attr(index)` - * - * Reads an element from this `can.List`. - * - * @param {Number} index The element to read. - * @return {*} The value at _index_. - * - * @signature `list.attr(index, value)` - * - * Assigns _value_ to the index _index_ on this `can.List`, expanding the list if necessary. - * - * @param {Number} index The element to set. - * @param {*} value The value to assign at _index_. - * @return {can.List} This list, for chaining. - * - * @signature `list.attr(elements[, replaceCompletely])` - * - * Merges the members of _elements_ into this List, replacing each from the beginning in order. If - * _elements_ is longer than the current List, the current List will be expanded. If _elements_ - * is shorter than the current List, the extra existing members are not affected (unless - * _replaceCompletely_ is `true`). To remove elements without replacing them, use `[can.Map::removeAttr removeAttr]`. - * - * @param {Array} elements An array of elements to merge in. - * - * @param {bool} [replaceCompletely=false] whether to completely replace the elements of List - * If _replaceCompletely_ is `true` and _elements_ is shorter than the List, the existing - * extra members of the List will be removed. - * - * @return {can.List} This list, for chaining. - * - * @body - * - * - * ## Use - * - * `attr` gets or sets elements on the `can.List` it's called on. Here's a tour through - * how all of its forms work: - * - * var people = new can.List(['Alex', 'Bill']); - * - * // set an element: - * people.attr(0, 'Adam'); - * - * // get an element: - * people.attr(0); // 'Adam' - * people[0]; // 'Adam' - * - * // get all elements: - * people.attr(); // ['Adam', 'Bill'] - * - * // extend the array: - * people.attr(4, 'Charlie'); - * people.attr(); // ['Adam', 'Bill', undefined, undefined, 'Charlie'] - * - * // merge the elements: - * people.attr(['Alice', 'Bob', 'Eve']); - * people.attr(); // ['Alice', 'Bob', 'Eve', undefined, 'Charlie'] - * - * ## Deep properties - * - * `attr` can also set and read deep properties. All you have to do is specify - * the property name as you normally would if you weren't using `attr`. - * - * @codestart - * var people = new can.List([{name: 'Alex'}, {name: 'Bob'}]); - * - * // set a property: - * people.attr('0.name', 'Alice'); - * - * // get a property: - * people.attr('0.name'); // 'Alice' - * people[0].attr('name'); // 'Alice' - * - * // get all properties: - * people.attr(); // [{name: 'Alice'}, {name: 'Bob'}] - * @codeend - * - * The discussion of deep properties under `[can.Map.prototype.attr]` may also - * be enlightening. - * - * ## Events - * - * `can.List`s emit five types of events in response to changes. They are: - * - * - the _change_ event fires on every change to a List. - * - the _set_ event is fired when an element is set. - * - the _add_ event is fired when an element is added to the List. - * - the _remove_ event is fired when an element is removed from the List. - * - the _length_ event is fired when the length of the List changes. - * - * ### The _change_ event - * - * The first event that is fired is the _change_ event. The _change_ event is useful - * if you want to react to all changes on an List. - * - * @codestart - * var list = new can.List([]); - * list.bind('change', function(ev, index, how, newVal, oldVal) { - * console.log('Something changed.'); - * }); - * @codeend - * - * The parameters of the event handler for the _change_ event are: - * - * - _ev_ The event object. - * - _index_ Where the change took place. - * - _how_ Whether elements were added, removed, or set. - * Possible values are `'add'`, `'remove'`, or `'set'`. - * - _newVal_ The elements affected after the change - * _newVal_ will be a single value when an index is set, an Array when elements - * were added, and `undefined` if elements were removed. - * - _oldVal_ The elements affected before the change. - * _newVal_ will be a single value when an index is set, an Array when elements - * were removed, and `undefined` if elements were added. - * - * Here is a concrete tour through the _change_ event handler's arguments: - * - * @codestart - * var list = new can.List(); - * list.bind('change', function(ev, index, how, newVal, oldVal) { - * console.log(ev + ', ' + index + ', ' + how + ', ' + newVal + ', ' + oldVal); - * }); - * - * list.attr(['Alexis', 'Bill']); // [object Object], 0, add, ['Alexis', 'Bill'], undefined - * list.attr(2, 'Eve'); // [object Object], 2, add, Eve, undefined - * list.attr(0, 'Adam'); // [object Object], 0, set, Adam, Alexis - * list.attr(['Alice', 'Bob']); // [object Object], 0, set, Alice, Adam - * // [object Object], 1, set, Bob, Bill - * list.removeAttr(1); // [object Object], 1, remove, undefined, Bob - * @codeend - * - * ### The _set_ event - * - * _set_ events are fired when an element at an index that already exists in the List is - * modified. Actions can cause _set_ events to fire never also cause _length_ events - * to fire (although some functions, such as `[can.List.prototype.splice splice]` - * may cause unrelated sets of events to fire after being batched). - * - * The parameters of the event handler for the _set_ event are: - * - * - _ev_ The event object. - * - _newVal_ The new value of the element. - * - _index_ where the set took place. - * - * Here is a concrete tour through the _set_ event handler's arguments: - * - * @codestart - * var list = new can.List(); - * list.bind('set', function(ev, newVal, index) { - * console.log(newVal + ', ' + index); - * }); - * - * list.attr(['Alexis', 'Bill']); - * list.attr(2, 'Eve'); - * list.attr(0, 'Adam'); // Adam, 0 - * list.attr(['Alice', 'Bob']); // Alice, 0 - * // Bob, 1 - * list.removeAttr(1); - * @codeend - * - * ### The _add_ event - * - * _add_ events are fired when elements are added or inserted - * into the List. - * - * The parameters of the event handler for the _add_ event are: - * - * - _ev_ The event object. - * - _newElements_ The new elements. - * If more than one element is added, _newElements_ will be an array. - * Otherwise, it is simply the new element itself. - * - _index_ Where the add or insert took place. - * - * Here is a concrete tour through the _add_ event handler's arguments: - * - * @codestart - * var list = new can.List(); - * list.bind('add', function(ev, newElements, index) { - * console.log(newElements + ', ' + index); - * }); - * - * list.attr(['Alexis', 'Bill']); // ['Alexis', 'Bill'], 0 - * list.attr(2, 'Eve'); // Eve, 2 - * list.attr(0, 'Adam'); - * list.attr(['Alice', 'Bob']); - * - * list.removeAttr(1); - * @codeend - * - * ### The _remove_ event - * - * _remove_ events are fired when elements are removed from the list. - * - * The parameters of the event handler for the _remove_ event are: - * - * - _ev_ The event object. - * - _removedElements_ The removed elements. - * If more than one element was removed, _removedElements_ will be an array. - * Otherwise, it is simply the element itself. - * - _index_ Where the removal took place. - * - * Here is a concrete tour through the _remove_ event handler's arguments: - * - * @codestart - * var list = new can.List(); - * list.bind('remove', function(ev, removedElements, index) { - * console.log(removedElements + ', ' + index); - * }); - * - * list.attr(['Alexis', 'Bill']); - * list.attr(2, 'Eve'); - * list.attr(0, 'Adam'); - * list.attr(['Alice', 'Bob']); - * - * list.removeAttr(1); // Bob, 1 - * @codeend - * - * ### The _length_ event - * - * _length_ events are fired whenever the list changes. - * - * The parameters of the event handler for the _length_ event are: - * - * - _ev_ The event object. - * - _length_ The current length of the list. - * If events were batched when the _length_ event was triggered, _length_ - * will have the length of the list when `stopBatch` was called. Because - * of this, you may recieve multiple _length_ events with the same - * _length_ parameter. - * - * Here is a concrete tour through the _length_ event handler's arguments: - * - * @codestart - * var list = new can.List(); - * list.bind('length', function(ev, length) { - * console.log(length); - * }); - * - * list.attr(['Alexis', 'Bill']); // 2 - * list.attr(2, 'Eve'); // 3 - * list.attr(0, 'Adam'); - * list.attr(['Alice', 'Bob']); - * - * list.removeAttr(1); // 2 - * @codeend - */ _attrs: function (items, remove) { if (items === undefined) { return Map.helpers.serialize(this, 'attr', []); @@ -852,26 +432,10 @@ steal("can/util", "can/map", function (can, Map) { join: function () { return [].join.apply(this.attr(), arguments); }, - - /** - * @function can.List.prototype.reverse reverse - * @description Reverse the order of a List. - * @signature `list.reverse()` - * - * `reverse` reverses the elements of the List in place. - * - * @return {can.List} the List, for chaining - * - * @body - * @codestart - * var list = new can.List(['Alice', 'Bob', 'Eve']); - * var reversedList = list.reverse(); - * - * reversedList.attr(); // ['Eve', 'Bob', 'Alice']; - * list === reversedList; // true - * @codeend - */ - reverse: [].reverse, + reverse: function() { + var list = can.makeArray([].reverse.call(this)); + this.replace(list); + }, /** * @function can.List.prototype.slice slice From 91379cf223e41627c47ef8315662e0443ffb02ca Mon Sep 17 00:00:00 2001 From: David Luecke Date: Thu, 3 Apr 2014 14:16:42 -0600 Subject: [PATCH 51/66] Fixing build for lazy-bubbling. --- map/setter/setter.js | 2 +- test/pluginified/2.0.5.test.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/map/setter/setter.js b/map/setter/setter.js index d43dd55b008..ddbccf44292 100644 --- a/map/setter/setter.js +++ b/map/setter/setter.js @@ -50,8 +50,8 @@ steal('can/util', 'can/map/attributes', 'can/util/string/classize.js',function ( asyncTimer = setTimeout(function(){ can.dev.warn('can/map/setter.js: Setter ' + setName+' did not return a value or call the setter callback.'); },can.dev.warnTimeout); - can.batch.stop(); //!steal-remove-end + can.batch.stop(); return; } else { old.call(self, prop, value, current, success, errorCallback); diff --git a/test/pluginified/2.0.5.test.js b/test/pluginified/2.0.5.test.js index a4f584013d6..e36e649b9ea 100644 --- a/test/pluginified/2.0.5.test.js +++ b/test/pluginified/2.0.5.test.js @@ -6402,7 +6402,7 @@ var __m42 = (function () { '{noExistStuff} proc': function () {} }); var c = new Control(document.createElement('div')); - equal(c._bindings.length, 1, 'There is only one binding'); + equal(c._bindings.user.length, 1, 'There is only one binding'); }); test('Multiple calls to destroy', 2, function () { var Control = can.Control({ From 5b37e2d2dedcddf3679d3b1e027bd64da7068125 Mon Sep 17 00:00:00 2001 From: Nikica Jokic Date: Fri, 4 Apr 2014 15:04:12 +0200 Subject: [PATCH 52/66] Inline documentation for map/sort/sort.js Related to #865. --- map/sort/sort.js | 161 +++++++++++++++++++++++------------------- map/sort/sort_test.js | 8 ++- 2 files changed, 95 insertions(+), 74 deletions(-) diff --git a/map/sort/sort.js b/map/sort/sort.js index b7e8d38a9ad..a6374896b7b 100644 --- a/map/sort/sort.js +++ b/map/sort/sort.js @@ -1,8 +1,17 @@ +// # can/map/sort/sort.js +// +// A plugin that enables smart sorting of can.Lists. It can do that in multiple ways: +// * by invoking a comparator function provided as an argument to the sort() method, +// * by using a comparator function defined in each contained can.Map +// +// It also listens to changes in the List, and positions changed elements to their appropriate place in the List. + steal('can/util', 'can/list', function (can) { var proto = can.List.prototype, _changes = proto._changes, setup = proto.setup; - // extend the list for sorting support + + // Extends the can.List prototype can.extend(proto, { comparator: undefined, sortIndexes: [], @@ -10,6 +19,7 @@ steal('can/util', 'can/list', function (can) { /** * @hide */ + // Calculates the index the item would have in a can.List if the list was sorted. sortedIndex: function (item) { var itemCompare = item.attr(this.comparator), equaled = 0; @@ -28,6 +38,7 @@ steal('can/util', 'can/list', function (can) { /** * @hide */ + // Prepares arguments for the sort method of the Array prototype, and invokes the sort after the arguments have been prepared. It handles various sorting cases (comparator function, comparator method, and delegation to Array). sort: function (method, silent) { var comparator = this.comparator, args = comparator ? [ @@ -44,89 +55,94 @@ steal('can/util', 'can/list', function (can) { return Array.prototype.sort.apply(this, args); } }); - // create push, pop, shift, and unshift - // converts to an array of arguments + var getArgs = function (args) { return args[0] && can.isArray(args[0]) ? args[0] : can.makeArray(args); }; + + // Takes certain methods from can.List prototype and depending on the + // method replaces them with a function that does the same thing, but + // invokes sorting afterwards. + // + // It also suspends triggering events on each sort-move by setting + // the silent flag to true while sorting and only triggers events + // after the list has been sorted. can.each({ - /** - * @function push - * Add items to the end of the list. - * - * var l = new can.List([]); - * - * l.bind('change', function( - * ev, // the change event - * attr, // the attr that was changed, for multiple items, "*" is used - * how, // "add" - * newVals, // an array of new values pushed - * oldVals, // undefined - * where // the location where these items where added - * ) { - * - * }) - * - * l.push('0','1','2'); - * - * @param {...*} [...items] items to add to the end of the list. - * @return {Number} the number of items in the array - */ - push: "length", - /** - * @function unshift - * Add items to the start of the list. This is very similar to - * [can.List::push]. Example: - * - * var l = new can.List(["a","b"]); - * l.unshift(1,2,3) //-> 5 - * l.attr() //-> [1,2,3,"a","b"] - * - * @param {...*} [...items] items to add to the start of the list. - * @return {Number} the length of the array. - */ - unshift: 0 - }, /** - * adds a method where - * @param where items in the array should be added - * @param name method name + * @function push + * Add items to the end of the list. Example: + * + * var l = new can.List([]); + * + * l.bind('change', function( + * ev, // the change event + * attr, // the attr that was changed, for multiple items, "*" is used + * how, // "add" + * newVals, // an array of new values pushed + * oldVals, // undefined + * where // the location where these items where added + * ) { + * + * }) + * + * l.push('0','1','2'); + * + * @param {...*} [...items] items to add to the end of the list. + * @return {Number} the number of items in the array */ - function (where, name) { - var proto = can.List.prototype, - old = proto[name]; - proto[name] = function () { - // get the items being added - var args = getArgs(arguments), - // where we are going to add items - len = where ? this.length : 0; - // call the original method - var res = old.apply(this, arguments); - // cause the change where the args are: - // len - where the additions happened - // add - items added - // args - the items added - // undefined - the old value - if (this.comparator && args.length) { - this.sort(null, true); - can.batch.trigger(this, 'reset', [args]); - this._triggerChange('' + len, 'add', args, undefined); - } - return res; - }; - }); - //- override changes for sorting + push: "length", + /** + * @function unshift + * Add items to the start of the list. This is very similar to + * [can.List::push]. Example: + * + * var l = new can.List(["a","b"]); + * l.unshift(1,2,3) //-> 5 + * l.attr() //-> [1,2,3,"a","b"] + * + * @param {...*} [...items] items to add to the start of the list. + * @return {Number} the length of the array. + */ + unshift: 0 + }, + /** + * adds a method where + * @param where items in the array should be added + * @param name method name + */ + function (where, name) { + var proto = can.List.prototype, + old = proto[name]; + proto[name] = function () { + var args = getArgs(arguments), + len = where ? this.length : 0; + var res = old.apply(this, arguments); + if (this.comparator && args.length) { + this.sort(null, true); + can.batch.trigger(this, 'reset', [args]); + this._triggerChange('' + len, 'add', args, undefined); + } + return res; + }; + }); + + // Overrides the _changes callback that gets triggered when + // an element in an List changes. + // + // Since this is a sorted List, the change needs to appropriately + // handled, which in turn means that the changed element needs to be + // positioned to it's correct location inside the List. + // + // Events are triggered after the move has happened. proto._changes = function (ev, attr, how, newVal, oldVal) { + // Checks if the attribute name is numeric, which means + // elements of can.List are changing. if (this.comparator && /^\d+./.test(attr)) { - // get the index var index = +/^\d+/.exec(attr)[0], - // and item item = this[index]; if (typeof item !== 'undefined') { - // and the new item var newIndex = this.sortedIndex(item); if (newIndex !== index) { - // move ... [].splice.call(this, index, 1); [].splice.call(this, newIndex, 0, item); can.trigger(this, 'move', [ @@ -146,7 +162,8 @@ steal('can/util', 'can/list', function (can) { } _changes.apply(this, arguments); }; - //- override setup for sorting + + // Override setup for sorting proto.setup = function (instances, options) { setup.apply(this, arguments); if (this.comparator) { diff --git a/map/sort/sort_test.js b/map/sort/sort_test.js index fc5078791c9..9d45c59929c 100644 --- a/map/sort/sort_test.js +++ b/map/sort/sort_test.js @@ -1,5 +1,6 @@ steal("can/map/sort", "can/test", "can/view/mustache", function () { module('can/map/sort'); + test('list events', 16, function () { var list = new can.List([{ name: 'Justin' @@ -47,6 +48,7 @@ steal("can/map/sort", "can/test", "can/view/mustache", function () { list.splice(0, 1); list[0].attr('name', 'Zed'); }); + test('list sort with func', 1, function () { var list = new can.List([{ priority: 4, @@ -69,8 +71,9 @@ steal("can/map/sort", "can/test", "can/view/mustache", function () { return a.priority > b.priority ? 1 : 0; }); equal(list[0].name, 'high'); - }); - test('list sort with comparator function', 4, function () { + }) + + test('list sort with containing Map attribute', 4, function () { var list = new can.Map.List([ new can.Map({ text: 'Bbb', @@ -104,6 +107,7 @@ steal("can/map/sort", "can/test", "can/view/mustache", function () { equal(list.attr()[2].text, 'baa'); equal(list.attr()[3].text, 'Bbb'); }); + test('live binding with comparator (#170)', function () { var renderer = can.view.mustache('
      {{#items}}
    • {{text}}
      • {{/items}}
    '), el = document.createElement('div'), From e6c8c7d9071219c8ab55d7c514bbc4e6ee4618bb Mon Sep 17 00:00:00 2001 From: Nikica Jokic Date: Fri, 4 Apr 2014 15:09:14 +0200 Subject: [PATCH 53/66] Sentence to one-line comment. --- map/sort/sort.js | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/map/sort/sort.js b/map/sort/sort.js index a6374896b7b..dff2cdc4aab 100644 --- a/map/sort/sort.js +++ b/map/sort/sort.js @@ -60,13 +60,9 @@ steal('can/util', 'can/list', function (can) { return args[0] && can.isArray(args[0]) ? args[0] : can.makeArray(args); }; - // Takes certain methods from can.List prototype and depending on the - // method replaces them with a function that does the same thing, but - // invokes sorting afterwards. + // Takes certain methods from can.List prototype and depending on the method replaces them with a function that does the same thing, but invokes sorting afterwards. // - // It also suspends triggering events on each sort-move by setting - // the silent flag to true while sorting and only triggers events - // after the list has been sorted. + // It also suspends triggering events on each sort-move by setting the silent flag to true while sorting and only triggers events after the list has been sorted. can.each({ /** * @function push From b1b4c5260cb678e119fd87c985930b0809607553 Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Fri, 4 Apr 2014 10:29:03 -0500 Subject: [PATCH 54/66] fixed model.list to look for base list. fixes #736 --- model/model.js | 13 ++++++++++--- model/model_test.js | 12 ++++++++++++ 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/model/model.js b/model/model.js index 4fbea13c916..1f42d60249e 100644 --- a/model/model.js +++ b/model/model.js @@ -1083,9 +1083,16 @@ steal('can/util', 'can/map', 'can/list', function (can) { * Task.List.Map //-> Task * */ - this.List = ML({ - Map: this - }, {}); + if(staticProps && staticProps.List) { + this.List = staticProps.List; + this.List.Map = this; + } + else { + this.List = base.List.extend({ + Map: this + }, {}); + } + var self = this, clean = can.proxy(this._clean, self); diff --git a/model/model_test.js b/model/model_test.js index 662870fbca6..98f2bd95dee 100644 --- a/model/model_test.js +++ b/model/model_test.js @@ -1448,4 +1448,16 @@ steal("can/model", 'can/map/attributes', "can/test", "can/util/fixture", functio }); + test('extending a model also inherits model list', function() { + var BaseModel = can.Model.extend({}); + BaseModel.List = can.Model.List.extend({ + someFunc: function() {} + }); + + + var SomeModel = BaseModel.extend({}); + var list = new SomeModel.List([]); + ok(list instanceof BaseModel.List); + }); + }); From b5ba819af9f15db8baa28d26292b0504ba7e49f0 Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Fri, 4 Apr 2014 10:49:51 -0500 Subject: [PATCH 55/66] cleaning up reverse demo --- list/doc/prototype.reverse.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/list/doc/prototype.reverse.md b/list/doc/prototype.reverse.md index 54745b22932..80ab2c8074c 100644 --- a/list/doc/prototype.reverse.md +++ b/list/doc/prototype.reverse.md @@ -18,8 +18,8 @@ reversedList.attr(); // ['Eve', 'Bob', 'Alice']; list === reversedList; // true @codeend -## Use - `reverse` calls `replace` internally and triggers corresponding `add`, `remove`, `change` and `length` events respectively. -@demo can/list/doc/reverse.html \ No newline at end of file +## Demo + +@iframe can/list/doc/reverse.html 350 \ No newline at end of file From d59608a376707b0ab44ce71eb9f9bfbffb0faba8 Mon Sep 17 00:00:00 2001 From: Curtis Cummings Date: Fri, 4 Apr 2014 12:01:18 -0400 Subject: [PATCH 56/66] Fixes to can.Maop inline documentation --- map/map.js | 185 ++++++++++++++++++++++++++--------------------------- 1 file changed, 89 insertions(+), 96 deletions(-) diff --git a/map/map.js b/map/map.js index a15232a64bc..bcf686a9186 100644 --- a/map/map.js +++ b/map/map.js @@ -1,48 +1,50 @@ -// # can/map.js -// -// can.Map provides the observable pattern for JavaScript Objects. +// # can/map/map.js +// `can.Map` provides the observable pattern for JavaScript Objects. + + + + steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function (can, bind) { - // ##Helpers - // Make parent listen to a child's change events + // ## Helpers + // Make parent listen to a child's change events. var bindToChildAndBubbleToParent = function (child, prop, parent) { can.listenTo.call(parent, child, "change", function ( /* ev, attr */ ) { var args = can.makeArray(arguments), ev = args.shift(); - //Make attr name relative to the parent + //Make attr name relative to the parent. args[0] = (prop === "*" ? [parent.indexOf(child), args[0]] : [prop, args[0]]) .join("."); - // track objects dispatched on this map + // Track objects dispatched on this map. ev.triggeredNS = ev.triggeredNS || {}; - // if it has already been dispatched; exit + // If it has already been dispatched; exit. if (ev.triggeredNS[parent._cid]) { return; } ev.triggeredNS[parent._cid] = true; - // send change event with modified attr to parent + // Send change event with modified attr to parent. can.trigger(parent, ev, args); }); }; - // Setup child binding and event bubbling to parent + // Setup child binding and event bubbling to parent. var makeBindSetup = function (wildcard) { return function () { var parent = this; this._each(function (child, prop) { - // If child can be bound + // If child can be bound, setup child to parent bubbling. if (child && child.bind) { - // Setup child to parent bubbling bindToChildAndBubbleToParent(child, wildcard || prop, parent); } }); }; }; - // A temporary map of Maps that have already been made from plain JS objects + // A temporary map of Maps that have been made from plain JS objects. var madeMap = null; - // Clears out map of converted objects + // Clears out map of converted objects. var teardownMap = function () { for (var cid in madeMap) { if (madeMap[cid].added) { @@ -51,7 +53,7 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( } madeMap = null; }; - // Retrieves a Map instance from an Object + // Retrieves a Map instance from an Object. var getMapFromObject = function (obj) { return madeMap && madeMap[obj._cid] && madeMap[obj._cid].instance; }; @@ -68,44 +70,43 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( can.Construct.setup.apply(this, arguments); - // Do not run if we are defining can.Map + // Do not run if we are defining can.Map. if (can.Map) { if (!this.defaults) { this.defaults = {}; } - // Builds a list of compute and non-compute properties in this Object's prototype + // Builds a list of compute and non-compute properties in this Object's prototype. this._computes = []; for (var prop in this.prototype) { - // Non-functions are regular defaults + // Non-functions are regular defaults. if (typeof this.prototype[prop] !== "function") { this.defaults[prop] = this.prototype[prop]; - // functions with an isComputed property are computes + // Functions with an `isComputed` property are computes. } else if (this.prototype[prop].isComputed) { this._computes.push(prop); } } } - // if we inerit from can.Map, but not can.List + // If we inherit from can.Map, but not can.List, make sure any lists are the correct type. if (can.List && !(this.prototype instanceof can.List)) { - // Make sure any lists are the correct type this.List = Map.List({ Map: this }, {}); } }, - // List of computes on the Object's prototype + // List of computes on the Map's prototype. _computes: [], - // Adds an event to this Object + // Adds an event to this Map. bind: can.bindAndSetup, on: can.bindAndSetup, - // Removes an event from this Object + // Removes an event from this Map. unbind: can.unbindAndTeardown, off: can.unbindAndTeardown, // Name of the id field. Used in can.Model. id: "id", - // Internal helpers + // ## Internal helpers helpers: { /** * @hide @@ -114,8 +115,8 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( * @param {Boolean} keepKey whether to keep the key intact * @return {Array} attribute parts */ - // ## can.Map.helpers.attrParts - // Parses attribute name into its parts + // ### can.Map.helpers.attrParts + // Parses attribute name into its parts. attrParts: function (attr, keepKey) { //Keep key intact if (keepKey) { @@ -132,22 +133,21 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( * @param {can.Map} instance the can.Map instance * @return {Function} function to clear out object mapping */ - // ## can.Map.helpers.addToMap + // ### can.Map.helpers.addToMap // Tracks Map instances created from JS Objects addToMap: function (obj, instance) { var teardown; - // Setup a fresh mapping if `madeMap` is missing + // Setup a fresh mapping if `madeMap` is missing. if (!madeMap) { teardown = teardownMap; madeMap = {}; } - // Record if Object has a `_cid` before adding one + // Record if Object has a `_cid` before adding one. var hasCid = obj._cid; var cid = can.cid(obj); - // Only update if there already isn't one already + // Only update if there already isn't one already. if (!madeMap[cid]) { - madeMap[cid] = { obj: obj, instance: instance, @@ -162,8 +162,8 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( * @param {Object} obj Object to check * @return {Boolean} whether `obj` can be made into an observable */ - // ## can.Map.helpers.canMakeObserve - // Determines if an object can be made into an observable + // ### can.Map.helpers.canMakeObserve + // Determines if an object can be made into an observable. canMakeObserve: function (obj) { return obj && !can.isDeferred(obj) && (can.isArray(obj) || can.isPlainObject(obj) || (obj instanceof can.Map)); }, @@ -174,8 +174,8 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( * @param {can.Map|can.List} parent parent observable * @return {Array} */ - // ## can.Map.helpers.unhookup - // Removes child event bubbling from parent + // ### can.Map.helpers.unhookup + // Removes child event bubbling from parent. unhookup: function (items, parent) { return can.each(items, function (item) { if (item && item.unbind) { @@ -194,8 +194,8 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( * @param {Function} List the List constructor * @return {can.Map|can.List} The child Map or List */ - // ## can.Map.helpers.unhookup - // Adds child event bubbling to parent + // ### can.Map.helpers.unhookup + // Adds child event bubbling to parent. hookupBubble: function (child, prop, parent, Ob, List) { Ob = Ob || Map; List = List || can.List; @@ -203,8 +203,7 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( // If it's an `array` make a list, otherwise a child. if (child instanceof Map) { - // We have a Map; make sure we are not listening to this already. - // It's only listening if it has bindings already. + // We have a Map; make sure we are not listening to this already (has bindings already). if (parent._bindings) { Map.helpers.unhookup([child], parent); } @@ -232,7 +231,7 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( * @param {String} where Object or Array to put properties in. * @return {Object|Array} serialized Map or List data. */ - // ## can.Map.helpers.serialize + // ### can.Map.helpers.serialize // Serializes a Map or Map.List serialize: function (map, how, where) { // Go through each property. @@ -247,7 +246,7 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( can.__reading(map, name); }); - // Let others know the number of keys have changed + // Let others know the number of keys have changed. can.__reading(map, '__keys'); return where; @@ -262,7 +261,7 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( */ keys: function (map) { var keys = []; - // Let others know the number of keys have changed + // Let others know the number of keys have changed. can.__reading(map, '__keys'); for (var keyName in map._data) { keys.push(keyName); @@ -287,10 +286,10 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( can.cid(this, ".map"); // Sets all `attrs`. this._init = 1; - // Setup computed attributes + // Setup computed attributes. this._setupComputes(); var teardownMapping = obj && can.Map.helpers.addToMap(obj, this); - // Setup default attribute values + // Setup default attribute values. var data = can.extend(can.extend(true, {}, this.constructor.defaults || {}), obj); this.attr(data); @@ -298,11 +297,12 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( teardownMapping(); } + // `batchTrigger` change events. this.bind('change', can.proxy(this._changes, this)); delete this._init; }, - // Sets up computed properties on a Map + // Sets up computed properties on a Map. _setupComputes: function () { var computes = this.constructor._computes; this._computedBindings = {}; @@ -316,28 +316,28 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( }; } }, - // Setup child bindings + // Setup child bindings. _bindsetup: makeBindSetup(), - // Teardown child bindings + // Teardown child bindings. _bindteardown: function () { var self = this; this._each(function (child) { Map.helpers.unhookup([child], self); }); }, - // `change`event handler + // `change`event handler. _changes: function (ev, attr, how, newVal, oldVal) { - // when a change happens, forward the event + // When a change happens, forward the event can.batch.trigger(this, { type: attr, batchNum: ev.batchNum }, [newVal, oldVal]); }, - // Trigger a change event + // Trigger a change event. _triggerChange: function (attr, how, newVal, oldVal) { can.batch.trigger(this, "change", can.makeArray(arguments)); }, - // Iterator that does not trigger live binding + // Iterator that does not trigger live binding. _each: function (callback) { var data = this.__get(); for (var prop in data) { @@ -368,7 +368,7 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( return can.each.apply(undefined, [this.__get()].concat(can.makeArray(arguments))); }, removeAttr: function (attr) { - // If this is List or not + // If this is List. var isList = can.List && this instanceof can.List, // Convert the `attr` into parts (if nested). parts = can.Map.helpers.attrParts(attr), @@ -386,18 +386,18 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( prop = attr; } if (isList) { - // Use splice on a list + // Use splice on a list which will remove the item and trigger an event. this.splice(prop, 1); } else if (prop in this._data) { - //Otherwise delete the data from `_data` + // Otherwise delete the property from `_data` and the Map + // as long as it isn't part of the Map's prototype. delete this._data[prop]; - // Create the event. if (!(prop in this.constructor.prototype)) { delete this[prop]; } - // Let others know the number of keys have changed + // Let others know the number of keys have changed. can.batch.trigger(this, "__keys"); - // Let others now this property has been removed + // Let others now this property has been removed. this._triggerChange(prop, "remove", undefined, current); } @@ -416,35 +416,33 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( return value; } } - // Otherwise we have to dig deeper into the Map to get the value - - // break up the attr (`"foo.bar"`) into parts like `["foo","bar"]` + // Otherwise we have to dig deeper into the Map to get the value. + // First, break up the attr (`"foo.bar"`) into parts like `["foo","bar"]`. var parts = can.Map.helpers.attrParts(attr), - // get the value of the first attr name (`"foo"`) + // Then get the value of the first attr name (`"foo"`). current = this.__get(parts.shift()); - // if there are other attributes to read + // If there are other attributes to read... return parts.length ? - // and current has a value + // and current has a value... current ? - // lookup the remaining attrs on current + // then lookup the remaining attrs on current current._get(parts) : - // or if there's no current, return undefined + // or if there's no current, return undefined. undefined : - // if there are no more parts, return current + // If there are no more parts, return current. current; }, // Reads a property directly if an `attr` is provided, otherwise // returns the "real" data object itself. __get: function (attr) { if (attr) { - // If it is a compute return the result + // If property is a compute return the result, otherwise get the value directly if (this[attr] && this[attr].isComputed && can.isFunction(this.constructor.prototype[attr])) { return this[attr](); - // Otherwise get the value directly } else { return this._data[attr]; } - // Return entire data object + // If not property is provided, return entire `_data` object } else { return this._data; } @@ -460,9 +458,8 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( // The current value. current = this.__get(prop); - // If we have an `object` and remaining parts. if ( parts.length && Map.helpers.canMakeObserve(current) ) { - // That `object` should set it (this might need to call attr). + // If we have an `object` and remaining parts that `object` should set it. current._set(parts, value); } else if (!parts.length) { // We're in "real" set territory. @@ -477,14 +474,14 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( }, __set: function (prop, value, current) { // TODO: Check if value is object and transform - // are we changing the value. + // Don't do anything if the value isn't changing. if (value !== current) { // Check if we are adding this for the first time -- // if we are, we need to create an `add` event. var changeType = this.__get() .hasOwnProperty(prop) ? "set" : "add"; - // Set the value on data. + // Set the value on `_data`. this.___set(prop, // If we are getting an object. @@ -497,8 +494,7 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( if (changeType === "add") { // If there is no current value, let others know that - // the the number of keys have changed - + // the the number of keys have changed. can.batch.trigger(this, "__keys", undefined); } @@ -530,12 +526,11 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( bind: function (eventName, handler) { var computedBinding = this._computedBindings && this._computedBindings[eventName]; if (computedBinding) { - // If this is the first time binding to this computed property + // The first time we bind to this computed property we + // initialize `count` and `batchTrigger` the change event. if (!computedBinding.count) { - // Initialize the count computedBinding.count = 1; var self = this; - // `batchTrigger` the change event computedBinding.handler = function (ev, newVal, oldVal) { can.batch.trigger(self, { type: eventName, @@ -544,23 +539,23 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( }; this[eventName].bind("change", computedBinding.handler); } else { - // Increment number of things listening to this computed property + // Increment number of things listening to this computed property. computedBinding.count++; } } + // The first time we bind to this Map, `_bindsetup` will + // be called to setup child event bubbling. return can.bindAndSetup.apply(this, arguments); - }, unbind: function (eventName, handler) { var computedBinding = this._computedBindings && this._computedBindings[eventName]; if (computedBinding) { - // If there is only one other listener + // If there is only one listener, we unbind the change event handler + // and clean it up since no one is listening to this property any more. if (computedBinding.count === 1) { computedBinding.count = 0; - // Stop listening to the `change` event this[eventName].unbind("change", computedBinding.handler); - // Cleanup the event handler delete computedBinding.handler; } else { // Decrement number of things listening to this computed property @@ -589,20 +584,19 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( self = this, newVal; - // Batch all of the change events until we are done + // Batch all of the change events until we are done. can.batch.start(); - // Merge current properties with the new ones + // Merge current properties with the new ones. this.each(function (curVal, prop) { - // you can not have a _cid property; abort + // You can not have a _cid property; abort. if (prop === "_cid") { return; } newVal = props[prop]; - // If we are merging + // If we are merging, remove the property if it has no value. if (newVal === undefined) { if (remove) { - // Remove the property if it has no value self.removeAttr(prop); } return; @@ -613,13 +607,13 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( newVal = self.__convert(prop, newVal); } - // if we're dealing with models, want to call _set to let converter run + // If we're dealing with models, we want to call _set to let converters run. if (newVal instanceof can.Map) { self.__set(prop, newVal, curVal); - // if its an object, let attr merge + // If its an object, let attr merge. } else if (Map.helpers.canMakeObserve(curVal) && Map.helpers.canMakeObserve(newVal) && curVal.attr) { curVal.attr(newVal, remove); - // otherwise just set + // Otherwise just set. } else if (curVal !== newVal) { self.__set(prop, newVal, curVal); } @@ -628,7 +622,7 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( }); // Add remaining props. for (prop in props) { - // Ignore _cid + // Ignore _cid. if (prop !== "_cid") { newVal = props[prop]; this._set(prop, newVal, true); @@ -639,12 +633,11 @@ steal('can/util', 'can/util/bind', 'can/construct', 'can/util/batch', function ( return this; }, compute: function (prop) { - // If the property is a function + // If the property is a function, use it as the getter/setter + // otherwise, create a new compute that returns the value of a property on `this` if (can.isFunction(this.constructor.prototype[prop])) { - // Use it as the getter/setter return can.compute(this[prop], this); } else { - // Otherwise, create a new compute that returns the value of a property on this var reads = prop.split("."), last = reads.length - 1, options = { From 452fa085adf43f6313a670ad3e80c66d7c7911c6 Mon Sep 17 00:00:00 2001 From: David Luecke Date: Fri, 4 Apr 2014 14:18:10 -0600 Subject: [PATCH 57/66] Fix JSHint for inline documentation. --- map/sort/sort_test.js | 2 +- view/scope/scope.js | 474 +++++++++++++++++++++--------------------- 2 files changed, 238 insertions(+), 238 deletions(-) diff --git a/map/sort/sort_test.js b/map/sort/sort_test.js index 9d45c59929c..a6301bbda4a 100644 --- a/map/sort/sort_test.js +++ b/map/sort/sort_test.js @@ -71,7 +71,7 @@ steal("can/map/sort", "can/test", "can/view/mustache", function () { return a.priority > b.priority ? 1 : 0; }); equal(list[0].name, 'high'); - }) + }); test('list sort with containing Map attribute', 4, function () { var list = new can.Map.List([ diff --git a/view/scope/scope.js b/view/scope/scope.js index e4d72bfae92..e037979f871 100644 --- a/view/scope/scope.js +++ b/view/scope/scope.js @@ -4,195 +4,195 @@ // If no parent scope is provided, only the scope's context will be explored for values. steal( - 'can/util', - 'can/construct', - 'can/map', - 'can/list', - 'can/view', - 'can/compute', function (can) { + 'can/util', + 'can/construct', + 'can/map', + 'can/list', + 'can/view', + 'can/compute', function (can) { - // ## Helpers + // ## Helpers - // Regex for escaped periods - var escapeReg = /(\\)?\./g, - // Regex for double escaped periods - escapeDotReg = /\\\./g, - // **getNames** - // Returns array of names by splitting provided string by periods and single escaped periods. - // ```getNames("a.b\.c.d\\.e") //-> ['a', 'b', 'c', 'd.e']``` - getNames = function (attr) { - var names = [], - last = 0; - // Goes through attr string and places the characters found between the periods and single escaped periods into the - // `names` array. Double escaped periods are ignored. - attr.replace(escapeReg, function (first, second, index) { - /* If period is double escaped then leave in place */ - if (!second) { - names.push( - attr - .slice(last, index) - /* replaces double-escaped period with period */ - .replace(escapeDotReg, '.') - ); - last = index + first.length; - } - }); - /* Adds last portion of attr to names array */ - names.push( - attr - .slice(last) - /* replaces double-escaped period with period */ - .replace(escapeDotReg, '.') - ); - return names; - }; - - /** - * @add can.view.Scope - */ - var Scope = can.Construct.extend( + // Regex for escaped periods + var escapeReg = /(\\)?\./g, + // Regex for double escaped periods + escapeDotReg = /\\\./g, + // **getNames** + // Returns array of names by splitting provided string by periods and single escaped periods. + // ```getNames("a.b\.c.d\\.e") //-> ['a', 'b', 'c', 'd.e']``` + getNames = function (attr) { + var names = [], + last = 0; + // Goes through attr string and places the characters found between the periods and single escaped periods into the + // `names` array. Double escaped periods are ignored. + attr.replace(escapeReg, function (first, second, index) { + /* If period is double escaped then leave in place */ + if (!second) { + names.push( + attr + .slice(last, index) + /* replaces double-escaped period with period */ + .replace(escapeDotReg, '.') + ); + last = index + first.length; + } + }); + /* Adds last portion of attr to names array */ + names.push( + attr + .slice(last) + /* replaces double-escaped period with period */ + .replace(escapeDotReg, '.') + ); + return names; + }; /** - * @static - */ - { - // ## Scope.read - // Scope.read was moved to can.compute.read - // can.compute.read reads properties from a parent. A much more complex version of getObject. - read: can.compute.read - }, - /** - * @prototype + * @add can.view.Scope */ - { - init: function (context, parent) { - this._context = context; - this._parent = parent; - this.__cache = {}; - }, + var Scope = can.Construct.extend( - // ## Scope.prototype.attr - // Reads a value from the current context or parent contexts. - attr: function (key) { - // Reads for whatever called before attr. It's possible - // that this.read clears them. We want to restore them. - var previousReads = can.__clearReading(), - res = this.read(key, { - isArgument: true, - returnObserveMethods: true, - proxyMethods: false - }).value; - can.__setReading(previousReads); - return res; + /** + * @static + */ + { + // ## Scope.read + // Scope.read was moved to can.compute.read + // can.compute.read reads properties from a parent. A much more complex version of getObject. + read: can.compute.read }, + /** + * @prototype + */ + { + init: function (context, parent) { + this._context = context; + this._parent = parent; + this.__cache = {}; + }, - // ## Scope.prototype.add - // Creates a new scope and sets the current scope to be the parent. - // ``` - // var scope = new can.view.Scope([{name:"Chris"}, {name: "Justin"}]).add({name: "Brian"}); - // scope.attr("name") //-> "Brian" - // ``` - add: function (context) { - if (context !== this._context) { - return new this.constructor(context, this); - } else { - return this; - } - }, + // ## Scope.prototype.attr + // Reads a value from the current context or parent contexts. + attr: function (key) { + // Reads for whatever called before attr. It's possible + // that this.read clears them. We want to restore them. + var previousReads = can.__clearReading(), + res = this.read(key, { + isArgument: true, + returnObserveMethods: true, + proxyMethods: false + }).value; + can.__setReading(previousReads); + return res; + }, + + // ## Scope.prototype.add + // Creates a new scope and sets the current scope to be the parent. + // ``` + // var scope = new can.view.Scope([{name:"Chris"}, {name: "Justin"}]).add({name: "Brian"}); + // scope.attr("name") //-> "Brian" + // ``` + add: function (context) { + if (context !== this._context) { + return new this.constructor(context, this); + } else { + return this; + } + }, - // ## Scope.prototype.computeData - // Finds the first location of the key in the scope and then provides a get-set compute that represents the key's value - // and other information about where the value was found. - computeData: function (key, options) { - options = options || { - args: [] - }; - var self = this, - rootObserve, - rootReads, - computeData = { - // computeData.compute returns a get-set compute that is tied to the first location of the provided - // key in the context of the scope. - compute: can.compute(function (newVal) { - // **Compute setter** - if (arguments.length) { - if (rootObserve.isComputed && !rootReads.length) { - rootObserve(newVal); + // ## Scope.prototype.computeData + // Finds the first location of the key in the scope and then provides a get-set compute that represents the key's value + // and other information about where the value was found. + computeData: function (key, options) { + options = options || { + args: [] + }; + var self = this, + rootObserve, + rootReads, + computeData = { + // computeData.compute returns a get-set compute that is tied to the first location of the provided + // key in the context of the scope. + compute: can.compute(function (newVal) { + // **Compute setter** + if (arguments.length) { + if (rootObserve.isComputed && !rootReads.length) { + rootObserve(newVal); + } else { + var last = rootReads.length - 1; + can.compute.read(rootObserve, rootReads.slice(0, last)) + .value.attr(rootReads[last], newVal); + } + // **Compute getter** } else { - var last = rootReads.length - 1; - can.compute.read(rootObserve, rootReads.slice(0, last)) - .value.attr(rootReads[last], newVal); - } - // **Compute getter** - } else { - // If computeData has found the value for the key in the past in an observable then go directly to - // the observable (rootObserve) that the value was found in the last time and return the new value. This - // is a huge performance gain for the fact that we aren't having to check the entire scope each time. - if (rootObserve) { - return can.compute.read(rootObserve, rootReads, options) - .value; + // If computeData has found the value for the key in the past in an observable then go directly to + // the observable (rootObserve) that the value was found in the last time and return the new value. This + // is a huge performance gain for the fact that we aren't having to check the entire scope each time. + if (rootObserve) { + return can.compute.read(rootObserve, rootReads, options) + .value; + } + // If the key has not already been located in a observable then we need to search the scope for the + // key. Once we find the key then we need to return it's value and if it is found in an observable + // then we need to store the observable so the next time this compute is called it can grab the value + // directly from the observable. + var data = self.read(key, options); + rootObserve = data.rootObserve; + rootReads = data.reads; + computeData.scope = data.scope; + computeData.initialValue = data.value; + return data.value; } - // If the key has not already been located in a observable then we need to search the scope for the - // key. Once we find the key then we need to return it's value and if it is found in an observable - // then we need to store the observable so the next time this compute is called it can grab the value - // directly from the observable. - var data = self.read(key, options); - rootObserve = data.rootObserve; - rootReads = data.reads; - computeData.scope = data.scope; - computeData.initialValue = data.value; - return data.value; - } - }) - }; - return computeData; - }, + }) + }; + return computeData; + }, - // ## Scope.prototype.compute - // Provides a get-set compute that represents a key's value. - compute: function (key, options) { - return this.computeData(key, options) - .compute; - }, + // ## Scope.prototype.compute + // Provides a get-set compute that represents a key's value. + compute: function (key, options) { + return this.computeData(key, options) + .compute; + }, - // ## Scope.prototype.read - // Finds the first isntance of a key in the available scopes and returns the keys value along with the the observable the key - // was found in, readsData and the current scope. - /** - * @hide - * @param {can.Mustache.key} attr A dot seperated path. Use `"\."` if you have a property name that includes a dot. - * @param {can.view.Scope.readOptions} options that configure how this gets read. - * @return {{}} - * @option {Object} parent the value's immediate parent - * @option {can.Map|can.compute} rootObserve the first observable to read from. - * @option {Array} reads An array of properties that can be used to read from the rootObserve to get the value. - * @option {*} value the found value - */ - read: function (attr, options) { + // ## Scope.prototype.read + // Finds the first isntance of a key in the available scopes and returns the keys value along with the the observable the key + // was found in, readsData and the current scope. + /** + * @hide + * @param {can.Mustache.key} attr A dot seperated path. Use `"\."` if you have a property name that includes a dot. + * @param {can.view.Scope.readOptions} options that configure how this gets read. + * @return {{}} + * @option {Object} parent the value's immediate parent + * @option {can.Map|can.compute} rootObserve the first observable to read from. + * @option {Array} reads An array of properties that can be used to read from the rootObserve to get the value. + * @option {*} value the found value + */ + read: function (attr, options) { - // check if we should be running this on a parent. - if (attr.substr(0, 3) === "../") { - return this._parent.read(attr.substr(3), options); - } else if (attr === "..") { - return { - value: this._parent._context - }; - } else if (attr === "." || attr === "this") { - return { - value: this._context - }; - } + // check if we should be running this on a parent. + if (attr.substr(0, 3) === "../") { + return this._parent.read(attr.substr(3), options); + } else if (attr === "..") { + return { + value: this._parent._context + }; + } else if (attr === "." || attr === "this") { + return { + value: this._context + }; + } - // Array of names from splitting attr string into names. ```"a.b\.c.d\\.e" //-> ['a', 'b', 'c', 'd.e']``` - var names = attr.indexOf('\\.') === -1 ? - // Reference doesn't contain escaped periods - attr.split('.') - // Reference contains escaped periods ```(`a.b\.c.foo` == `a["b.c"].foo)``` - : getNames(attr), + // Array of names from splitting attr string into names. ```"a.b\.c.d\\.e" //-> ['a', 'b', 'c', 'd.e']``` + var names = attr.indexOf('\\.') === -1 ? + // Reference doesn't contain escaped periods + attr.split('.') + // Reference contains escaped periods ```(`a.b\.c.foo` == `a["b.c"].foo)``` + : getNames(attr), // The current context (a scope is just data and a parent scope). - context, + context, // The current scope. - scope = this, + scope = this, // While we are looking for a value, we track the most likely place this value will be found. // This is so if there is no me.name.first, we setup a listener on me.name. // The most likely candidate is the one with the most "read matches" "lowest" in the @@ -200,11 +200,11 @@ steal( // By "read matches", we mean the most number of values along the key. // By "lowest" in the context chain, we mean the closest to the current context. // We track the starting position of the likely place with `defaultObserve`. - defaultObserve, + defaultObserve, // Tracks how to read from the defaultObserve. - defaultReads = [], + defaultReads = [], // Tracks the highest found number of "read matches". - defaultPropertyDepth = -1, + defaultPropertyDepth = -1, // `scope.read` is designed to be called within a compute, but // for performance reasons only listens to observables within one context. // This is to say, if you have me.name in the current context, but me.name.first and @@ -212,78 +212,78 @@ steal( // To make this happen, we clear readings if they do not find a value. But, // if that path turns out to be the default read, we need to restore them. This // variable remembers those reads so they can be restored. - defaultComputeReadings, + defaultComputeReadings, // Tracks the default's scope. - defaultScope, + defaultScope, // Tracks the first found observe. - currentObserve, + currentObserve, // Tracks the reads to get the value for a scope. - currentReads; + currentReads; - // Goes through each scope context provided until it finds the key (attr). Once the key is found - // then it's value is returned along with an observe, the current scope and reads. - // While going through each scope context searching for the key, each observable found is returned and - // saved so that either the observable the key is found in can be returned, or in the case the key is not - // found in an observable the closest observable can be returned. + // Goes through each scope context provided until it finds the key (attr). Once the key is found + // then it's value is returned along with an observe, the current scope and reads. + // While going through each scope context searching for the key, each observable found is returned and + // saved so that either the observable the key is found in can be returned, or in the case the key is not + // found in an observable the closest observable can be returned. - while (scope) { - context = scope._context; - if (context !== null) { - var data = can.compute.read(context, names, can.simpleExtend({ - /* Store found observable, incase we want to set it as the rootObserve. */ - foundObservable: function (observe, nameIndex) { - currentObserve = observe; - currentReads = names.slice(nameIndex); - }, - // Called when we were unable to find a value. - earlyExit: function (parentValue, nameIndex) { - /* If this has more matching values */ - if (nameIndex > defaultPropertyDepth) { - defaultObserve = currentObserve; - defaultReads = currentReads; - defaultPropertyDepth = nameIndex; - defaultScope = scope; - /* Clear and save readings so next attempt does not use these readings */ - defaultComputeReadings = can.__clearReading(); + while (scope) { + context = scope._context; + if (context !== null) { + var data = can.compute.read(context, names, can.simpleExtend({ + /* Store found observable, incase we want to set it as the rootObserve. */ + foundObservable: function (observe, nameIndex) { + currentObserve = observe; + currentReads = names.slice(nameIndex); + }, + // Called when we were unable to find a value. + earlyExit: function (parentValue, nameIndex) { + /* If this has more matching values */ + if (nameIndex > defaultPropertyDepth) { + defaultObserve = currentObserve; + defaultReads = currentReads; + defaultPropertyDepth = nameIndex; + defaultScope = scope; + /* Clear and save readings so next attempt does not use these readings */ + defaultComputeReadings = can.__clearReading(); + } } + }, options)); + // **Key was found**, return value and location data + if (data.value !== undefined) { + return { + scope: scope, + rootObserve: currentObserve, + value: data.value, + reads: currentReads + }; } - }, options)); - // **Key was found**, return value and location data - if (data.value !== undefined) { - return { - scope: scope, - rootObserve: currentObserve, - value: data.value, - reads: currentReads - }; } + // Prevent prior readings and then move up to the next scope. + can.__clearReading(); + scope = scope._parent; } - // Prevent prior readings and then move up to the next scope. - can.__clearReading(); - scope = scope._parent; - } - // **Key was not found**, return undefined for the value. Unless an observable was - // found in the process of searching for the key, then return the most likely observable along with it's - // scope and reads. + // **Key was not found**, return undefined for the value. Unless an observable was + // found in the process of searching for the key, then return the most likely observable along with it's + // scope and reads. - if (defaultObserve) { - can.__setReading(defaultComputeReadings); - return { - scope: defaultScope, - rootObserve: defaultObserve, - reads: defaultReads, - value: undefined - }; - } else { - return { - names: names, - value: undefined - }; + if (defaultObserve) { + can.__setReading(defaultComputeReadings); + return { + scope: defaultScope, + rootObserve: defaultObserve, + reads: defaultReads, + value: undefined + }; + } else { + return { + names: names, + value: undefined + }; + } } - } - }); + }); - can.view.Scope = Scope; - return Scope; -}); + can.view.Scope = Scope; + return Scope; + }); From 09cae18b409e35329f62f6ad32ea07cc6ddf488b Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Wed, 2 Apr 2014 16:16:22 -0500 Subject: [PATCH 58/66] Adds computed attributes for can.List instances. Fixes #790 --- list/list.js | 11 ++++++++++- list/list_test.js | 19 ++++++++++++++++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/list/list.js b/list/list.js index 8c79230dccf..f98b23fdd60 100644 --- a/list/list.js +++ b/list/list.js @@ -88,6 +88,7 @@ steal("can/util", "can/map", "can/map/bubble.js",function (can, Map, bubble) { this.length = 0; can.cid(this, ".map"); this._init = 1; + this._setupComputes(); instances = instances || []; var teardownMapping; @@ -127,7 +128,15 @@ steal("can/util", "can/map", "can/map/bubble.js",function (can, Map, bubble) { }, __get: function (attr) { - return attr ? this[attr] : this; + if (attr) { + if (this._computedBindings[attr]) { + return this[attr](); + } else { + return this[attr]; + } + } else { + return this; + } }, ___set: function (attr, val) { this[attr] = val; diff --git a/list/list_test.js b/list/list_test.js index 92e797ce114..acf197ad8bb 100644 --- a/list/list_test.js +++ b/list/list_test.js @@ -1,4 +1,4 @@ -steal("can/util", "can/list", "can/test", function () { +steal("can/util", "can/list", "can/test", "can/compute", function () { module('can/list'); test('list attr changes length', function () { var l = new can.List([ @@ -166,4 +166,21 @@ steal("can/util", "can/list", "can/test", function () { l.splice(0, 1); ok(!l.attr(0), 'all props are removed'); }); + + test('list sets up computed attributes (#790)', function() { + var List = can.List.extend({ + i: can.compute(0), + a: 0 + }); + + var l = new List([1]); + equal(l.attr('i'), 0); + + var Map = can.Map.extend({ + f: can.compute(0) + }); + + var m = new Map(); + m.attr('f'); + }); }); From f2975814086b5f7664cc54624f301a722b6f6d0b Mon Sep 17 00:00:00 2001 From: Alexis Abril Date: Sun, 6 Apr 2014 19:42:19 -0500 Subject: [PATCH 59/66] Adding ./ syntax for current scope property lookup. Fixes #873 --- view/scope/scope.js | 20 ++++++++++++++++---- view/scope/scope_test.js | 17 +++++++++++++++++ 2 files changed, 33 insertions(+), 4 deletions(-) diff --git a/view/scope/scope.js b/view/scope/scope.js index 9a666e5b593..ea50a7c9553 100644 --- a/view/scope/scope.js +++ b/view/scope/scope.js @@ -264,9 +264,15 @@ steal('can/util', 'can/construct', 'can/map', 'can/list', 'can/view', 'can/compu * @option {*} value the found value */ read: function (attr, options) { - + // check if we should only look within current scope + if(attr.substr(0, 2) === './') { + // set flag to halt lookup from walking up scope + this._stopLookup = true; + // stop lookup from checking parent scopes + return this.read(attr.substr(2), options); + } // check if we should be running this on a parent. - if (attr.substr(0, 3) === "../") { + else if (attr.substr(0, 3) === "../") { return this._parent.read(attr.substr(3), options); } else if (attr === "..") { return { @@ -353,8 +359,14 @@ steal('can/util', 'can/construct', 'can/map', 'can/list', 'can/view', 'can/compu } // Prevent prior readings. can.__clearReading(); - // Move up to the next scope. - scope = scope._parent; + + if(!this._stopLookup) { + // Move up to the next scope. + scope = scope._parent; + } + + // a flag to set if we should stop walking up scope + this._stopLookup = false; } // If there was a likely observe. diff --git a/view/scope/scope_test.js b/view/scope/scope_test.js index 354ab19f20c..881d41a853a 100644 --- a/view/scope/scope_test.js +++ b/view/scope/scope_test.js @@ -345,4 +345,21 @@ steal("can/view/scope", "can/route", "can/test", function () { .compute(), "baz", "static prop"); }); + test('Scope lookup restricted to current scope with ./', function() { + var Parent = can.Map.extend({ + foo: 0, + bar: 1 + }); + + var Child = Parent.extend({ + foo: 1 + }); + + var child = new Child(); + var scope = new can.view.Scope(child); + + equal(scope.computeData('bar').compute(), 1); + equal(scope.computeData('./foo').compute(), 1); + }); + }); From bc6f34f02297f0bfee27c141ab6bc4d9ffdaa194 Mon Sep 17 00:00:00 2001 From: Stan Carrico Date: Mon, 7 Apr 2014 13:22:53 -0700 Subject: [PATCH 60/66] docco plugin rework --- .gitignore | 3 +- Gruntfile.js | 25 +- component/component.md | 2 +- compute/compute.md | 2 +- construct/construct.md | 2 +- control/control.md | 2 +- list/doc/list.md | 2 +- map/doc/map.md | 2 +- model/model.md | 2 +- package.json | 2 +- resources/docco.css | 524 ++++++++++++++++++++++++++++++++++ route/route.md | 2 +- view/bindings/doc/bindings.md | 2 +- view/mustache/doc/mustache.md | 2 +- view/stache/doc/stashe.md | 2 +- 15 files changed, 554 insertions(+), 22 deletions(-) create mode 100644 resources/docco.css diff --git a/.gitignore b/.gitignore index 56d3518d640..7a5c1c09b67 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,5 @@ docs* *.DS_Store .idea bower_components/ -test/pluginified/latest.js \ No newline at end of file +test/pluginified/latest.js +docco \ No newline at end of file diff --git a/Gruntfile.js b/Gruntfile.js index d848652d594..3181e533ec2 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -376,15 +376,22 @@ module.exports = function (grunt) { } }, docco: { - dev: { - src: [ - 'component/**/*.js', 'compute/**/*.js', 'construct/**/*.js', 'control/**/*.js', 'list/**/*.js', - 'map/**/*.js', 'model/**/*.js', 'observe/**/*.js','route/**/*.js', 'util/**/*.js','view/**/*.js', - '!util/dojo/dojo-1.8.1.js', '!util/dojo/nodelist-traverse.js','!**/*_test.js' + options: { + dst: 'docco/', + layout : 'parallel', + css : 'resources/docco.css' + }, + docs: { + files : [ + { + src : [ + 'component/**/*.js', 'compute/**/*.js', 'construct/**/*.js', 'control/**/*.js', 'list/**/*.js', + 'map/**/*.js', 'model/**/*.js', 'observe/**/*.js','route/**/*.js', 'util/**/*.js','view/**/*.js', + '!util/dojo/dojo-1.8.1.js', '!util/dojo/nodelist-traverse.js','!**/*_test.js' + ], + expand : true + } ], - options: { - output: 'docco/' - } } }, plato: { @@ -450,7 +457,7 @@ module.exports = function (grunt) { grunt.loadNpmTasks('grunt-shell'); grunt.loadNpmTasks('bitovi-tools'); grunt.loadNpmTasks('grunt-jsbeautifier'); - grunt.loadNpmTasks('grunt-docco'); + grunt.loadNpmTasks('grunt-docco2'); grunt.loadNpmTasks('grunt-plato'); grunt.registerTask('quality', [ 'jsbeautifier', 'jshint']); diff --git a/component/component.md b/component/component.md index 3ffb1e06bbd..60a84375dff 100644 --- a/component/component.md +++ b/component/component.md @@ -3,7 +3,7 @@ @test can/component/test.html @parent canjs @release 2.0 -@link ../docco/component.html docco +@link ../docco/component/component.html docco @description Create widgets that use a template, a view-model diff --git a/compute/compute.md b/compute/compute.md index 4962acf77d6..12f5cf54cf8 100644 --- a/compute/compute.md +++ b/compute/compute.md @@ -1,7 +1,7 @@ @function can.compute @parent canjs @release 1.1 -@link ../docco/compute.html docco +@link ../docco/compute/compute.html docco @description Create an observable value. diff --git a/construct/construct.md b/construct/construct.md index 108b8c7f464..9ba78f4c39f 100644 --- a/construct/construct.md +++ b/construct/construct.md @@ -3,7 +3,7 @@ @test can/construct/test.html @parent canjs @group can.Construct.plugins plugins -@link ../docco/construct.html docco +@link ../docco/construct/construct.html docco @description diff --git a/control/control.md b/control/control.md index 23db52ec341..ab61e892492 100644 --- a/control/control.md +++ b/control/control.md @@ -6,7 +6,7 @@ @inherits can.Construct @description widget factory with declarative event binding. @group can.Control.plugins plugins -@link ../docco/control.html docco +@link ../docco/control/control.html docco @description Create organized, memory-leak free, rapidly performing, stateful controls with declarative event binding. Use `can.Control` to create UI diff --git a/list/doc/list.md b/list/doc/list.md index 2a098578d75..53161423ef9 100644 --- a/list/doc/list.md +++ b/list/doc/list.md @@ -9,7 +9,7 @@ @group can.List.static 1 Static @group can.List.plugins 2 plugins -@link ../docco/list.html docco +@link ../docco/list/list.html docco Use for observable array-like objects. diff --git a/map/doc/map.md b/map/doc/map.md index 43201ee0681..dd48f5c5a0b 100644 --- a/map/doc/map.md +++ b/map/doc/map.md @@ -7,7 +7,7 @@ @test can/map/test.html @plugin can/map @release 2.0 -@link ../docco/map.html docco +@link ../docco/map/map.html docco @description Create observable objects. diff --git a/model/model.md b/model/model.md index 870108661ad..c1132cefb00 100644 --- a/model/model.md +++ b/model/model.md @@ -2,7 +2,7 @@ @parent canjs @download can/model @test can/model/test.html -@link ../docco/model.html docco +@link ../docco/model/model.html docco @signature `can.Model([name,] staticProperties, instanceProperties)` Create a can.Model constructor. (See [can.Construct] for more details on this syntax.) diff --git a/package.json b/package.json index 68adbf8b392..454c1d87213 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,7 @@ "bower": "~1.2.7", "grunt-contrib-jshint": "~0.8.0", "grunt-jsbeautifier": "~0.2.6", - "grunt-docco": "~0.3.2", + "grunt-docco2": "git://github.com/shcarrico/grunt-docco.git#e4de54886ed5c421b2e26e7a2aeba1f73e889733", "grunt-plato": "~0.2.1" }, "scripts": { diff --git a/resources/docco.css b/resources/docco.css new file mode 100644 index 00000000000..30fea14bfda --- /dev/null +++ b/resources/docco.css @@ -0,0 +1,524 @@ + +@font-face { + font-family: 'aller-light'; + src: url('public/fonts/aller-light.eot'); + src: url('public/fonts/aller-light.eot?#iefix') format('embedded-opentype'), + url('public/fonts/aller-light.woff') format('woff'), + url('public/fonts/aller-light.ttf') format('truetype'); + font-weight: normal; + font-style: normal; +} + +@font-face { + font-family: 'aller-bold'; + src: url('public/fonts/aller-bold.eot'); + src: url('public/fonts/aller-bold.eot?#iefix') format('embedded-opentype'), + url('public/fonts/aller-bold.woff') format('woff'), + url('public/fonts/aller-bold.ttf') format('truetype'); + font-weight: normal; + font-style: normal; +} + +@font-face { + font-family: 'novecento-bold'; + src: url('public/fonts/novecento-bold.eot'); + src: url('public/fonts/novecento-bold.eot?#iefix') format('embedded-opentype'), + url('public/fonts/novecento-bold.woff') format('woff'), + url('public/fonts/novecento-bold.ttf') format('truetype'); + font-weight: normal; + font-style: normal; +} + +/*--------------------- Layout ----------------------------*/ +html { height: 100%; } +body { + font-family: "aller-light"; + font-size: 14px; + line-height: 18px; + color: #B8C4D0; + margin: 0; padding: 0; + height:100%; + background-color: #393939; +} + +.content { + background-color: #393939; +} + +.annotation { + color : #393939; +} + +#background { + background-color: #eee; +} + +#container { min-height: 100%; } + +a { + color: #393939; +} + +b, strong { + font-style: italic; + font-family: "aller-bold"; +} + +p { + margin: 15px 0 0px; +} +.annotation ul, .annotation ol { + margin: 25px 0; +} +.annotation ul li, .annotation ol li { + font-size: 14px; + line-height: 18px; + margin: 10px 0; +} + +h1, h2, h3, h4, h5, h6 { + color: #112233; + line-height: 1em; + font-weight: 700; + margin: 30px 0 15px 0; +} + +h1 { + margin-top: 40px; +} + +hr { + border: 0; + background: 1px #ddd; + height: 1px; + margin: 20px 0; +} + +pre, tt, code { + font-size: 12px; line-height: 16px; + font-family: Menlo, Monaco, Consolas, "Lucida Console", monospace; + margin: 0; + padding: 0; + tab-size: 2; + -moz-tab-size: 2; +} +.annotation pre { + display: block; + margin: 0; + padding: 7px 10px; + background: #393939; + -moz-box-shadow: inset 0 0 10px rgba(100,100,100,0.2); + -webkit-box-shadow: inset 0 0 10px rgba(100,100,100,0.2); + box-shadow: inset 0 0 10px rgba(100,100,100,0.2); + overflow-x: auto; +} + +.annotation pre code { + border: 0; + padding: 0; + background-color: #393939; +} + + +blockquote { + border-left: 5px solid #ccc; + margin: 0; + padding: 1px 0 1px 1em; +} +.sections blockquote p { + font-family: Menlo, Consolas, Monaco, monospace; + font-size: 12px; line-height: 16px; + color: #999; + margin: 10px 0 0; + white-space: pre-wrap; +} + +ul.sections { + list-style: none; + padding:0 0 5px 0;; + margin:0; +} + +/* + Force border-box so that % widths fit the parent + container without overlap because of margin/padding. + + More Info : http://www.quirksmode.org/css/box.html +*/ +ul.sections > li > div { + -moz-box-sizing: border-box; /* firefox */ + -ms-box-sizing: border-box; /* ie */ + -webkit-box-sizing: border-box; /* webkit */ + -khtml-box-sizing: border-box; /* konqueror */ + box-sizing: border-box; /* css3 */ +} + + +/*---------------------- Jump Page -----------------------------*/ +#jump_to, #jump_page { + margin: 0; + background: white; + -webkit-box-shadow: 0 0 25px #777; -moz-box-shadow: 0 0 25px #777; + -webkit-border-bottom-left-radius: 5px; -moz-border-radius-bottomleft: 5px; + font: 16px Arial; + cursor: pointer; + text-align: right; + list-style: none; +} + +#jump_to a { + text-decoration: none; +} + +#jump_to a.large { + display: none; +} +#jump_to a.small { + font-size: 22px; + font-weight: bold; + color: #676767; +} + +#jump_to, #jump_wrapper { + position: fixed; + right: 0; top: 0; + padding: 10px 15px; + margin:0; +} + +#jump_wrapper { + display: none; + padding:0; +} + +#jump_to:hover #jump_wrapper { + display: block; + overflow: auto; + bottom: 0; +} + +#jump_page { + padding: 5px 0 3px; + margin: 0 0 25px 25px; +} + +#jump_page .source { + display: block; + padding: 15px; + text-decoration: none; + border-top: 1px solid #eee; +} + +#jump_page .source:hover { + background: #f5f5ff; +} + +#jump_page .source:first-child { +} + +/*---------------------- Low resolutions (> 320px) ---------------------*/ +@media only screen and (min-width: 320px) { + .pilwrap { display: none; } + + ul.sections > li > div { + display: block; + padding:5px 10px 0 10px; + } + + ul.sections > li > div.annotation ul, ul.sections > li > div.annotation ol { + padding-left: 30px; + } + + ul.sections > li > div.content { + overflow-x:auto; + -webkit-box-shadow: inset 0 0 5px #e5e5ee; + box-shadow: inset 0 0 5px #e5e5ee; + border: 1px solid #dedede; + margin:5px 10px 5px 10px; + padding-bottom: 5px; + } + + ul.sections > li > div.annotation pre { + margin: 7px 0 7px; + padding-left: 15px; + } + + ul.sections > li > div.annotation p tt, .annotation code { + background: #f8f8ff; + border: 1px solid #dedede; + font-size: 12px; + padding: 0 0.2em; + } +} + +/*---------------------- (> 481px) ---------------------*/ +@media only screen and (min-width: 481px) { + #container { + position: relative; + } + body { + font-size: 15px; + line-height: 21px; + } + pre, tt, code { + line-height: 18px; + } + p, ul, ol { + margin: 0 0 15px; + } + + + #jump_to { + padding: 5px 10px; + } + #jump_wrapper { + padding: 0; + } + #jump_to, #jump_page { + font: 10px Arial; + text-transform: uppercase; + } + #jump_page .source { + padding: 5px 10px; + } + #jump_to a.large { + display: inline-block; + } + #jump_to a.small { + display: none; + } + + + #background { + position: absolute; + top: 0; bottom: 0; + width: 350px; + border-right: 1px solid #e5e5ee; + z-index: -1; + } + + ul.sections > li > div.annotation ul, ul.sections > li > div.annotation ol { + padding-left: 40px; + } + + ul.sections > li { + white-space: nowrap; + } + + ul.sections > li > div { + display: inline-block; + } + + ul.sections > li > div.annotation { + max-width: 350px; + min-width: 350px; + min-height: 5px; + padding: 13px; + overflow-x: hidden; + white-space: normal; + vertical-align: top; + text-align: left; + } + ul.sections > li > div.annotation pre { + margin: 15px 0 15px; + padding-left: 15px; + } + + ul.sections > li > div.content { + padding: 13px; + vertical-align: top; + border: none; + -webkit-box-shadow: none; + box-shadow: none; + } + + .pilwrap { + position: relative; + display: inline; + } + + .pilcrow { + font: 12px Arial; + text-decoration: none; + color: #454545; + position: absolute; + top: 3px; left: -20px; + padding: 1px 2px; + opacity: 0; + -webkit-transition: opacity 0.2s linear; + } + .for-h1 .pilcrow { + top: 47px; + } + .for-h2 .pilcrow, .for-h3 .pilcrow, .for-h4 .pilcrow { + top: 35px; + } + + ul.sections > li > div.annotation:hover .pilcrow { + opacity: 1; + } +} + +/*---------------------- (> 1025px) ---------------------*/ +@media only screen and (min-width: 1025px) { + + body { + font-size: 16px; + line-height: 24px; + } + + #background { + width: 525px; + } + ul.sections > li > div.annotation { + max-width: 525px; + min-width: 525px; + padding: 10px 25px 1px 50px; + } + ul.sections > li > div.content { + padding: 9px 15px 16px 15px; + } +} + +/*---------------------- Syntax Highlighting -----------------------------*/ + +td.linenos { background-color: #f0f0f0; padding-right: 10px; } +span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; } + +pre code { + display: block; padding: 0.5em; + color: #B8C4D0; + background-color: #393939 +} + +pre .hljs-comment, +pre .hljs-template_comment, +pre .hljs-diff .hljs-header, +pre .hljs-javadoc { + color: #408080; + font-style: italic +} + +pre .hljs-comment { + display: none; +} + +.annotation pre .hljs-comment { + display: inline; + color : #999; +} + +pre .hljs-keyword, +pre .hljs-assignment, +pre .hljs-literal, +pre .hljs-css .hljs-rule .hljs-keyword, +pre .hljs-winutils, +pre .hljs-javascript .hljs-title, +pre .hljs-lisp .hljs-title, +pre .hljs-subst { + color: #FFCF85; + /*font-weight: bold*/ +} + +pre .hljs-number, +pre .hljs-hexcolor { + color: #75A46A +} + +pre .hljs-string, +pre .hljs-tag .hljs-value, +pre .hljs-phpdoc, +pre .hljs-tex .hljs-formula { + color: #75A46A; +} + +pre .hljs-title, +pre .hljs-id { + color: #B8C4D0; +} +pre .hljs-params { + color: #B8C4D0; +} + +pre .hljs-javascript .hljs-title, +pre .hljs-lisp .hljs-title, +pre .hljs-subst { + font-weight: normal +} + +pre .hljs-class .hljs-title, +pre .hljs-haskell .hljs-label, +pre .hljs-tex .hljs-command { + color: #B8C4D0; + font-weight: bold +} + +pre .hljs-tag, +pre .hljs-tag .hljs-title, +pre .hljs-rules .hljs-property, +pre .hljs-django .hljs-tag .hljs-keyword { + color: #B8C4D0; + font-weight: normal +} + +pre .hljs-attribute, +pre .hljs-variable, +pre .hljs-instancevar, +pre .hljs-lisp .hljs-body { + color: #D58B48 +} + +pre .hljs-regexp { + color: #A98DB7 +} + +pre .hljs-class { + color: #B8C4D0; + font-weight: bold +} + +pre .hljs-symbol, +pre .hljs-ruby .hljs-symbol .hljs-string, +pre .hljs-ruby .hljs-symbol .hljs-keyword, +pre .hljs-ruby .hljs-symbol .hljs-keymethods, +pre .hljs-lisp .hljs-keyword, +pre .hljs-tex .hljs-special, +pre .hljs-input_number { + color: #990073 +} + +pre .hljs-builtin, +pre .hljs-constructor, +pre .hljs-built_in, +pre .hljs-lisp .hljs-title { + color: #D58B48 +} + +pre .hljs-preprocessor, +pre .hljs-pi, +pre .hljs-doctype, +pre .hljs-shebang, +pre .hljs-cdata { + color: #999; + font-weight: bold +} + +pre .hljs-deletion { + background: #fdd +} + +pre .hljs-addition { + background: #dfd +} + +pre .hljs-diff .hljs-change { + background: #0086b3 +} + +pre .hljs-chunk { + color: #aaa +} + +pre .hljs-tex .hljs-formula { + opacity: 0.5; +} \ No newline at end of file diff --git a/route/route.md b/route/route.md index cac3d730ad0..3b7513d9344 100644 --- a/route/route.md +++ b/route/route.md @@ -5,7 +5,7 @@ @test can/route/test.html @parent canjs @group can.route.plugins plugins -@link ../docco/route.html docco +@link ../docco/route/route.html docco @description Manage browser history and client state by synchronizing the window.location.hash with diff --git a/view/bindings/doc/bindings.md b/view/bindings/doc/bindings.md index b9f4dff9899..a17521e2d33 100644 --- a/view/bindings/doc/bindings.md +++ b/view/bindings/doc/bindings.md @@ -1,6 +1,6 @@ @page can.view.bindings @parent canjs -@link ../docco/bindings.html docco +@link ../docco/view/bindings/bindings.html docco Provides template event bindings and two-way bindings. diff --git a/view/mustache/doc/mustache.md b/view/mustache/doc/mustache.md index 0c42438bb1b..f91d187bf0c 100644 --- a/view/mustache/doc/mustache.md +++ b/view/mustache/doc/mustache.md @@ -5,7 +5,7 @@ @group can.Mustache.types 1 Types @group can.Mustache.tags 2 Basic Tags @group can.Mustache.htags 3 Helper Tags -@link ../docco/mustache.html docco +@link ../docco/view/mustache/mustache.html docco @test can/view/mustache/test/test.html @plugin can/view/mustache @download http://canjs.us/release/latest/can.view.mustache.js diff --git a/view/stache/doc/stashe.md b/view/stache/doc/stashe.md index 3d34a05d4fa..20678771ed4 100644 --- a/view/stache/doc/stashe.md +++ b/view/stache/doc/stashe.md @@ -6,7 +6,7 @@ @group can.stache.tags 2 Basic Tags @group can.stache.htags 3 Helper Tags @group can.stache.static 4 Methods -@link ../docco/stache.html docco +@link ../docco/view/stache/mustache_core.html docco @test can/view/stache/test/test.html @plugin can/view/stache @download http://canjs.us/release/latest/can.stache.js From f761946449ab8e19ae1073649d51f408759b2d97 Mon Sep 17 00:00:00 2001 From: Stan Carrico Date: Mon, 7 Apr 2014 13:23:08 -0700 Subject: [PATCH 61/66] view.js documentation fixes --- view/doc/ejs.md | 42 +++ view/doc/mustache.md | 42 +++ view/{ => doc}/view.md | 2 +- view/view.js | 633 +++++++++++++++++++++-------------------- 4 files changed, 411 insertions(+), 308 deletions(-) create mode 100644 view/doc/ejs.md create mode 100644 view/doc/mustache.md rename view/{ => doc}/view.md (99%) diff --git a/view/doc/ejs.md b/view/doc/ejs.md new file mode 100644 index 00000000000..ab49a9f39fa --- /dev/null +++ b/view/doc/ejs.md @@ -0,0 +1,42 @@ +@function can.view.ejs ejs +@parent can.view.static + +@signature `can.view.ejs( [id,] template )` + +Register an EJS template string and create a renderer function. + + var renderer = can.view.ejs("

    <%= message %>

    "); + renderer({message: "Hello"}) //-> docFrag[

    Hello

    ] + +@param {String} [id] An optional ID to register the template. + + + can.view.ejs("greet","

    <%= message %>

    "); + can.view("greet",{message: "Hello"}) //-> docFrag[

    Hello

    ] + +@param {String} template An EJS template in string form. +@return {can.view.renderer} A renderer function that takes data and helpers. + + +@body +`can.view.ejs([id,] template)` registers an EJS template string +for a given id programatically. The following +registers `myViewEJS` and renders it into a documentFragment. + + can.view.ejs('myViewEJS', '

    <%= message %>

    '); + + var frag = can.view('myViewEJS', { + message : 'Hello there!' + }); + + frag // ->

    Hello there!

    + +To convert the template into a render function, just pass +the template. Call the render function with the data +you want to pass to the template and it returns the +documentFragment. + + var renderer = can.view.ejs('
    <%= message %>
    '); + renderer({ + message : 'EJS' + }); // ->
    EJS
    \ No newline at end of file diff --git a/view/doc/mustache.md b/view/doc/mustache.md new file mode 100644 index 00000000000..c2220596893 --- /dev/null +++ b/view/doc/mustache.md @@ -0,0 +1,42 @@ +@function can.view.mustache mustache +@parent can.view.static + +@signature `can.view.mustache( [id,] template )` + +Register a Mustache template string and create a renderer function. + + var renderer = can.view.mustache("

    {{message}}

    "); + renderer({message: "Hello"}) //-> docFrag[

    Hello

    ] + +@param {String} [id] An optional ID for the template. + + can.view.ejs("greet","

    {{message}}

    "); + can.view("greet",{message: "Hello"}) //-> docFrag[

    Hello

    ] + +@param {String} template A Mustache template in string form. + +@return {can.view.renderer} A renderer function that takes data and helpers. + +@body + +`can.view.mustache([id,] template)` registers an Mustache template string +for a given id programatically. The following +registers `myStache` and renders it into a documentFragment. + + can.viewmustache('myStache', '

    {{message}}

    '); + + var frag = can.view('myStache', { + message : 'Hello there!' + }); + + frag // ->

    Hello there!

    + +To convert the template into a render function, just pass +the template. Call the render function with the data +you want to pass to the template and it returns the +documentFragment. + + var renderer = can.view.mustache('
    {{message}}
    '); + renderer({ + message : 'Mustache' + }); // ->
    Mustache
    \ No newline at end of file diff --git a/view/view.md b/view/doc/view.md similarity index 99% rename from view/view.md rename to view/doc/view.md index b0e3b87af42..3adbcc078d0 100644 --- a/view/view.md +++ b/view/doc/view.md @@ -2,7 +2,7 @@ @parent canjs @group can.view.static static @group can.view.plugins plugins -@link ../docco/view.html docco +@link ../docco/view/view.html docco @description Utilities for loading, processing, rendering, and live-updating of templates. diff --git a/view/view.js b/view/view.js index 52a270bd303..4e565d11f98 100644 --- a/view/view.js +++ b/view/view.js @@ -1,44 +1,212 @@ +// # can/view/view.js +// ------- +// `can.view` +// _Templating abstraction._ +// can.view loads templates based on a registered type, and given a set of data, returns a document fragment +// from the template engine's rendering method +// steal('can/util', function (can) { - // ## view.js - // `can.view` - // _Templating abstraction._ var isFunction = can.isFunction, makeArray = can.makeArray, // Used for hookup `id`s. - hookupId = 1, - // Makes a renderer function. - makeRenderer = function(textRenderer) { - var renderer = function() { - return $view.frag(textRenderer.apply(this, arguments)); - }; - renderer.render = function() { - return textRenderer.apply(textRenderer, arguments); - }; - return renderer; - }, - /** - * @add can.view - */ - $view = can.view = can.template = function (view, data, helpers, callback) { - // If helpers is a `function`, it is actually a callback. - if (isFunction(helpers)) { - callback = helpers; - helpers = undefined; + hookupId = 1; + + // internal utility methods + // ------------------------ + + // ##### makeRenderer + /** + * @hide + * Rendering function factory method + * @param textRenderer + * @returns {renderer} + */ + var makeRenderer = function(textRenderer) { + var renderer = function() { + return $view.frag(textRenderer.apply(this, arguments)); + }; + renderer.render = function() { + return textRenderer.apply(textRenderer, arguments); + }; + return renderer; + }; + + // ##### checkText + // Makes sure there's a template, if not, have `steal` provide a warning. + var checkText = function (text, url) { + if (!text.length) { + + // _removed if not used as a steal module_ + + //!steal-remove-start + can.dev.log("can/view/view.js: There is no template or an empty template at " + url); + //!steal-remove-end + + throw "can.view: No template or empty template:" + url; + } + }; + + // ##### get + // get a deferred renderer for provided url + /** + * @hide + * @function get + * @param {String | Object} obj url string or object with url property + * @param {Boolean} async If the ajax request should be asynchronous. + * @returns {can.Deferred} a `view` renderer deferred. + */ + var get = function (obj, async) { + var url = typeof obj === 'string' ? obj : obj.url, + suffix = (obj.engine && '.' + obj.engine) || url.match(/\.[\w\d]+$/), + type, + // If we are reading a script element for the content of the template, + // `el` will be set to that script element. + el, + // A unique identifier for the view (used for caching). + // This is typically derived from the element id or + // the url for the template. + id; + + //If the url has a #, we assume we want to use an inline template + //from a script element and not current page's HTML + if (url.match(/^#/)) { + url = url.substr(1); + } + // If we have an inline template, derive the suffix from the `text/???` part. + // This only supports `