Creating a new App for Watchful.li is quite easy and with the following instructions you will be up and running in no time.

The quickest way to create an App is duplicating the exampleApp, a simple App that contains all you need to create a 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 exampleApp.

Install files

To maintain a single installation package for different Joomla versions, we have both a exampleApp.xml and a _manifest.xml:

  • on Joomla 1.5, the exampleApp.xml file will be used
  • on Joomla 2.5 / 3.0, the _manifest.xml flle will be used

The first thing you have to do is to rename the exampleApp.xml file, and then edit both xml files to reflect the changes: you have to set your app name and parameters.

The "multiple xml files" is a nice trick, but it has its drawbacks, and that's why we need an install script.

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 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

Additional fields for J2.5 / J3.0

In a very similar way, the J2.5 / J3.0 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

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 quite commented and should be quite 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.li 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.li. 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.