twzToDoList.class documentation v1.2.0 2019-10-04
================================================================================
ABOUT twzToDoList:
________________________________________________________________________________
In case there aren't enough to-do-list applications already, here's another one.
twzToDoList is a simple web-based project/task checklist, which is suitable for
people who spend most of their day in front of a browser.
Any number of projects can be added, and each project can have any number of tasks.
The words "project" and "task" are options you can change; for example you might
prefer to work with "Jobs", with each Job consisting of multiple "Items".
Projects are automatically given a Status depending on their due date, and that
of their tasks. The status names can be customised to suit yourself, but their
meaning is fixed (see setupStatus method description below).
twzToDoList is easy to set up - all you need is a web server that supports PHP
and MySQL, and a browser with Javascript enabled.
________________________________________________________________________________
INSTALLATION:
________________________________________________________________________________
Database
twzToDoList requires a MySQL database, and will try to create one if it
doesn't exist. In some environments (eg shared hosting), that won't work -
in that case, you should start by manually creating a MySQL database, and
adding a database user with full privileges to the database.
Settings
Unzip the package and copy or rename index-example.php to index.php.
Open index.php in your favourite plain text editor, and enter your preferred
settings as explained in the file - timezone, database name, password, etc,
and any twzToDoList options (described below).
UPGRADE NOTE: if you are upgrading from an earlier version of twzToDoList,
you should already have an index.php file. Usually this can be kept, but have
a look inside index-example.php for any requirements that might have changed.
Upload
Upload all files to a directory on your web server, and point your browser
at that directory - that's it!
________________________________________________________________________________
PUBLIC METHODS:
________________________________________________________________________________
setOption( $OptKey, $OptValue )
Set a single option, eg
$todo->setOption('canBackup', true);
setOptions( $Options )
Set multiple options at once, eg
$todo->setOptions( array('canBackup'=>true, 'progressType'=>'bartext') );
setupStatus( $StatusNames=array(), $wordArchive='', $wordArchived='' )
Change the name of one or more statuses. The defaults are:
NEW ..... New
INPROG .. In progress
DUE ..... Due soon
URGENT .. Urgent (see 'urgentDays' option)
LATE .... Overdue
DONE .... Completed
CLOSED .. Archived
If the name for CLOSED is changed, you'll probably also want to change
$wordArchive ... used in the label 'Archive this project'
$wordArchived .. used in the link 'Show archived projects'
eg
$todo->setupStatus( array('INPROG'=>'Ongoing', 'DONE'=>'Finished') );
setTaskButton( $Text=array() )
Change the label of one or more task status indicators, when editing a
project. Labels should be kept short if possible. The defaults are:
NEW ..... todo
INPROG .. inprog
DUE ..... due
URGENT .. urgent (see 'urgentDays' option)
LATE .... late
DONE .... done
eg
$todo->setTaskButton( array('NEW'=>'new', 'LATE'=>'urgent') );
go()
Does all the work! Call this as the last step, eg
$todo->go();
________________________________________________________________________________
OPTIONS:
________________________________________________________________________________
The list below shows the options that can be changed by calling the setOption() or
setOptions() method, and each option's default value. Option names are case sensitive.
Terminology
wordProject ....... ('project') the word to use for a project, eg 'job to do'
wordProjects ...... ('projects') the word to use for projects (plural), eg 'jobs to do'
wordTask .......... ('task') the word to use for a task, eg 'item'
wordTasks ......... ('tasks') the word to use for tasks (plural), eg 'items'
Permissions
canSearch ......... (true) whether user can search for projects
canAddProject ..... (true) whether user can add a new project
NOTE: all users can edit existing projects
canDeleteProject .. (true) whether user can delete a project
canEditPreset ..... (true) whether user can edit presets
canDeletePreset ... (true) whether user can delete a preset
canBackup ......... (false) whether user can download a database backup
Date related
dmyInput .......... (true) dates entered with slashes are normally assumed to
be in day/month/year order; if false, month/day/year order.
Eg if dmyInput is true, 5/3/19 means 5 March 2019; if
false it means 3 May 2019.
searchFrom ........ ('1 month ago') default search-From date
searchTo .......... ('now') default search-To date
setNowText ........ ('✓') text for 'set date to now' button, eg 'now'
or use '✓' for a checkmark, '✔' for a bold
checkmark. Empty string to disable this feature
defaultDue ........ ('+1 month') auto due date for new projects.
See also: usePresetDue
dueSoonDays ....... (7) how many days in the future a due date is considered
to be "due soon"
urgentDays ........ (7) if less than dueSoonDays, how many days in the future
a due date is considered to be "urgent". If urgentDays is
the same as dueSoonDays, the urgent status is not used.
dateFormat ........ ('D j M Y g:ia') display format for date of backup files;
ref PHP's date() function
Backups
backupDir ......... ('./backups/') directory to save database backups (only
applies if canBackup is true). The directory must exist,
and be writable by PHP.
backupAudit ....... (true) whether to include audit tables in backup (see canBackup)
gzipBackup ........ (true) whether downloaded backup should be gzipped (see canBackup)
backupAll ......... (false) ADMIN ONLY - whether the user can back up (and
download) all tables, with any tablePrefix
Features
uniqueName ........ (true) whether each project name must be unique
listTooltip ....... ('descn') adds a tooltip in the project list taken from
the project description. Empty string to disable this feature
progressType ...... ('textbar') progress indicator in project list; can be
one of: (none|text|textbar|bar|bartext)
useSession ........ (true) Use a session to remember search fields
newTaskCount ...... (5) number of new tasks that can be added at one time
(for a new project or preset)
addTaskCount ...... (1) number of tasks that can be added at one time (for an
existing project or preset)
pageMax ........... (20) maximum number of archived projects to list per page
allowTaskDue ...... (true) whether user can enter a due date for each task
applyTaskDue ...... (true) whether the task due date affects project status in
the project list (allowTaskDue must be true). This means that
even if a project's due date is in the future, it will be
listed as overdue if it has a task with an overdue date
usePresetDue ...... (false) whether to have the option for each preset to use
a custom default due date for projects that use that preset.
If present, this will override the 'defaultDue' option for
those projects.
Other
tablePrefix ....... ('') database table prefix; allows multiple versions of
twzToDoList in the same database
createTables ...... (true) whether twzToDoList should attempt to create database
tables if they are missing
devDeleted ........ (false) whether user can view a deleted project (from the
audit tables)
devRestore ........ (false) whether user can restore a deleted project from the
audit tables - devDeleted must be true
|