Creating New Report

[spatialguru]

Our event managers have needed to regularly download various reports from OCS. To help with this we are upgrading to OCS 2.1 so we can use the great bundle of Reports (located in Stats & Reports page). One report they wanted that was not already available was one that gave them a listing of all registered users on the system. So I copied the Registrants Report and modified it so it included all users - not just ones from a given event - and thought I'd share my process here in case someone else wants to make their own report.

Thanks to the great work of the development team - it's really easy to do if you are comfy with SQL and tiny bit of PHP hacking. My new plugin is called All Users Report.

Step 1 - Clone Existing Report Plugin
Copy the files and rename them accordingly:

Code: Select all

cd ocs-2.1/plugins/reports
cp -r registrants users
cd users
mv RegistrantReportDAO.inc.php UsersReportPlugin.inc.php
mv RegistrantReportPlugin.inc.php UsersReportPlugin.inc.php


That was easy, but you'll find the page won't load until you make some more changes in the code.

Step 2 - Rename Plugin Attributes
Mainly just in 3 places. First edit the index.php to import the newly named files. You can do it mainly (only 2 changes) but for the sake of description I'll use the sed command to do it easier:

Code: Select all

sed -iorig 's/RegistrantReport/UsersReport/g' *
sed -iorig 's/registrantReport/usersReport/g' *


Step 3 - Choose Your Fields

Then I had to decide which fields and from what tables in the database I wanted the info from. The Registrant report itself was almost exactly what I wanted, but a few too many fields and a bit too constraining. To adjust the database query, edit the UsersReportDAO.inc.php file. Here is my resulting, greatly simplified, final statement for the report:

Code: Select all

   $result =& $this->retrieve(
                        'SELECT
                                u.user_id AS userid,
                                u.username AS uname,
                                u.first_name AS fname,
                                u.middle_name AS mname,
                                u.last_name AS lname,
                                u.email AS email,
                                u.country AS country
                        FROM
                                        users u
                        ORDER BY
                                lname'
                );


That was easy too Note it now only uses one table in the query - the users table.

Step 4 - Adjust Output and Locale Terms

Now the final step... to adjust the output of the values as they will go into the CSV report file and to set the way the report shows in the list of available reports (uses local settings). Do this by editing the UsersReportPlugin.inc.php file:

Lines 47 and 51 - these settings display the "name" of the plugin and its description as shown on the Stats & Reports page and also in the Site Plugins page. I kept it really simple:

Code: Select all

47 from:            return Locale::translate('plugins.reports.registrants.displayName');
47 to:                return Locale::translate('manager.people.allUsers');

51 from:           return Locale::translate('plugins.reports.registrants.description');
51 to:               return Locale::translate('manager.people.allUsers');


The locale settings should likely be done in the locale settings for the plugin, but I was too lazy.

Finally I modified the field names for the data output - here's what I ended up with for the main variable setting:

Code: Select all

                $columns = array(
                        'userid' => Locale::translate('plugins.reports.users.userid'),
                        'uname' => Locale::translate('user.username'),
                        'fname' => Locale::translate('user.firstName'),
                        'mname' => Locale::translate('user.middleName'),
                        'lname' => Locale::translate('user.lastName'),
                        'email' => Locale::translate('user.email'),
                        'country' => Locale::translate('common.country'),
                );


Hope that helps you out! I'll follow up with some more of the things I needed or questions I have, but wanted to get this in writing before I forgot

Cheers to the devs! These reports are great templates to follow and this was an all-round pleasant experience!

Tyler

[asmecher]

Hi Tyler,

Glad to hear it! We'd like to put together a plugin gallery for user-contributed plugins; would you like us to start with this one?

Regards,
Alec Smecher
Public Knowledge Project Team

[spatialguru]

We'd like to put together a plugin gallery for user-contributed plugins; would you like us to start with this one?

Sure thing!

The only thing I'd like to fix up properly is the handling of locale values. I would love to know the best way to handle this. I don't mind putting my plugin name and description into the plugin locale files, but what do you do when you don't have the localization info for the others languages?

Tyler