pax_global_header00006660000000000000000000000064125242314730014515gustar00rootroot0000000000000052 comment=d18937c085356dcefc887618b8422660440b534a nytimes-backbone.stickit-d18937c/000077500000000000000000000000001252423147300167645ustar00rootroot00000000000000nytimes-backbone.stickit-d18937c/.gitignore000066400000000000000000000001501252423147300207500ustar00rootroot00000000000000build dist node_modules npm-debug.log docs gh-pages *.diff *.patch *.bak *.log *.swp .DS_Store .project nytimes-backbone.stickit-d18937c/.travis.yml000066400000000000000000000005211252423147300210730ustar00rootroot00000000000000language: node_js node_js: - "0.12" - "0.11" - "0.10" deploy: email: amk528@cs.nyu.edu provider: npm api_key: secure: pEowAgsG9ULWrGt0cV+uP3Iq48GiC7qseB7I+LI0vcJdphy8hevCU/z8yJ9Q4pY/UJy9KvOcwlAtGdjmWXxeB7GUA8EfjcFImiFOEryog+ahuF1fCG8i5pZ6EACFcEq4CzBVnBdBSYFgZtMdS+wUSB2AstHEhB412bBLTa/q81Q= notifications: email: false nytimes-backbone.stickit-d18937c/Gruntfile.js000066400000000000000000000053571252423147300212730ustar00rootroot00000000000000module.exports = function(grunt) { grunt.initConfig({ pkg: grunt.file.readJSON('package.json'), lint: { all: ['backbone.stickit.js'] }, jshint: { src: ['backbone.stickit.js'], options: { browser: true, indent: 2, white: false, evil: true, regexdash: true, wsh: true, trailing: true, eqnull: true, expr: true, boss: true, node: true, strict: false } }, qunit: { all: { options: { urls: ['http://localhost:3000/test/index.html'] } } }, server: { port: 8000, base: '.' }, concat: { options: { stripBanners: true, banner: '//\n' + '// <%= pkg.name %> - v<%= pkg.version %>\n' + '// The MIT License\n' + '// Copyright (c) 2012 The New York Times, CMS Group, Matthew DeLambo \n' + '//\n' }, dist: { src: 'backbone.stickit.js', dest: 'dist/backbone.stickit.js' } }, uglify: { options: { banner: '//\n' + '// <%= pkg.name %> - v<%= pkg.version %>\n' + '// The MIT License\n' + '// Copyright (c) 2012 The New York Times, CMS Group, Matthew DeLambo \n' + '//\n' }, nasty: { options: { preserveComments: false }, files: { 'dist/backbone.stickit.min.js': ['backbone.stickit.js'] } } }, docco: { app: { src: ['dist/backbone.stickit.js'], dest: "docs/" } }, compress: { gz: { options: { mode: 'gzip' }, expand: true, cwd: 'dist/', src: ['backbone.stickit.min.js'], dest: 'dist/' }, zip: { options: { archive: 'dist/backbone.stickit_<%= pkg.version %>.zip' }, files: [ {src: './**', cwd: 'dist/', expand:true} ] } }, clean: { build: ['dist'], docco: ['docs'] } }); grunt.loadNpmTasks('grunt-docco'); grunt.loadNpmTasks('grunt-contrib-concat'); grunt.loadNpmTasks('grunt-contrib-jshint'); grunt.loadNpmTasks('grunt-contrib-qunit'); grunt.loadNpmTasks('grunt-contrib-uglify'); grunt.loadNpmTasks('grunt-contrib-clean'); grunt.loadNpmTasks('grunt-contrib-compress'); grunt.registerTask('build', ['jshint', 'clean:build', 'uglify:nasty', 'concat', 'compress:gz', 'cp-docs', 'compress:zip']); grunt.registerTask('cp-docs', function() { grunt.file.copy('docs/docco.css', 'dist/docs/annotated/docco.css'); grunt.file.copy('docs/backbone.stickit.html', 'dist/docs/annotated/index.html'); }); }; nytimes-backbone.stickit-d18937c/LICENSE000066400000000000000000000021541252423147300177730ustar00rootroot00000000000000The MIT License Copyright (c) 2012-2015 The New York Times, CMS Group, Matthew DeLambo Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. nytimes-backbone.stickit-d18937c/README.md000066400000000000000000001026001252423147300202420ustar00rootroot00000000000000[-> **Documentation for current/stable release: 0.9.2**](http://nytimes.github.com/backbone.stickit/) **The following is documentation for the code in master/edge version...** ## Introduction Backbone's philosophy is for a View, the display of a Model's state, to re-render after any changes have been made to the Model. This works beautifully for simple apps, but rich apps often need to render, respond, and synchronize changes with finer granularity. Stickit is a Backbone data binding plugin that binds Model attributes to View elements with a myriad of options for fine-tuning a rich app experience. Unlike most model binding plugins, Stickit does not require any extra markup in your html; in fact, Stickit will clean up your templates, as you will need to interpolate fewer variables (if any at all) while rendering. In Backbone style, Stickit has a simple and flexible api which plugs in nicely to a View's lifecycle. ## Download + Source [download v0.9.2](http://nytimes.github.com/backbone.stickit/downloads/backbone.stickit_0.9.2.zip) [download master/edge](https://raw.github.com/NYTimes/backbone.stickit/master/backbone.stickit.js) [view annotated source](http://nytimes.github.com/backbone.stickit/docs/annotated/) ## Usage Similar to `view.events`, you can define `view.bindings` to map selectors to binding configurations. The following bindings configuration will bind the `view.$('#title')` element to the `title` model attribute and the `view.$('#author')` element to the `authorName` model attribute: ```javascript bindings: { '#title': 'title', '#author': 'authorName' } ``` When the view's html is rendered, usually the last call will be to stickit. By convention, and in the following example, stickit will use `view.model` and the `view.bindings` configuration to initialize: ```javascript render: function() { this.$el.html('
'); this.stickit(); } ``` On the initial call, stickit will initialize the innerHTML of `view.$('#title')` with the value of the `title` model attribute, and will setup a one-way binding (model->view) so that any time a model `change:title` event is triggered, the `view.$('#title')` element will reflect those changes. For form elements, like `view.$('#author')`, stickit will configure a two-way binding (model<->view), connecting and reflecting changes in the view elements with changes in bound model attributes. ## API ### stickit `view.stickit(optionalModel, optionalBindingsConfig)` Uses `view.bindings` and `view.model` to setup bindings. Optionally, you can pass in a model and bindings hash. Note, it is safe to re-render or call stickit multiple times, as stickit will match any previously bound selectors and their associated models and unbind them before reinitializing. ```javascript render: function() { this.$el.html(/* ... */); // Initialize stickit with view.bindings and view.model this.stickit(); // In addition to, or instead, call stickit with a different model and bindings configuration. this.stickit(this.otherModel, this.otherBindings); } ``` ### addBinding `view.addBinding(optionalModel, selector, configuration)` Adds a single binding to the view, using the given model, or `view.model`, and the given `selector` and `configuration`. It's also possible to pass in a bindings hash as the second parameter. If you use a selector that was already used for a binding, then the old binding will be destroyed before initializing the new binding. ```javascript // Short-form selector. this.addBinding(null, '#author', 'author'); // With configuration. this.addBinding(null, '#author', {observe:'author', onGet: function() {/* ... */}}); // Or, with a bindings hash. this.addBinding(null, { '#author': { observe: 'author', onGet: function() {/* ... */} }); ``` ### unstickit `view.unstickit(optionalModel, optionalSelector)` Removes event bindings from all models. Optionally, a model can be passed in which will remove events for the given model and its corresponding bindings configuration only. Another option is to pass in a binding selector or bindings hash to granularly remove any bindings that are associated with `this.model` or the given model. Note, Stickit is setup to automatically unbind all bindings associated with a view on `view.remove()`. For each model that is unbound, a `stickit:unstuck` event will be triggered, and for each binding that is unbound the `destroy` callback will be executed. ## Bindings The `view.bindings` is a hash of jQuery or Zepto selector keys with binding configuration values. Similar to the callback definitions configured in `view.events`, bindings callbacks can be defined as the name of a method on the view or a direct function body. `view.bindings` may also be defined as a function. Once you are familiarized with the bindings callbacks, use [this reference](#binding-callbacks-flowchart) for a better idea of when they are called. ### observe A string, function, or array which is used to map a model attribute to a view element. If binding to `observe` is the only configuration needed, then it can be written in short form where the attribute name is the value of the whole binding configuration. Notes on binding to an array of attributes: when binding from model->view, this configuration should be paired with an `onGet` callback that can unpack/format the values. When binding from view->model, then `onSet` or `getVal` should be defined and should return an array of values that stickit will set into the model. ```javascript bindings: { // Short form binding '#author': 'author', // Normal binding '#title': { observe: 'title' }, // Bind to multiple model attributes '#header': { observe: ['title', 'author'], onGet: function(values) { // onGet called after title *or* author model attributes change. return values[0] + '-' + values[1]; }, onSet: function(value) { return value.split('-'); } } } // Defined bindings as a function. bindings: function() { return { '#title': { observe: 'title' } }; } ``` ### :el (selector) A special selector value that binds to the view delegate (view.$el). ```javascript tagName: 'form', bindings: { ':el': { observe: 'title' onGet: function(value) { /* ... */ } } } ``` ### onGet A callback which returns a formatted version of the model attribute value that is passed in before setting it in the bound view element. ```javascript bindings: { '#header': { observe: 'headerName', onGet: 'formatHeader' } }, formatHeader: function(value, options) { return options.observe + ': ' + value; } ``` ### onSet A callback which prepares a formatted version of the view value before setting it in the model. ```javascript bindings: { '#author': { observe: 'author', onSet: 'addByline' } }, addByline: function(val, options) { return 'by ' + val; } ``` ### getVal A callback which overrides stickit's default handling for retrieving the value from the bound view element. Use `onSet` to format values - this is better used in [handlers](#custom-handlers) or when extra/different dom operations need to be handled. ```javascript bindings: { '#author': { observe: 'author', getVal: function($el, event, options) { return $el.val(); } } } ``` ### update A callback which overrides stickit's default handling for updating the value of a bound view element. Use `onGet` to format model values - this is better used in [handlers](#custom-handlers) or when extra/different dom operations need to be handled . ```javascript bindings: { '#author': { observe: 'author', update: function($el, val, model, options) { $el.val(val); } } } ``` ### updateModel A boolean value or a function that returns a boolean value which controls whether or not the model gets changes/updates from the view (model<-view). This is only relevant to form elements, as they have two-way bindings with changes that can be reflected into the model. Defaults to true. ```javascript bindings: { '#title': { observe: 'title', updateModel: 'confirmFormat' } }, confirmFormat: function(val, event, options) { // Only update the title attribute if the value starts with "by". return val.startsWith('by '); } ``` ### updateView A boolean value or a function that returns a boolean value which controls whether or not the bound view element gets changes/updates from the model (view<-model). Defaults to true. ```javascript bindings: { '#title': { observe: 'title', // Any changes to the model will not be reflected to the view. updateView: false } } ``` ### afterUpdate Called after a value is updated in the dom. ```javascript bindings: { '#warning': { observe: 'warningMessage', afterUpdate: 'highlight' } }, highlight: function($el, val, options) { $el.fadeOut(500, function() { $(this).fadeIn(500); }); } ``` ### updateMethod Method used to update the inner value of the view element. Defaults to 'text', but 'html' may also be used to update the dom element's innerHTML. ```javascript bindings: { '#header': { observe: 'headerName', updateMethod: 'html', onGet: function(val) { return '
' + val + '
'; } } } ``` ### escape A boolean which when true escapes the model before setting it in the view - internally, gets the attribute value by calling `model.escape('attribute')`. This is only useful when `updateMethod` is "html". ```javascript bindings: { '#header': { observe: 'headerName', updateMethod: 'html', escape: true } } ``` ### initialize Called for each binding after it is configured in the initial call to `stickit()`. Useful for setting up third-party plugins, see the handlers section for examples. ```javascript bindings: { '#album': { observe: 'exai', initialize: function($el, model, options) { // Setup a Chosen or thirdy-party plugin for this bound element. } } } ``` ### destroy Called for each binding after it is unstuck from the model and view. Useful for tearing down third-party plugins or events that were configured in `initialze`. ```javascript bindings: { '#album': { observe: 'Tomorrow\'s Harvest', destroy: function($el, model, options) { // Tear down any events or clean up. } } } ``` ### visible and visibleFn When true, `visible` shows or hides the view element based on the model attribute's truthiness. `visible` may also be defined with a callback which should return a truthy value. The `updateView` option defaults to `false` when using `visible`. You must opt-in to `updateView` in order to have both view element visibility and value changes bound to the observed attribute. If more than the standard jQuery show/hide is required, then you can manually take control by defining `visibleFn` with a callback. ```javascript bindings: { '#author': { observe: 'isDeleuze', visible: true } } ``` ```javascript bindings: { '#title': { observe: 'title', visible: function(val, options) { return val == 'Mille Plateaux'; }, updateView: true } } ``` ```javascript bindings: { '#body': { observe: 'isWithoutOrgans', visible: true, visibleFn: 'slideFast' } }, slideFast: function($el, isVisible, options) { if (isVisible) $el.slideDown('fast'); else $el.slideUp('fast'); } ``` ## Form Element Bindings and Contenteditable By default, form and contenteditable elements will be configured with two-way bindings, syncing changes in the view elements with model attributes. Optionally, one-way bindings can be configured with `updateView` or `updateModel`. With the `events`, you can specify a different set of events to use for reflecting changes to the model. The following is a list of the supported form elements, their binding details, and the default events used for binding: - input, textarea, and contenteditable - element value synced with model attribute value - `propertychange`, `input`, `change` events are used for handling - input[type=checkbox] - `checked` property determined by the truthiness of the model attribute or if the checkbox "value" attribute is defined, then its value is used to match against the model. If a binding selector matches multiple checkboxes then it is expected that the observed model attribute will be an array of values to match against the checkbox value attributes. - `change` event is used for handling - input[type=radio] - model attribute value matched to a radio group `value` attribute - `change` event is used for handling - select - (recommended) specify `selectOptions` to have Stickit handle the rendering and option bindings of your select (see `selectOptions`) - if you choose to pre-render your select-options (not recommended) then there are two ways of configuring the bindings: - "data-stickit-bind-val" attributes in the DOM. This allows for binding non-string values from a prerendered <select>, assuming that you are using jQuery or a build of Zepto that includes the "data" module. - "option[value]" attributes in the DOM (used if no data-stickit-bind-val is present) - `change` event is used for handling ### events Specify a list of events which will override stickit's default events for a form element. Bound events control when the model is updated with changes in the view element. ```javascript bindings: { 'input#title': { observe: 'title', // Normally, stickit would bind `keyup`, `change`, `cut`, and `paste` events // to an input:text element. The following will override these events and only // update/set the model after the input#title element is blur'ed. events: ['blur'] } } ``` ### selectOptions With the given `collection`, creates `