twz PHP To Do List Project: Manage to do tasks of project on a Web page

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