diff options
Diffstat (limited to 'vendor/assets/javascripts/task_list.js')
| -rw-r--r-- | vendor/assets/javascripts/task_list.js | 161 |
1 files changed, 150 insertions, 11 deletions
diff --git a/vendor/assets/javascripts/task_list.js b/vendor/assets/javascripts/task_list.js index bc451506b6a..9fbfef03f6d 100644 --- a/vendor/assets/javascripts/task_list.js +++ b/vendor/assets/javascripts/task_list.js @@ -1,15 +1,118 @@ - +// The MIT License (MIT) +// +// Copyright (c) 2014 GitHub, Inc. +// +// 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. +// TaskList Behavior +// /*= provides tasklist:enabled */ - - /*= provides tasklist:disabled */ - - /*= provides tasklist:change */ - - /*= provides tasklist:changed */ - +// +// +// Enables Task List update behavior. +// +// ### Example Markup +// +// <div class="js-task-list-container"> +// <ul class="task-list"> +// <li class="task-list-item"> +// <input type="checkbox" class="js-task-list-item-checkbox" disabled /> +// text +// </li> +// </ul> +// <form> +// <textarea class="js-task-list-field">- [ ] text</textarea> +// </form> +// </div> +// +// ### Specification +// +// TaskLists MUST be contained in a `(div).js-task-list-container`. +// +// TaskList Items SHOULD be an a list (`UL`/`OL`) element. +// +// Task list items MUST match `(input).task-list-item-checkbox` and MUST be +// `disabled` by default. +// +// TaskLists MUST have a `(textarea).js-task-list-field` form element whose +// `value` attribute is the source (Markdown) to be udpated. The source MUST +// follow the syntax guidelines. +// +// TaskList updates trigger `tasklist:change` events. If the change is +// successful, `tasklist:changed` is fired. The change can be canceled. +// +// jQuery is required. +// +// ### Methods +// +// `.taskList('enable')` or `.taskList()` +// +// Enables TaskList updates for the container. +// +// `.taskList('disable')` +// +// Disables TaskList updates for the container. +// +//# ### Events +// +// `tasklist:enabled` +// +// Fired when the TaskList is enabled. +// +// * **Synchronicity** Sync +// * **Bubbles** Yes +// * **Cancelable** No +// * **Target** `.js-task-list-container` +// +// `tasklist:disabled` +// +// Fired when the TaskList is disabled. +// +// * **Synchronicity** Sync +// * **Bubbles** Yes +// * **Cancelable** No +// * **Target** `.js-task-list-container` +// +// `tasklist:change` +// +// Fired before the TaskList item change takes affect. +// +// * **Synchronicity** Sync +// * **Bubbles** Yes +// * **Cancelable** Yes +// * **Target** `.js-task-list-field` +// +// `tasklist:changed` +// +// Fired once the TaskList item change has taken affect. +// +// * **Synchronicity** Sync +// * **Bubbles** Yes +// * **Cancelable** No +// * **Target** `.js-task-list-field` +// +// ### NOTE +// +// Task list checkboxes are rendered as disabled by default because rendered +// user content is cached without regard for the viewer. (function() { var codeFencesPattern, complete, completePattern, disableTaskList, disableTaskLists, enableTaskList, enableTaskLists, escapePattern, incomplete, incompletePattern, itemPattern, itemsInParasPattern, updateTaskList, updateTaskListItem, indexOf = [].indexOf || function(item) { for (var i = 0, l = this.length; i < l; i++) { if (i in this && this[i] === item) return i; } return -1; }; @@ -18,20 +121,48 @@ complete = "[x]"; + // Escapes the String for regular expression matching. escapePattern = function(str) { return str.replace(/([\[\]])/g, "\\$1").replace(/\s/, "\\s").replace("x", "[xX]"); }; - incompletePattern = RegExp("" + (escapePattern(incomplete))); - - completePattern = RegExp("" + (escapePattern(complete))); + incompletePattern = RegExp("" + (escapePattern(incomplete))); // escape square brackets + // match all white space + completePattern = RegExp("" + (escapePattern(complete))); // match all cases + // Pattern used to identify all task list items. + // Useful when you need iterate over all items. itemPattern = RegExp("^(?:\\s*(?:>\\s*)*(?:[-+*]|(?:\\d+\\.)))\\s*(" + (escapePattern(complete)) + "|" + (escapePattern(incomplete)) + ")\\s+(?!\\(.*?\\))(?=(?:\\[.*?\\]\\s*(?:\\[.*?\\]|\\(.*?\\))\\s*)*(?:[^\\[]|$))"); + // prefix, consisting of + // optional leading whitespace + // zero or more blockquotes + // list item indicator + // optional whitespace prefix + // checkbox + // is followed by whitespace + // is not part of a [foo](url) link + // and is followed by zero or more links + // and either a non-link or the end of the string + // Used to filter out code fences from the source for comparison only. + // http://rubular.com/r/x5EwZVrloI + // Modified slightly due to issues with JS codeFencesPattern = /^`{3}(?:\s*\w+)?[\S\s].*[\S\s]^`{3}$/mg; + // ``` + // followed by optional language + // whitespace + // code + // whitespace + // ``` + // Used to filter out potential mismatches (items not in lists). + // http://rubular.com/r/OInl6CiePy itemsInParasPattern = RegExp("^(" + (escapePattern(complete)) + "|" + (escapePattern(incomplete)) + ").+$", "g"); + // Given the source text, updates the appropriate task list item to match the + // given checked value. + // + // Returns the updated String text. updateTaskListItem = function(source, itemIndex, checked) { var clean, index, line, result; clean = source.replace(/\r/g, '').replace(codeFencesPattern, '').replace(itemsInParasPattern, '').split("\n"); @@ -55,6 +186,9 @@ return result.join("\n"); }; + // Updates the $field value to reflect the state of $item. + // Triggers the `tasklist:change` event before the value has changed, and fires + // a `tasklist:changed` event once the value has changed. updateTaskList = function($item) { var $container, $field, checked, event, index; $container = $item.closest('.js-task-list-container'); @@ -70,10 +204,12 @@ } }; + // When the task list item checkbox is updated, submit the change $(document).on('change', '.task-list-item-checkbox', function() { return updateTaskList($(this)); }); + // Enables TaskList item changes. enableTaskList = function($container) { if ($container.find('.js-task-list-field').length > 0) { $container.find('.task-list-item').addClass('enabled').find('.task-list-item-checkbox').attr('disabled', null); @@ -81,6 +217,7 @@ } }; + // Enables a collection of TaskList containers. enableTaskLists = function($containers) { var container, i, len, results; results = []; @@ -91,11 +228,13 @@ return results; }; + // Disable TaskList item changes. disableTaskList = function($container) { $container.find('.task-list-item').removeClass('enabled').find('.task-list-item-checkbox').attr('disabled', 'disabled'); return $container.removeClass('is-task-list-enabled').trigger('tasklist:disabled'); }; + // Disables a collection of TaskList containers. disableTaskLists = function($containers) { var container, i, len, results; results = []; |