gfm-task-list

This plugin is based on the work previously done on github-archive/task_list. That plugin has been deprecated and this plugin picks up where it left off.

jQuery plugin for enabling GitHub Flavored Markdown (GFM) task lists for third-party integrations to GitHub.

Getting Started

Installation

You can find the built library in unpkg. You may either download them and serve them from your app or load them directly from unpkg.

unpkg

<link href="https://unpkg.com/gfm-task-list@1.0.3/dist/gfm-task-list.min.css" rel="stylesheet" type="text/css"></link>
<script src="https://unpkg.com/gfm-task-list@1.0.3/dist/gfm-task-list.min.js"></script>

Usage

HTML Structure

gfmTaskList expects your html to have a structure similar to:

<div class="container">
  <textarea class="markdown-editor"></textarea>
  <div class="rendered-markdown"></div>
</div>

You are responsible for populating .markdown-editor with the markdown of the issue or comment body as well as for populating .rendered-markdown with the rendered html for that markdown.

Initialization

gfmTaskList is written as a jQuery plugin. To initialize a task list, you must specify which element contains the raw markdown and which element contains the rendered html. For example:

$('.container').gfmTaskList({
  markdownContainer: '.markdown-editor',
  renderedContainer: '.rendered-markdown'
});

Configuration Properties

Property	Required	Type	Behavior
markdownContainer	true	`String	jQuery`
renderedContainer	true	`String	jQuery`
onUpdate	false	function	A callback function that receives one argument of type string that is the updated markdown after a checkbox has been updated.

Once initialized, the task list check boxes will be enabled and any change in the state of the checkboxes within the rendered container will be reflected in the markdown in the markdown container.

Handling Task List Updates

You can handle updates by either passing an onUpdate callback at the time of initialization:

$('.container').gfmTaskList({
  markdownContainer: '.markdown-editor',
  renderedContainer: '.rendered-markdown',
  onUpdate: function(updatedMarkdown) {
    // Handle the update, generally involves sending a PATCH request to GitHub to update the issue/comment.
  }
});

or by listening for the plugin's jQuery events:

$('.container').on('tasklist:changed', function(event, index, checked) {
  var updatedMarkdown = $('.markdown-editor').val();
  // PATCH request to GitHub to update the issue/comment.
});

Methods

After initializing a task list, you may enable or disable the list.

Note: The task list will automatically be enabled after initialization.

Enable

$('.container').gfmTaskList('enable');

Disable

$('.container').gfmTaskList('enable');

Events

All events are fired from the element used to initialize gfmTaskList.

tasklist:enabled

Fired when a task list has been enabled. Ex:

$('.container').on('tasklist:enabled', function(event) {});

tasklist:disabled

Fired when a task list has been disabled. Ex:

$('.container').on('tasklist:disabled', function(event) {});

tasklist:change

Fired when a checkbox has been checked/unchecked, but before the associated markdown has been updated. You may call event.preventDefault() within this event handler to stop the markdown from being updated. Ex:

$('.container').on('tasklist:change', function(event) {
  // event.preventDefault()
});

tasklist:changed

Fired after a checkbox has been checked/unchecked and the associated markdown has been updated. At this point, you are ready to send a PATCH request to GitHub to update the issue/comment.

$('.container').on('tasklist:changed', function(event) {});

Development

Please review our contributing guidelines for instructions on how to get started with contributing to this project.