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 make setup to install dependencies.

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

To release a new version:

1. Update version number in lib/html/pipeline/task_list/version.rb
2. Run make push-gem

Pushihg the git commits and tags will force CI to automatically push to RubyGems.org.

Testing

before beginning testing, be sure to run make setup

To run Ruby and Javascript unit tests and linting, run make test.

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

1. run npm start
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!