Mark Lavin avatar Mark Lavin committed 56ad86e

Release notes and better comments for JS.

Comments (0)

Files changed (2)

docs/releases.rst

 _________________
 
 - Better compatibility with :ref:`AutoCompleteSelectWidget`/:ref:`AutoComboboxSelectWidget` and Django's ModelChoiceField
+- Better compatibility with the Django admin related objects popup
 - Easier passing of query parameters. See the :ref:`Additional Parameters <additional-parameters>` section
+- Additional documentation
 
 
 Backwards Incompatible Changes

selectable/static/selectable/js/jquery.dj.selectable.js

         },
         
         _initDeck: function() {
+            /* Create list display for currently selected items for multi-select */
             var self = this;
             var data = $(this.element).data();
             var style = data.selectablePosition || data['selectable-position'] || 'bottom';
         },
 
         _addDeckItem: function(input) {
+            /* Add new deck list item from a given hidden input */
             var self = this;
             $('<li>')
             .text($(input).attr('title'))
         },
 
         select: function(item) {
+            /* Trigger selection of a given item.
+            Item should contain two properties: id and value */
             var self = this,
             input = this.element;
             $(input).removeClass('ui-state-error');
         },
 
         _create: function() {
+            /* Initialize a new selectable widget */
             var self = this,
             input = this.element,
             data = $(input).data();
             }
 
             function dataSource(request, response) {
+                /* Custom data source to uses the lookup url with pagination
+                Adds hook for adjusting query parameters.
+                Includes timestamp to prevent browser caching the lookup. */
                 var url = data.selectableUrl || data['selectable-url'];
                 var now = new Date().getTime();
                 var query = {term: request.term, timestamp: now};
                 }
 				$.getJSON(url, query, response);
             }
-
+            // Create base auto-complete lookup
             $(input).autocomplete({
                 source: dataSource,
                 change: function(event, ui) {
                 select: function(event, ui) {
                     $(input).removeClass('ui-state-error');
                     if (ui.item && ui.item.page) {
+                        // Set current page value
                         $(input).data("page", ui.tem.page);
                         $('.selectable-paginator', self.menu).remove();
+                        // Search for next page of results
                         $(input).autocomplete("search");
                         return false;
                     }
                     self.select(ui.item);
                 }
             }).addClass("ui-widget ui-widget-content ui-corner-all");
-
+            // Override the default auto-complete render.
             $(input).data("autocomplete")._renderItem = function(ul, item) {
+                /* Adds hook for additional formatting, allows HTML in the label,
+                highlights term matches and handles pagination. */
                 var label = item.label;
                 if (self.options.formatLabel) {
                     label = self.options.formatLabel(label, item);
                 }
                 return li;
             };
-
+            // Override the default auto-complete suggest.
             $(input).data("autocomplete")._suggest = function(items) {
+                /* Needed for handling pagination links */
                 var page = $(input).data('page');
                 var ul = this.menu.element;
                 if (!page) {
                     this.menu.next(new $.Event("mouseover"));
                 }
             };
-
+            // Additional work for combobox widgets
             var selectableType = data.selectableType || data['selectable-type'];
             if (selectableType === 'combobox') {
                 // Change auto-complete options
                 })
                 .removeClass("ui-corner-all")
                 .addClass("ui-corner-left ui-combo-input");
-
+                // Add show all items button
                 $("<button>&nbsp;</button>").attr("tabIndex", -1).attr("title", "Show All Items")
                 .insertAfter($(input))
                 .button({
                         $(input).autocomplete("close");
                         return false;
                     }
-
                     // pass empty string as value to search for, displaying all results
                     $(input).autocomplete("search", "");
                     $(input).focus();
 })(jQuery);
 
 function bindSelectables(context) {
+    /* Bind all selectable widgets in a given context.
+    Automatically called on document.ready.
+    Additional calls can be made for dynamically added widgets.
+    */
     $(":input[data-selectable-type=text]", context).djselectable();
     $(":input[data-selectable-type=combobox]", context).djselectable();
     $(":input[data-selectable-type=hidden]", context).each(function(i, elem) {
             };
             var added = null;
             if (options.added) {
+                // Wrap previous added function and include call to bindSelectables
                 var oldadded = options.added;
                 added = function(row) { oldadded(row); addedevent(row); };
             }
 }
 
 $(document).ready(function() {
+    // Bind existing widgets on document ready
     bindSelectables('body');
 });
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.