To Do List Basic Module

Basics

The basic To Do List module has many parts and each is documented in a separate page.

First, you will want to install the module. Note that you want to Rebuild the Post permissions. Once you are done with that step, the other sections are optional as the default settings make the system work as expected for the administrator user (i.e. user #1). If you want to allow others users to use your system, check out the Permissions and enable access to specific roles. You may want to create new roles for this purpose.

Sub-modules are available to add functionality to the basic To Do List module. These are documented elsewhere. Go Up once and select the module you want more information about.

Click on the image to see a 1:1 version.

  cd sites/all/modules
  tar -xf to_do.tar.gz

Help for To Do List End Users

Introduction

This page documents the usage of the To Do List module to end users (i.e. not how to install and setup the module, but how to create To Do List items, share them, mark them started/finished, etc.)

For administrative information check out the To Do List module help.

Creating a new To Do item

When you see the Plus icon (as shown on the left,) click on it. This brings you to a new form where you can enter a new To Do item.

When the Plus icon is not shown, look for a menu item named "Create content." Click on that link. Then one of the links on that page is called To do1. Click on that link and you are on the form where you can create a new To Do item. (Create content » To do).

The following describe the To Do specific fields. Your form may include more fields if the administrator created additional fields.

To do task

The field accepts a brief description of the To Do task. This is equivalent to a post title or subject.

Make sure to make it descriptive enough so people know what the task is about without automatically having to read the detailed description of the assignment.

Vocabularies

Your administrator may have setup different vocabularies of terms to choose from.

It is possible that he created a tree of terms used to manage who has the right to see your To Do items. In that case, you may be obligated to enter information in that vocabulary.

For more information, contact your administrator.

Assignment details

This field is optional and may be removed by your administrator. If present, enter a more detailed description as you see fit. The description can use formatting, just like any other post.

This is equivalent to a post body or content.

To authorize more people to add details, some administrator will let other users post comments to the To Do item.

Revision Information

This field is optional and may not be activated by your administrator. When present, you can use it to create multiple revisions. This is particularly useful if you want to keep track of the changes of a To Do item.

Also by default this field is optional, note that the administrator may actually require a new revision to be created each time you edit your To Do item.

The easiest way to look at different revisions at once is to make use of the Views system. If not available check with your administrator who can install the Views modules and create a page for you to check out the revision information.

To do

Define the Status and Priority of the new To Do item. The status is set to Not Started by default. The Priority is set to Medium by default.

Authorized users can change the Status from Not Started to Started, then from any other state to Finished (see below, the Assignment fields). This means if you are a To Do item administrator you can create issues and assign them to other people. These other people can then mark the issue Started and Finished as required.

The Status and Priority can only be changed by the administrator.

Dates

By default, the To Do items are not assigned a date. In other words, you won't be pressured to complete a task at a specific given time.

By clicking on the Include a deadline checkbox, you can enter the date when this assignment needs to be complete. When the website was setup to send reminders, the users assigned this To Do item will receive emails before the assignment reaches its deadline, when the deadline was reached and when the deadline was missed. By default, the date is set to today + 1 day. Reminders stop as soon as the "Mark Finished" button is clicked or the item is edited and status is changed to Finished.

By clicking on the Include a start date checkbox, you can enter the date when the assignment started. Note that leaving the To Do item to Not Started and clicking on the "Mark Started" button has the same effect.

Note that the start date can be specified in the future. The module will keep that information unless you also mark the status as Not Started and later click on the "Mark Started" button. At that time, the date is overwritten with the current date.

IMPORTANT NOTE

The To Do item may be setup so when the deadline is reached, it automatically gets closed on that day. It is a good idea to do so with To Do items that represent events such as meetings and conferences. If you are using your To Do List for other purposes, your may want to leave the Automatically mark this listing closed after the deadline option unchecked. By default, the Auto-close feature is turned off.

Assignment

The field set let you select who is assigned the task. You can click on the Assign to self checkbox in order to assign this To Do item to yourself.

Any number of users can be added, yet only 3 at a time. To assign a user, start typing his or her name in the 3 boxes provided. When you save the To Do item, these users will be in the group of people assigned this To Do item. To add more than 3 users, re-edit the To Do item and assign another 1 to 3 users.

To remove a user from his or her assignment, edit the To Do item and deselect the checkbox next to that user's name, and hit Save. This will remove the user from the list.

Note that at least one user is required to be assigned each To Do item.

At the bottom of this group, you see a list of radio buttons. These let you choose who can see the "Mark Started" and "Mark Finished" buttons. By default, only you can see those buttons. Click on the Any assigned user to let others click those buttons.

Authoring information

Some administrators may let you change the authoring information. In that case, you can transfer your To Do items to another user who then can update the To Do item as required.

Publishing options

Your administrator may have changed the defaults on this one. The Drupal defaults are to show posts in the website default home page (i.e. /node.) It may be wise to also make To Do items sticky since they then stay at the top of your home page. The administrator can automatically unpublish To Do items that were marked Finished (either immediately or after a few days.) When unpublished, To Do items disappear from the default home page.

View/Edit Permissions

On advanced websites you may see this entry on this form. When present, it gives you a way to define the permissions about this To Do item based on the role of the users available on your website.

The administrator will let you know who and how to define these permissions. The default is probably safe in most cases.

Changing the Status of a To Do item

By default, a To Do item is set to Not Started. This gives the option to the author and other assigned users to click on the "Mark Started" button. A click on this button changes the status to Started and sets the Start date to the day when the button was clicked.

Once started and in other states (except Not Started and Finished) the To Do item will present the "Mark Finished" button to the users who have permission to click it. A click on this button changes the status to Finished and sets the Date Finished to the day when the button was clicked.

The "Mark Finished" button also makes the item unsticky so it disappears from your front page. Your administrator may also setup the website to automatically unpublish and even delete the item. In that last case, you will not be able to do anything to keep the information.

Only the author and website Administrator can change the status to something else.

Changing the To Do item description

At this time, only the author and all almighty Administrator of the website can update a To Do item. Thus only those two people are able to make appropriate changes to the item.

It is possible, however, for the administrator to authorize comments and thus let other assigned users post additional information to the To Do items.

Finding all your To Do items

The administrator may enable the To Do Block feature. In that case, you will have access to your list of assignments right at hand on all pages you visit (see icon on the left.) Note that the block may only show you urgent To Do items. In that case, you may only see a few items that you need to work on as soon as possible.

On some websites, administrators may decide not to install the To Do Block. In that case, you will find your list of To Do items in your account. Go to My account » To do list. This list includes all the items assigned to you. You can also access the list of items you created. For To Do List administrators, a tab entry gives you access to all the To Do items defined in the system.

Your administrator may also use the To Do Views feature. In that case, he may setup some other pages where you can go to see your list of To Do items.

• 1. If you cannot find the link, then you do not have permission to create a To Do item. Please contact your administrator to verify that he properly gave you permission to use this system.

Similar Modules

To Do Lists

The Todo Filter creates a set of checkboxes on a page that you can click to mark as done. It uses a filter so it can appear in any node that has access to that filter.

The Todolist system that creates a list of To Do items managed using AJAX. Very similar in functionality, but unfortunately not supported anymore.

Advanced Management Systems

The Storm system is an advanced CMS including basic bookkeeping, hours worked, resources. This is not to be used publicly.

To Do List Requirements

Requirements

The following are the requirements for the To Do List module.

To Do Items

The basic To Do List module offers you a new Node type and several User lists. There are no specific requirements for the main module to work other than Drupal Core.

Block

The Block module is mandatory, so in itself it is not a requirement.

In order to use the To Do List Block sub-module, you need the Core Block module.

This option gives you access to a block that you can add to one of your regions. By default, it displays the items that are close or past their deadline.

Check out the To Do List Block feature for more information.

Views

The Views module is optional. It is necessary if you want to make use of the To Do List Views sub-module.

This option gives you a way to create your own lists of To Do List items. It respects the permissions even if the View access settings are not set by the Views maintainer.

Examples of lists one can do:

• List the To Do List items that near their deadline
• List the To Do List items marked "Awaiting More Information"
• List the To Do List items that were recently marked "Finished"
• List the To Do List items that are unpublished

Check out the To Do List Views feature for more information.

Actions

The Trigger module is optional. It is necessary if you want to make use of the To Do List Action sub-module.

This option gives you the possibility to control events that the module sends when something happens. There are many things that can be handled such as reminders and status changes.

Check out the To Do List Actions feature for more information.

Rules

The Rules module is not yet supported. It will be optional once available. This will be added in order to give better event hanlding than the Actions sub-module. Stay tuned.

To Do Block

Installation

Go to Administer » Site building » Modules and click on To Do Block to install the Block extension for the To Do module.

To Do Block Settings

The To Do Block has settings defined in the Block configuration form.

The image on the right is a sample of the available options. Click on the image to see a full scale version (1:1).

To find those settings, go to Administer » Site building » Blocks (admin/build/block) and search for the To Do Block. Don't forget to add the block from the Disabled region to one of your visible regions.

Block title

Here you recognize the usual Block title at the top.

By default, the module dynamically generates a title that depends on the current situation. By entering your own title here, you will forfeit that feature.

Hide block when empty

By default, the block always stays visible. This option lets you hide the block when no more To Do items are assigned to the current user.

If you use the To Do Block to display To Do Items with a sporadic frequency, then this is generally a good idea. If you are managing many items, it probably will never disappear anyway. If you are in between, know that by hiding the block you also lose access to the several icons offered by the block.

IMPORTANT NOTES

The fact that the list in your block is empty does not mean that your list of To Do Items is empty. The block does not always display all the items.

WARNING

The Tab feature of the block let you switch between Urgent and All. If you still have a few items in the All list, but know in the Urgent list, clicking on Urgent will "inadvertently" hide the block on your next page load. There is currently no way to restore your block and set it back to All until you add a new Urgent item in it.

Teaser in title

The block lists the To Do Items as links to the corresponding To Do item page.

That link includes a title attribute that can be set to the teaser of the To Do item.

IMPORTANT NOTE

At this time, this feature removes all the HTML and the result can be poor. Therefore it is not recommended. I will look into adding the Overlib library to display a really nice full HTML drop-down.

Display status/priority/deadline columns

The block displays a list of the To Do Items that one should be working on.

Here you can choose to display the:

• To Do item status (i.e. Started, Finished, Waiting information, etc.)
• To Do item priority (i.e. Low, Medium, High, Immediate)
• To Do item deadline (i.e. the date by when the item must be complete)

None of those columns are required.

You cannot remove the To Do item title column.

Display links

This checkbox let you decide whether the icons should be added below the list. By default, the icons are shown. At this time, we have three icons:

• Go to a To Do form so the user can add a new item.
• Go to your list of To Do items.
• Go to the To Do help page (see Help link below, by default, Help for To Do List End Users.)

NOTE

The links will also disappear when the block gets hidden because of an empty list.

List to Display

It is posible to let the user choose whether he will see the Urgent or All the To Do Items assigned to him or force one or the other. To let the user choose use Last block selection. This feature uses a PHP session variable so each user can have a different current setup.

When the Last block selection option is selected, the user sees a couple tabs at the top of his block. The tabs are Urgent and All.

IMPORTANT NOTE

If you use the Hide block when empty feature (first checkbox) then clicking on Urgent when you do not have any Urgent To Do Item will have the side effect of hiding the block the next time you click on a link. Once the block is hidden, you cannot choose All since the tabs are gone. There are several ways to fix this issue: (1) change the configuration to All forcing all users to see all their pending items; (2) add an Urgent item for that user; (3) reset all sessions1.

Help link

This text field let you enter a link to a help page or remove the link completely (by entering blank in this field.)

By default, the help link is set to:

https://www.m2osw.com/doc_to_do_list_item

You are more than welcome to change this link to point to your own website help pages.

Requirements

The To Do Block sub-module requires the To Do List module and the Block module. Note that the Block module is mandatory in Drupal Core so you do not have to worry about that one.

The To Do Block makes use of JavaScript for several features, some of which can cause issues if JavaScript is turned off.

The use of the Tab (i.e. by setting List to display to Last block selection) currently requires JavaScript. The tabs won't work at all if JavaScript is not available. If you have users who don't have JavaScript, you may want to get rid of the tabs.

The use of the block pager requires JavaScript. The pager will not appear whenever JavaScript is not available. The interface will otherwise be functional.

For additional information, see the To Do List Known Issues page.

• 1. This is not accessible from the Drupal interface. Resetting sessions is something that your PHP guru can do for you.

To Do Rules

The To Do module includes a sub-module called To Do Rules extension.

Events

The Rules extension includes the events as follow.

Each event is sent once per user assigned to a To Do item, including self-assigned users. It includes 4 parameters: the To Do item (a node); the To Do item author; the currently logged in user; and the assigned user. The node supports additional tokens that can be used as conditions (see below).

• To Do Event Started

This event occurs when the Start button is clicked on a To Do item. This event is sent once.

• To Do Event Reminder

This event occurs when CRON detects a To Do item that is closing in onto its deadline. In this case, the action user is the Anonymous user. This event may be sent up to 3 times.

• To Do Event Deadline Reached

This event occurs the day CRON detects that a To Do item reached the day of the deadline. The action user is the Anonymous user. This event is sent once.

• To Do Event Past Deadline

This event occurs the day after CRON detected that a To Do item reached the deadline. The action user is the Anonymous user. This event is sent once.

• To Do Event was Completed

This event occurs when a user clicks the Finished button. This event is sent once.

• To Do Event was Unpublished Automatically

Once completed, an event can automatically be unpublished by the To Do module. This happens when CRON detects that the time between the Finished button is clicked and the interval defined in the settings has elapsed (it may be instantaneous in which case CRON won't be generating this event; it will instead be a cascade event from the user who clicked on the Finished button.)

In this case, the action user may either be the person clicked on the button or the Anonymous user.

• To Do Event is being Deleted Automatically

Old To Do items can automatically be deleted by CRON when unpublished and marked as finished. This event is sent right before it gets deleted. You cannot prevent the deletion at this point.

Conditions

At this point, the module does not offer specific conditions. However, all the parameters defined by the To Do module are accessible by the Rules module using the Tokens module.

This is done by adding a condition such as the Rules Number condition and using one of the To Do tokens. For example, to test the priority, one can use [to-do-priority-raw] against a number such as 2 for High.

For the priority and status, it is also possible to use a name.

To know the values, you can use the Tokens filter and enter such tokens in your To Do items and see the results.

Actions

At this point, no actions are available.

To Do Tokens

The To Do module supports tokens that can be retrieved using the Token module.

The available tokens will generally appear in the list of tokens as found under a text area.

The raw tokens are no representing any security risk. They simply return the raw value instead of a more human representation of the value. For example, when the priority is "High", the raw value is 2.

To Do Actions

Installation

Go to Administer » Site building » Modules and click on To Do Action to install the Action extension for the To Do module.

This module requires the installation of the Drupal Core Trigger module.

To Do Action

The To Do Action sub-module is used to enable To Do triggers.

By default, the To Do system has a set of callback API that are not connected to anything. Install the To Do Action and you will get Drupal Core triggers called. You can then create a set of actions to apply to those triggers such as an action to send an email to a user.

The triggers currently available are as follow.

Click the figure to see a full scale version (1:1).

Started

The issue status was just set to Started.

NOTES

To avoid this trigger when editing a started item, make sure to select the Auto-change "Started" to "In Progress" checkbox in the global settings.

Reminder1

This trigger is sent by the CRON system whenever it detects that the deadline is approaching.

When the reminders are being sent is defined in the global settings. If all the reminders are clear (i.e. empty string,) then no reminder is sent.

Deadline reached1

On the day the deadline is reached, the CRON system generates this trigger.

Past deadline1

The day after the deadline, the CRON system generates this trigger. Note that this trigger is called once a day until the issue is marked finished or the deadline is pushed.

Finished

The issue status was just set to Finished.

Note that we do not expect users to edit a Finished task once marked Finished. However, it is to be noted that this trigger will be sent each time such an item is edited.

Unpublished2

The To Do item node was unpublished.

This will happen automatically whenever the auto-unpublish feature is turned on (i.e. Number of days before unpublishing set to a positive number.)

Note that editing a To Do item and marking it unpublished will also trigger the event.

The node is already unpublished when this action is called.

Deleting2

Whenever you allow for automatic deletion, or you directly delete a To Do item, this trigger is generated.

Note that the deletion trigger is called AFTER the node was already deleted from the database3.

Requirements

This sub-module requires the Trigger Drupal Core module.

Some of the triggers only work when a valid CRON is functional on your system. The others will work without CRON.

• 1. a. b. c. Requires CRON to function.
• 2. a. b. Requires CRON for the automatic function.
• 3. The Deleting trigger is called after the node was deleted which means that the callee cannot re-load the node from the database.

To Do Views

Installation

Go to Administer » Site building » Modules and click on To Do Views to install the Views extension for the To Do module.

This module requires the installation of the 3rd party Views module.

Usage

Once installed, the Views will include features for the Nodes, Node Revisions and Users. All three options will see additional entries. The Relations can be used to link users and nodes or node revisions. Note that the relation is a one (node) to many (users.) This means your output will include the same node repeated once per user.

The Attributes accept the dates with 6 different formats as the node created and posted dates.

You can sort on all the fields.

You can filter on all the fields.

You can display all the fields (see screenshot).

The priority and item status fields are shown with their text representation when used as a display field.

The auto-close field is displayed as Yes or No.

To Do Screenshots

Screenshots

The following are screenshots demonstrating the capabilities of the To Do List module.

Screenshots are clickable to review the large version (scale 1:1).

To Do Items (output)

Global Settings

Block configuration

User To Do List Tab

To Do Additions to the Views Interface

To Do List API

To Do List offered Hooks

Since version 1.1, the To Do List module includes a few module_invoke() calls that other modules can catch via one of the following hooks.

hook_to_do_deadline_reached($node)

The specified To Do Item ($node) must be finished today to not be late. If the item is a meeting or conference, then it will be missed if not attended.

hook_to_do_deleting($node)

The specified To Do Item ($node) was deleted (i.e. that node does not exist in the database anymore!) You can act on the item and related objects, but you cannot reload it or prevent the deletion.

hook_to_do_finished($node)

The specified To Do Item ($node) was marked with the status Finished.

Note that marking an item as Canceled does not currently generate any callback.

hook_to_do_past_deadline($node)

The specified To Do Item ($node) had to be finished yesterday or earlier.

hook_to_do_reminder($node, $index, $days)

Sending out reminder $index1 for To Do Item $node. This reminder is being sent $days before the deadline.

hook_to_do_started($node)

The specified To Do Item ($node) was marked with the status Started.

Note that saving a To Do Item with the status Started does generate this event each time. You may want to use the

Auto-change "Started" to "In Progress"2 to make sure your users don't save the same item marked Startedover and over again.

hook_to_do_unpublished($node)

The specified To Do item ($node) was unpublished. The item will now be ignored except by the auto-delete feature if it was enabled (see the global settings for more information.)

Usage Example

The to_do/to_do_action.module makes use of all those hooks and transforms them in the appropriate Drupal Core Trigger so one can hook an action to one of those hooks without having to program anything.

This is probably not a perfect example, but it should already give you a good idea of how the interface functions.

Once the to_do/to_do_rules.module is creaed, it will be yet another example of this interface.

• 1. The reminder $index represents one of the 3 reminders: 0, 1 or 2.
• 2. See the global settings for more information about the Started to In Progress feature.

Extend To Do List with other modules

Extensibility

The To Do List module can be extend with the use of other modules. This page describes such extensions and what you can do with them.

Permissions

You may want to allow more people to work on your To Do List with better granularity in regard to who can edit which issue (instead of all of them) and who can view issues.

There are two modules you can use for this pupose. One lets you choose based on a set of taxonomy terms and the other lets you choose based on available roles.

In order to use a taxonomy with a set of terms, use tac_lite1. This is really the easiest way to mark each item permission exactly the want your want it.

To make items available only to a specific role, even when that role would otherwise have access to all the To Do List items, use Node privacy by role.

Path

By default, the To Do List works with the auto-path module properly, creating new items under the path todo/task-title.

I may add some extensions to allow for some of the data to be included in the path. However, it may not be a good idea because each time you edit a To Do List item, the path will change and thus your users won't be able to access the old items were they bookmarking them...

• 1. tac_lite stands for Taxonomy Access Control Light—a really light weight module using the taxonomy as a mean to control access rights to your nodes.

To Do List Known Issues

Cannot Assign User to To Do List item

When you first install the module, I wouldn't be surprised if you'd want to create a To Do List item right away and then assign the task to one or more users.

It won't work.

Before users can be assigned a To Do List item, you must give them permission to be assigned to such an item. This is done in the usual permission place: Administer » User management » Permissions. You may also want to create a new role of people who deal with To Do List items.

Actually, the To Do List module comes with many permissions so you may want to review this page To Do List Permissions for more information on how to deal with all of them.

Disappearing Block

The To Do Block can be setup to disappear (hide) whenever the list of To Do items is empty.

This causes a problem when a user also has the choice between Urgent or All items.

Situation: The user has 3 items left, all 3 have a Medium priority and are not close the to their deadline.

Result: The Urgent list is empty, the All list has 3 items.

Known Issue: The user clicks Urgent, the block disappears on the next page load because the list is empty.

Current Fixes:

• Force the list to Urgent or All in the Block configuration
• Unselect the Hide block when empty checkbox
• Post an Urgent To Do item for that user and have him switch back to All
• Clear all the PHP sessions assigned to that user (no Drupal API available for this one.)

JavaScript requirement

The To Do Block in the sidebar uses JavaScript and AJAX.

Two features that require JavaScript.

Pager

The block pager is created using JavaScript. Thus, a user without JavaScript cannot see but the first page in the list. This is a big problem since the user can always go to his account and use that pager instead.

The pager also makes use of AJAX to read the pages. Obviously, if the pager does not even appear, this is not going to even be accessible.

Block Tab

The Block Tab makes use of AJAX to communicate with the server and switch between the Urgent and All lists. The Tab should not be used if some of your users do not have JavaScript to ensure that the behavior is proper for all.

A future version of this module will circumvent these problems by offering links that work by default that JavaScript can tweak to get the AJAX functionality.

Bug in AHAH Helper module (up to rc12)

IMPORTANT NOTE

The older versions of the module (Up to to_do-6.x-1.1-rc12) would use the AHAH Helper module to handle form features with AJAX. The AHAH extension is very complicated to use and it was removed by Alexis Wilke when he made his updates. Now, version 1.0 and over do not make use of the AHAH feature at all and thus you obviously will not be hit by this problem.

There was a bug in the ahah helper module that caused an HTTP 500 error1 to appear when using this module. To fix this bug, you need to apply the patch that is attached to the initial post in this thread. This bug existed in AHAH Helper 2.0 (version as of July 16, 2009).

If you don't know how to apply patches, you can do this:

1. Open up ahah_helper.module in a text editor
2. Find this line:
   • require_once($form_state['storage']['#ahah_helper']['#file']);
3. Remove the '#' character before '#file' so the line like like this:
   • require_once($form_state['storage']['#ahah_helper']['file']);
4. Save the file, upload it to your server, and you should be good to go.

• 1. HTTP 500 Invalid server error.