This plugin implements task lists, a form of markup compatible with GitHub/GitLab Flavored Markdown and other dialects.

This plugin requires a LI tag to function properly. If there is no LI tag defined when the plugin is initialized, the Litedown plugin is automatically loaded.

Each task is assigned a pseudo-random alphanumeric ID generated at parsing time.

Syntax

A task is represented by a [x] or [ ] marker immediately following a list item.

Markdown style:

- [x] Checked
- [ ] Unchecked

BBCode style:

[list]
[*][x] Checked
[*][ ] Unchecked
[/list]

References

Examples

Note that in all of the reference outputs, random IDs have been replaced with a ... placeholder for convenience.

$configurator = new s9e\TextFormatter\Configurator;
$configurator->Litedown;
$configurator->TaskLists;

// Get an instance of the parser and the renderer
extract($configurator->finalize());

$text = "- [x] checked\n"
      . "- [X] Checked\n"
      . "- [ ] unchecked";
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html;
<ul><li data-task-id="..." data-task-state="checked"><input data-task-id="..." type="checkbox" checked disabled> checked</li>
<li data-task-id="..." data-task-state="checked"><input data-task-id="..." type="checkbox" checked disabled> Checked</li>
<li data-task-id="..." data-task-state="unchecked"><input data-task-id="..." type="checkbox" disabled> unchecked</li></ul>

Allow tasks to be toggled

Setting the TASKLISTS_EDITABLE parameter to a non-empty value will make tasks editable.

$configurator = new s9e\TextFormatter\Configurator;
$configurator->Litedown;
$configurator->TaskLists;

extract($configurator->finalize());

$text = "- [x] checked\n"
      . "- [ ] unchecked";
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

echo $html, "\n\n";

// Render it again but make the tasks editable
$renderer->setParameter('TASKLISTS_EDITABLE', '1');

echo $renderer->render($xml);
<ul><li data-task-id="..." data-task-state="checked"><input data-task-id="..." type="checkbox" checked disabled> checked</li>
<li data-task-id="..." data-task-state="unchecked"><input data-task-id="..." type="checkbox" disabled> unchecked</li></ul>

<ul><li data-task-id="..." data-task-state="checked"><input data-task-id="..." type="checkbox" checked> checked</li>
<li data-task-id="..." data-task-state="unchecked"><input data-task-id="..." type="checkbox"> unchecked</li></ul>

Using the API

The Helper class provides an API to extract stats from, and change a task's state in the XML representation of a parsed text.

use s9e\TextFormatter\Plugins\TaskLists\Helper;
use s9e\TextFormatter\Unparser;

$configurator = new s9e\TextFormatter\Configurator;
$configurator->Litedown;
$configurator->TaskLists;

extract($configurator->finalize());

$text = "- [ ] First\n"
      . "- [ ] Second";
$xml  = $parser->parse($text);
$html = $renderer->render($xml);

// Capture the first task's ID from the HTML
preg_match('(data-task-id="(\\w+))', $html, $match);
$id = $match[1];

// Show the original text and stats
echo "Before:\n", Unparser::unparse($xml), "\n\n", json_encode(Helper::getStats($xml)), "\n\n";

// Change the state of a given task with checkTask() or uncheckTask()
$xml = Helper::checkTask($xml, $id);

// Show the updated text and stats
echo "After:\n", Unparser::unparse($xml), "\n\n", json_encode(Helper::getStats($xml));
Before:
- [ ] First
- [ ] Second

{"checked":0,"unchecked":2}

After:
- [x] First
- [ ] Second

{"checked":1,"unchecked":1}

Styling task lists

Task lists can be styled via the data-task-* attributes. A common pattern is to hide the list item in unordered lists and cross-out checked tasks.

ul > li[data-task-id]
{
    list-style-type: none;
}
li[data-task-state="checked"]
{
    text-decoration: line-through rgba(0, 0, 0, .6);
}