2do

Simple To-Do List for the Web

By Bart King, Demonic Developments
2do@bart666.com
http://www.bart666.com

Version 1.22 (28-Apr-04)

If you are upgrading from a previous version, you must refer to the Upgrading instructions prior to using the new version.

INTRODUCTION

Do you need a quick way of organising a project? Got a web server, and would like to keep others updated on the status of your current list? Then 2do is your answer.

This simple web application, written in PHP with a MySQL back end, provides a scalable way of presenting and organising projects that you or your company work on.

Benefits of using 2do are:

Instantly see what needs to be done on your projects - no more lost scraps of paper!
Allow everyone to see the status of your projects, while restricting modification;
Support unlimited numbers of projects;
Page layout is entirely customisable down to HTML level.

INSTALLATION

To install 2do, you need a web server with at least PHP 4.2 and MySQL 3.23.x installed. Please see the PHP and MySQL web sites for more information about the general hardware and software requirements, and installation for each. If you do not run your own web server, please contact your administrator or web hosting company to check for these requirements.

For instructions on how to install 2do without SSH access (e.g. a shell), jump to here.

With a server, perform the following:

Download the latest version of 2do from the 2do web site.
If you downloaded the TAR+GZIP archive (.tar.gz), in your shell (such as bash), untar the PHP scripts from the archive:

$ tar -zxf 2do-X.X.tar.gz (replace X with the version number)

If you downloaded the ZIP archive (.zip), under Windows use a popular archiving tool to extract the contents to somewhere on your web server's document root. Please ask your administrator for assistance, if you are not sure.
Once extracted, you will have a "2do" directory. Inside this directory is an "sql" directory, containing tables which 2do requires.

At your servers shell or command prompt, type:

$ cd 2do
$ mysql -u USER -p DBNAME < sql/tables.sql

Replace "USER" with your MySQL database user name, and "DBNAME" with the name of your database. You will be prompted for your MySQL database password.
You are now installed! However, before you take 2do for a test drive, you need to configure it.

Installing Without Shell/SSH Access

While there are several ways to install 2do without shell access, this method describes how to install by using an FTP client to upload 2do to your web server. This also assumes you have access to the popular MySQL interface called phpMyAdmin.

Firstly, download 2do from the 2do web site if you haven't already, to your machine.
Extract the archive onto your hard disk. If you are using Windows, use a utility such as WinRAR. This will result in a 2do directory on your hard disk.
In the 'sql' directory is a file called tables.sql. This contains the required table structure that needs to be inserted into your MySQL database.

Browse to the URL for where phpMyAdmin is installed on your site, login with your database username and password. On the left is a panel containing the databases (and tables) that are available to you. Choose the database you wish to use with 2do.

Next, click the SQL tab along the top. Load the tables.sql file into a text editor and copy the whole file to your computers clipboard. (Windows users: Start->Run, type notepad and click OK. Drag and drop the tables.sql file from Explorer onto the Notepad window. From the Edit menu, choose Select All and then Copy.)

Paste the SQL tables into the big box on the SQL page of phpMyAdmin. Click the Execute button, and after a few moments a message saying the SQL query was successful should appear. If it does not, make sure you copied the information from tables.sql correctly, and also check that you are using the right database.
Next, you need to create your configuration for use with 2do. Refer to the next section now on how to create this file, then once done, return here to finish the installation.
Finally, you need to transfer 2do to your web site. To do this, you need an FTP program and login details for your ISP's FTP server. Please contact your ISP for more information about this if you do not have these details to hand.

Using your FTP program, login to your web site, and copy the whole of the 2do directory from your computer onto your remote web site. It is important to make sure you have your FTP client set to transfer files in binary mode.

After it is complete, you can then take 2do for a test drive - navigate to your site and the 2do sub-directory and give it a whirl!

If something goes wrong, this is either attributed to a wrong value in config.php, something happened during the SQL installation or something failed during the uploading phase. Start again, or e-mail me if you get completely stuck.
Jump to the Quick Tutorial.

CONFIGURATION

All configurations for 2do are stored inside the file config.php. This is located in the include directory, but called config.dist.php - this is to force you to create a configuration. Copy config.dist.php to config.php (or rename) and edit.

Load config.php into your favourite text editor (such as Notepad on Windows, or vim on Unix) and modify the settings, using the information below as guidance.

Variable	Default	Description
mysql_host	localhost	This specifies the host name for the MySQL server you wish to use. This is usually "localhost" or 127.0.0.1.
mysql_user	root	Your MySQL database user name.
mysql_pass	root	Your MySQL database password. Note that this is stored plain text!
mysql_dbase	test	The name of your MySQL database.
mysql_pfix	todo_	This is the prefix used in the database for the two tables required by 2do. If you need to change the names of the tables used by 2do (see later), you will need to change this to reflect the new setting. Most users can leave this as default.
temp_root	templates	This is the absolute path for where 2do's templates are stored on your server. Note that the templates do not need to be stored along with the PHP scripts. You will need to change this to reflect this change. Most users can leave this as default. Trailing slash is best left off.
admin_pass	adminpass	This is the password that you will need to enter if you want to modify to-dos or projects. All forms ask for this password before a modification will be permitted. Make sure you change this from the default to something reasonably secure!
change_date	TRUE	If this is set to 'true', every time you modify a to do entry (including changing an entry from 'Not Done' to 'Done'), the date of the entry will change - this is default behaviour. If you do not want the date to change, set this to FALSE.
project_passwords	TRUE	Setting this to TRUE permits the use of individual passwords on each project. This provides low-to-medium security to hide information about a particular project. Please see the Project Passwords section for more information. If this is set to FALSE, all projects are viewable by all.
hide_csv	FALSE	If this is set to FALSE, you can export and import todo data, so it can be shared with others. Setting this to TRUE disables all CSV options.

Once all these changes are made, save the configuration.

You may also modify the priorities list, which is located in the config.php file. You may add or delete as many of these entries as you like. Each entry has an HTML colour code (under the key 'col') and a textual description (under the key 'text').

If you are installing 2do without SSH access, you need to go back and finish the installation.

You should be able to start entering new project data. If something goes wrong, check your configuration again, making sure you entered the data correctly.

QUICK TUTORIAL

With 2do set up and fully configured, follow this simple and quick tutorial to get started.

Navigate to where 2do is installed in your web browser (by entering a URL - for example, http://www.mywebsite.com/2do/) and you will be presented with a form to enter a new project.
Enter the name of your project, followed by the administrative password you set up in the configuration. Click Submit.
You will be then taken to the main page, showing an empty to do list.
Choose New To Do Entry to create a new to do.
Enter a description of what you need to do in the box, and assign a priority to it. Also enter the administrative password again, and choose Submit.
You will be taken back to the main page with your new entry listed.
Repeat for other things to do.
To mark something as completed (i.e. 'done'), choose Edit underneath the to do that is complete, tick the Completed box, enter the administrative password and choose Submit.
To create a new project choose New Project.

And that's all there is to it.

ADVANCED CONFIGURATION

2do's pages are actually templates, thus allowing you to customise entirely how the to do list should appear in a browser. Each template (stored in the template directory) contains the full HTML for each page.

You can modify each of these in your favourite text or HTML editor (see below). There are special entries, enclosed in square brackets - these are blocks and variables. It is important that blocks must be present in the template, but they can be anywhere in the template. All variables are optional, but some functionality will disappear if some are left out.

For more information, refer to the actual templates.

TOP TIP: If you are using an HTML editor to modify the templates, rename them from .tpl to .html, load them into your editor, change and save, then rename them back from .html to .tpl.

The tables used in the database for 2do are called todo_entries and todo_projects. If these names are not acceptable, you will have to modify the SQL data file before you import the tables as explained in the installation instructions above. You can then change the "mysql_pfix" configuration entry to whatever you renamed the tables to be. Please note that the names must still have "entries" and "projects" on the end.

IMPORT AND EXPORT

2do has the ability to import and export the entire to do list. This allows you to have the same to do list available wherever you are.

An example for this scenario is where you work on a project off-line, without having access to the web server where the public to do list is available. You can use your to do list running on your machine, mark things as complete as you go, and later when you connect to the Internet to check e-mail, you can also export the contents of your off-line to do list and import into the public to do list.

The CSV export option will send to your browser a CSV file containing each project and each of their associated to do entries. While the import option will display a form, asking you to choose a CSV to upload and enter the administrative password. Use the same CSV file you obtained from exporting to import.

You can also use the export functionality as a backup service, if you so desire.

Note that if Project Passwords are enabled, it is not possible to export or import all projects in one go - you need to change to each project and choose export/import, using individual CSV files. However, if Project Passwords are disabled, you can operate on each project in one go.

PROJECT PASSWORDS

2do offers the ability to password protect each individual project. This allows you to allow public access to some projects in your to do list, while restricting access to others. You may find this useful when managing several projects, but wish to keep information about some confidential.

To assign passwords to a project, create a new project and enter the name of the project, followed by a project password, as well as the usual administrative password. Then, when you switch to your new project on the main page, you will be prompted to enter the project password. Doing so and clicking on 'Go' will show the to do entries below.

NOTE: You must enter the project password every time you wish to view, modify, create or delete entries in the project. You must also enter the password for exporting and importing entries via CSV.

ALSO NOTE: Once the password has been set, it cannot be changed or recalled. The password is stored in a one-way encrypted format in the database. While this security is adequate to prevent casual browsers from viewing your protected projects, no system is water-tight.

To remove a password from a project, edit the project, type in the current project password, tick the "Remove Project Password" box, and enter the administrative password. The project will then be publically accessable.

If you are working in a multi-user environment and wish a select few to access your protected project, you must also give them your administrative password, if you want them to be able to create, edit or delete entries in the project. But, these people will not be able to access other protected projects, as they require a different project password.

CREDITS

Thanks to all the people who have e-mailed me with suggestions and comments - keep 'em coming!

2do uses Simple Template - a template class, developed by Thomas Hurst. It is ©2004 Thomas Hurst, all rights reserved. See include/i_simpletemplate.php for its licensing. The included Simple Template has modifications by Bart King.

BSD LICENCE

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Demonic Developments nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CONTACT

E-mail: 2do@bart666.com
Web: http://www.bart666.com/projects/2do/
Phone: +44 781 219 5654

Thanks for reading - knowledge is power!