Task List

This Gem provides various components necessary for integrating Task Lists into your GitHub-flavored-Markdown user content.

HTML::Pipeline::TaskList is a successor to TaskList which GitHub stopped supporting and updating in 2016. This gem updates key components to support changes to underlying gems.

Components

The Task List feature is made of several different components:

  • GitHub-flavored-Markdown Ruby Filter
  • Summary Ruby Model: summarizes task list items
  • JavaScript: frontend task list update behavior
  • CSS: styles Markdown task list items

Usage & Integration

The backend components are designed for rendering the Task List item checkboxes, and the frontend components handle updating the Markdown source (embedded in the markup).

Backend: Markdown pipeline filter

Rendering Task List item checkboxes from source Markdown depends on the HTML::Pipeline::TaskList::Filter, designed to integrate with the html-pipeline gem. For example:

require 'html/pipeline'
require 'html/pipeline/task_list/filter'

pipeline = HTML::Pipeline.new [
  HTML::Pipeline::MarkdownFilter,
  HTML::Pipeline::TaskList::Filter
]

pipeline.call "- [ ] task list item"

Frontend: Markdown Updates

Task List updates on the frontend require specific HTML markup structure, and must be enabled with JavaScript.

Rendered HTML (the <ul> element below) should be contained in a js-task-list-container container element and include a sibling textarea.js-task-list-field element that is updated when checkboxes are changed.

- [ ] text

<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>

Enable Task List updates with:

$('.js-task-list-container').taskList('enable')

NOTE: Updates are not persisted to the server automatically. Persistence is the responsibility of the integrating application, accomplished by hooking into the tasklist:change JavaScript event. For instance, we use AJAX to submit a hidden form on update.

Read through the documented behaviors and samples in the source for more detail, including documented events.

Installation

Backend: RubyGem

For the backend Ruby components, add this line to your application's Gemfile:

gem 'html-pipeline-task_list', '~> 0.0'

And then execute bundle install

Development

After checking out the repo, run bundle install && npm install to install dependencies.

To install this gem onto your local machine, run bundle exec rake install

To release a new version, update run bundle exec rake release to create a git tag for the version. push the git commits and tags and CI will automatically push to RubyGems.org.

Testing

before beginning testing, be sure to run bundle install && npm install

Ruby unit tests can be run with bundle exec rake test. Javascript unit tests can be run with npm test

Functional tests can be run manually in the browser. To do so:

  1. run npm run server
  2. open a browser to http://localhost:3000/test/behavior.html
  3. you can also see the QUnit tests at http://localhost:4011/test/qunit.html

Contributing

Read the Contributing Guidelines and open a Pull Request!