How to extend Watchful with apps

Watchful provides an extensible framework for you to create Watchful log entries and notifications based on customized parameters.

To use this framework, you'll need to create an installable plugin for your website that includes a specific trigger such as the submission of a form or a new sale in your e-Commerce store.

When the plugin is installed and the trigger is detected, log entries and email notifications are created. 

Simply put, anything that can be evaluated/tested with an SQL query and/or PHP can be packaged into a specialized Watchful app.

Getting started

Watchful maintains a number of apps to suit common purposes. The quickest way to create an App is duplicating the "Example App", a simple plugin that contains all you need to create your own custom app.

You can also duplicate another App which may be more similar to the new one you want to create, but for this tutorial we'll stick to the "Example App".

Creating Watchful apps for WordPress

Coming soon.

Creating Watchful apps for Joomla

Install files

To maintain a single installation package for different Joomla versions, be sure to include the following manifest files depending on the Joomla versions required for your purposes:

• for Joomla 2.5 / 3.x / 4.x, the _manifest.xml flle will be used.
• for Joomla 1.5 (no longer actively supported), the exampleApp.xml file will be used.

The first thing you have to do is to rename the manifest file(s). Then you can edit the manifest to reflect your specidfic app name and parameters.

Using "multiple xml files" is a nice trick to support multiple Joomla versions. But it has its drawbacks, and that's why we need an install script (see below).

Install script

When you use an XML file named _manifest.xml instead of the proper exampleApp.xml for a plugin, everything will work fine apart from the configuration options. In other words, the extension will run but you will not be able to edit its configuration options.

So, to fix this, the package includes an install.php file which is called only in _manifest.xml file.

Basically, when you're on Joomla 2.5 or 3.0, the file _manifest.xml gets copied to exampleApp.xml on install.

You need to change the class name and the file name in the install.php file.

Additional fields for J2.5 / J3.x / J4.x

In a very similar way, the J2.5 / J3.x / J4.x XML file add the path fields. We don't need an additional subfolder anymore since each plugin has its own folder already.

As we said before, if you don't need any additional field, don't do anything. If you do, duplicate the field file and modify it.

See also: http://docs.joomla.org/Creating_a_custom_form_field_type

Additional elements for J1.5

The Joomla 1.5 xml file already adds the path exampleApp/elements as a container of custom parameters. You can easily write your own configuration parameter type. We created an additional folder because in Joomla 1.5 the plugins of the same type are all installed in a common folder and we need a little private space for each app.

If you don't have any additional element, you don't have to do anything. If you do, just duplicate the element file and modify it according to your need.

See also http://docs.joomla.org/Custom_parameter_types

The app: exampleApp.php

Now that we've seen all the files and folders structure, let's have a look at the app itself. The exampleApp.php file is well-commented and should be easy for you to understand what's going on.

First of all, rename the file according to your app name. After that, open it and change the class name accordingly.

Basically, the appMainProgram method is called each time a Watchful check starts.

Each app checks for some specific value(s). The exampleApp always returns the same value, but of course in a real app the result may change: think of a query that gets some items from a table (for example, the Articles App gets the ids of all articles from the configured categories).

The customCheck method is only an example; you can include the check in the main function, or you can create different functions and name them as you like. No need to call it customCheck, either.

After a new value is retrieved, we get the existing value from Watchful. If there wasn't an existing value, we assume it's the first time ever that this app has been started. Else we compare the two values and raise (or not) an alert accordingly.

Debug

You may have noticed that a debug configuration option can be really helpful to get additional info about what's going on. It's especially useful to get the old and the new value to be sure they are what you expect them to be.