Add cancelable tasklist:change event

The tasklist:change event defaults to firing the tasklist:changed event
after performing the update unless it's been canceled.

Add $.fn.enableTaskList and $.fn.disableTaskList.

Clean up some docs.

Author: mtodd

app/assets/javascripts/task_lists.coffee

@@ -5,6 +5,7 @@
 #= provides tasklist:changing
 #= provides tasklist:change
 #
+#= require crema/element/fire
 #= require crema/events/pageupdate
 #
 # Enables Task List update behavior.
@@ -27,7 +28,7 @@
 #
 # ### Specification
 #
-# TaskLists MUST be contained in a `div.js-task-list-container`.
+# TaskLists MUST be contained in a `(div).js-task-list-container`.
 #
 # TaskList Items SHOULD be an a list (`UL`/`OL`) element.
 #
@@ -38,9 +39,10 @@
 # `value` attribute is the source (Markdown) to be udpated. The source MUST
 # follow the syntax guidelines.
 #
-# TaskList updates trigger `tasklist:change` events.
+# TaskList updates trigger `tasklist:change` events. If the change is
+# successful, `tasklist:changed` is fired. The change can be canceled.
 #
-# jQuery is required and the `$.pageUpdate` behavior MUST be available.
+# jQuery and crema are required.
 #
 # ### Events
 #
@@ -112,7 +114,25 @@ updateTaskListItem = (source, itemIndex, checked) ->
     line
   result.join("\n")
 
-# Enables task list items to trigger updates.
+# 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 = ($item) ->
+  $container = $item.closest '.js-task-list-container'
+  $field     = $container.find '.js-task-list-field'
+  index      = 1 + $container.find('.task-list-item-checkbox').index($item)
+  checked    = $item.prop 'checked'
+
+  $field.fire 'tasklist:change', [index, checked], ->
+    $field.val updateTaskListItem($field.val(), index, checked)
+    $field.trigger 'change'
+    $field.fire 'tasklist:changed', [index, checked]
+
+# When the task list item checkbox is updated, submit the change
+$(document).on 'change', '.task-list-item-checkbox', ->
+  updateTaskList $(this)
+
+# Enables TaskList item changes.
 enableTaskList = ($container) ->
   if $container.find('.js-task-list-field').length > 0
     $container.
@@ -121,39 +141,32 @@ enableTaskList = ($container) ->
     $container.addClass('is-task-list-enabled').
       trigger 'tasklist:enabled'
 
+# Enables a collection of TaskList containers.
+$.fn.enableTaskList = ->
+  for container in this
+    enableTaskList $(container)
+
+# (Re)enable a TaskList container.
+$(document).on 'tasklist:enable', '.js-task-list-container', (event) ->
+  enableTaskList $(this)
+
+# Disable TaskList item changes.
 disableTaskList = ($container) ->
   $container.
     find('.task-list-item').removeClass('enabled').
     find('.task-list-item-checkbox').attr('disabled', 'disabled')
   $container.removeClass('is-task-list-enabled').
     trigger 'tasklist:disabled'
 
-# Updates the $field value to reflect the state of $item.
-# Triggers the `tasklist:change` event when the value has changed.
-updateTaskList = ($item) ->
-  $container = $item.closest '.js-task-list-container'
-  $field     = $container.find '.js-task-list-field'
-  index      = 1 + $container.find('.task-list-item-checkbox').index($item)
-  checked    = $item.prop 'checked'
-
-  $container.trigger 'tasklist:changing', [index, checked]
-  $field.val updateTaskListItem($field.val(), index, checked)
-  $field.trigger 'change'
-  $field.trigger 'tasklist:change', [index, checked]
-
-# When the task list item checkbox is updated, submit the change
-$(document).on 'change', '.task-list-item-checkbox', ->
-  updateTaskList $(this)
+# Disables a collection of TaskList containers.
+$.fn.disableTaskList = ->
+  for container in this
+    disableTaskList $(container)
 
 # Disable a TaskList container.
 $(document).on 'tasklist:disable', '.js-task-list-container', (event) ->
   disableTaskList $(this)
 
-# (Re)enable a TaskList container.
-$(document).on 'tasklist:enable', '.js-task-list-container', (event) ->
-  enableTaskList $(this)
-
 # When the page is updated, enable new TaskList containers.
 $.pageUpdate ->
-  $('.js-task-list-container').each ->
-    enableTaskList $(this)
+  $('.js-task-list-container').enableTaskList()

test/functional/test_task_lists_behavior.html

@@ -14,9 +14,11 @@
         $('.log').prepend("<li class='timestamp'><time>" + new Date + "</time></li>")
     }, 3000)
 
+    $(document).on('tasklist:enable', logEvent)
     $(document).on('tasklist:enabled', logEvent)
     $(document).on('tasklist:disabled', logEvent)
-    $(document).on('tasklist:change', '.js-task-list-field', function(event){
+    $(document).on('tasklist:change', logEvent)
+    $(document).on('tasklist:changed', '.js-task-list-field', function(event){
       logEvent(event)
       $(this).closest('form').submit()
     })

test/unit/test_events.coffee

@@ -2,8 +2,6 @@
 
 module "TaskList events",
   setup: ->
-    window.linkActivated = false
-
     @container = $ '<div>', class: 'js-task-list-container'
 
     @list = $ '<ul>', class: 'task-list'
@@ -28,8 +26,9 @@ module "TaskList events",
     $(document).off 'tasklist:enabled'
     $(document).off 'tasklist:disabled'
     $(document).off 'tasklist:change'
+    $(document).off 'tasklist:changed'
 
-asyncTest "triggers a tasklist:change event on task list item changes", ->
+asyncTest "triggers a tasklist:change event before making task list item changes", ->
   expect 1
 
   @field.on 'tasklist:change', (event, index, checked) ->
@@ -41,38 +40,56 @@ asyncTest "triggers a tasklist:change event on task list item changes", ->
 
   @checkbox.click()
 
-asyncTest "enables task list items when a .js-task-list-field is present", ->
+asyncTest "triggers a tasklist:changed event once a task list item changes", ->
   expect 1
 
-  $(document).on 'tasklist:enabled', (event) ->
+  @field.on 'tasklist:changed', (event, index, checked) ->
     ok true
 
-  @container.pageUpdate()
   setTimeout ->
     start()
   , 20
 
-asyncTest "doesn't enable task list items when a .js-task-list-field is absent", ->
-  expect 0
+  @checkbox.click()
 
-  $(document).on 'tasklist:enabled', (event) ->
+asyncTest "can cancel a tasklist:changed event", ->
+  expect 2
+
+  @field.on 'tasklist:change', (event, index, checked) ->
     ok true
+    event.preventDefault()
 
-  @field.remove()
+  @field.on 'tasklist:changed', (event, index, checked) ->
+    ok false
 
-  @container.pageUpdate()
-  setTimeout ->
+  before = @checkbox.val()
+  setTimeout =>
+    equal before, @checkbox.val()
     start()
   , 20
 
-asyncTest "disables task list items when changing source", ->
+  @checkbox.click()
+
+asyncTest "enables task list items when a .js-task-list-field is present", ->
   expect 1
 
-  $(document).on 'tasklist:disabled', (event) ->
+  $(document).on 'tasklist:enabled', (event) ->
     ok true
 
+  @container.pageUpdate()
   setTimeout ->
     start()
   , 20
 
-  @checkbox.click()
+asyncTest "doesn't enable task list items when a .js-task-list-field is absent", ->
+  expect 0
+
+  $(document).on 'tasklist:enabled', (event) ->
+    ok true
+
+  @field.remove()
+
+  @container.pageUpdate()
+  setTimeout ->
+    start()
+  , 20

test/unit/test_updates.coffee

@@ -2,8 +2,6 @@
 
 module "TaskList updates",
   setup: ->
-    window.linkActivated = false
-
     @container = $ '<div>', class: 'js-task-list-container'
 
     @list = $ '<ul>', class: 'task-list'
@@ -13,7 +11,7 @@ module "TaskList updates",
       type: 'checkbox'
       class: 'task-list-item-checkbox'
       disabled: true
-      checked: true # yup
+      checked: true
 
     @incompleteItem = $ '<li>', class: 'task-list-item'
     @incompleteCheckbox = $ '<input>',
@@ -51,12 +49,12 @@ module "TaskList updates",
     $('#qunit-fixture').append(@container).pageUpdate()
 
   teardown: ->
-    $(document).off 'tasklist:change'
+    $(document).off 'tasklist:changed'
 
 asyncTest "updates the source, marking the incomplete item as complete", ->
   expect 3
 
-  @field.on 'tasklist:change', (event, index, checked) =>
+  @field.on 'tasklist:changed', (event, index, checked) =>
     ok checked
     equal index, @incompleteItem.expectedIndex
     equal @field.val(), @changes.toIncomplete
@@ -70,7 +68,7 @@ asyncTest "updates the source, marking the incomplete item as complete", ->
 asyncTest "updates the source, marking the complete item as incomplete", ->
   expect 3
 
-  @field.on 'tasklist:change', (event, index, checked) =>
+  @field.on 'tasklist:changed', (event, index, checked) =>
     ok !checked
     equal index, @completeItem.expectedIndex
     equal @field.val(), @changes.toComplete