Notes on Plugin Development in ProjectPier

For those of you who didn't know about ProjectPier, it is yet another web-based Project Manager. What makes it different from the rest of them? Well, the fact that we use it in Floss-Pa to manage our projects :) I remember that the decision to use ProjectPier over some other options we were managing back then, was the fact that it doesn't offer a complex interface so people could actually jump in, grab a file, write a comment, close a task, and jump out. No fancy javascript going on, no full integration with your blood cells, just a web interface to keep track of things... simple.

On the other hand, we were looking for a simple way to keep track of some finances in Floss-Pa, namely selling t-shirts and souvenirs and keeping track of sales and expenses (yes, we are always looking for simple stuff -it is complicated enough to be part of a Free Software Community in our country). I came up with the idea of developing a plugin for ProjectPier that would just list transactions and let you add/edit/delete them as needed.

I finally sat down this weekend, and besides finishing a rough first version of the plugin, I gathered these notes that will hopefully help anyone trying to develop their own plugin too.

Where to Start

It doesn't seem easy to find where to start looking for documentation when you want to write your first plugin. From my experience, the following forum post was the most helpful in setting me up for development. You should be very careful with the large amount of references to ProjectLinks that appear in the code when you copy and paste it - some of these references were still allive days after I had started coding.

Update Notes

The very first thing I had to do to start developing was upgrading from version 0.8.6 to 0.8.8, which turned out to be not as straightforward as it could have been. Yet, all hassle can be prevented by enabling all your plugins before the update, so I sent out a patch to the upgrade instructions which was kindly merged, and you should be able to follow the updated instructions to have ProjectPier 0.8.8 in no time.

Database Types

When developing your plugin, you'll most likely be defining your own database table to store your plugin information. While defining the tables can be done in good ol' SQL, you still need to specify column mappings in the model code. For that, ProjectPier uses a set of data types constants - you can see some of them in use in the ProjectLinks plugin. For a complete list of available data types, check the environment/constants.php file int he project, which also defines other constants you might need later.

Form Reference

Like most PHP applications and frameworks, ProjectPier creates a wrapper around the form tags for templates. Again, you can check templates fromt he ProjectLinks plugin to have an idea of available wrappers, but a full list can be found at application/helpers/form.php and there you will find some incomplete widgets you don't want to use.

Error Logs

I was very concerned when I noticed I was not getting error logs in the usual Apache location - being able to quickly see the error messages is essential for effective development. But no worries, clicking around in the application, I found that, when logged in as an administrator, you can browse to the Administration -> Tools -> Browse System Logs menu to see a log of all error messages. This is your friend while debugging your code, you will see all fatal errors and warnings you are missing in the server error logs. When you are dealing with an issue, you can click on the First Page link to see the latest error message (the reason why it doesn't show up in the first page at the begining, or the number of pages displayed seem all like a bug to me, but I didn't investigate further).

One thing you'll quickly want to do is get rid of messages about errros you already fixed. That way, you can be sure the messages you see are only about current errors. To clear your logs, browse to the /tools/clearlog.php page of your installation (e.g. http://www.example.com/tools/clearlog.php). I agree there should be a link somewhere to do this, but I couldn't find any so this is my proposed workaround.

Traces

One last useful tip for developing and debugging your plugins are the traces. If you are examining the ProjectLinks code you will notice many calls to a trace() function that you can use to write debugging information. You will also notice that this messages don't go to the log, so where do they go? Well, I found out that adding a &trace=1 to your URLs will have those messages written to the cache/trace.txt file in your installation, so you can enable and disable this feature per URL whenever you want to take a look at a particular tracing. Be sure to delte that file after debugging, since it is a publicly available file and may contain sensitive information.

With all of these tips, developing for ProjectPier should be a lot easier. There are some other things we are missing for our Finances plugin, but in general, everything is in place and it just takes a little code diving to get everything to a working state. You can ping the developers of this project at their IRC channel, #projectpier at Freenode, in case you need assistance.