Developing add-ons for Agile Toolkit 4.2

One of the best features of Agile Toolkit 4.2 is extensive support for add-ons. Using add-ons Agile Toolkit can be extended significantly.

Before you develop an addon, you should look into some existing add-ons and how they are built. Majority of add-ons are very simple and can be easily understood

Add-ons in Agile Toolkit play a passive role. First you need to download add-on and place inside atk4-addons folder. Then you need to explicitly use it.

$page->add('helloworld/Core');

You will find that helloworld is already bundled with your copy of Agile Toolkit. There are also some other add-ons too. Read through their source-code and try using them.

Creating your own add-on

Go to http://agiletoolkit.org/ and log into your account. Click on "Create new Add-on" button and pick a name. It's important to pick a good name before you start developing. The name will have to match with "namespace" you are using. We are taking efforts to make sure the namespaces are distributed fairly, so once you register your add-on, others won't be able to use the same name.

When you have secured your name, you will get email confirmation. Create atk4-addons/myaddon and start developing it. Define a namespace. Take extra care to reference global namespace when you extend core objects.

Dependencies

Inside the main class of your add-on add the following lines:

  $this->api->requires('atk','4.2.1');
  
$this->api->requires('other_addon','2.1');

You can specify version inside atk4-addons/myaddon/VERSION.

Writing installation instrucitons

Create file atk4-addons/myaddon/README containing the steps developers must undertake to use your add-on in their application.

Live Demo

Create a sample applicaion using your add-on and deploy it to PHPFog. They host a simple applications free of charge without time restrictions, so you don't need to pay for your "demo" hosting.

What can you create inside add-on

Models

Sometimes certain tables are re-usable. The good example of an add-on containing models would be "filestore". This add-on will define filestore/Model_File, filestore/Model_Image which are tied to a physical files stored inside "uploads" directory and the metadata stored in SQL table.

You will find an example Model inside helloworld called 'MyModel'. To use:

  $view->setModel('helloworld/MyModel');

Controllers

In most cases, add-ons would contain controllers. Addon gridorder is a good example of add-on based conttroller.

Views

Addons may contain views. See formandsave for a sample view based on Form.

Resources

Apart from PHP, add-ons may contain additional resources. To make those resources discoverable, use pathfinder.

$l=$this->api->locate('addons','gridorder','location');
$this->api->pathfinder->addLocation($this->api->locate('addons','gridorder'),array(
  
'template'=>'templates'
))->setParent($l);

Model Fields

When Model fields are being defined, it relies on the "Field" class. If you use hasOne, hasMany etc then different types of objects are added into a model. You may create your own model field types which enhance query building, model behaviour and more. Refer to atk4-addons/filestore/lib/Field/Image.php for a good example. To add this field in your model your user would need to write:

$model->add('filestore/Field_Image','picture_id');

Adding pages

TO BE CHANGED!

You can use pathfinder to add "page" location. Please note that when including extra directories through pagefinder, they will no longer be concealed in your namespace.

Tips and Tricks

Including additional resources inside your add-on

You may ask user to place the code which includes a core controller of your add-on into initialization of their API. You should explain clearly what those controllers do and why they are needed. Inside your class you need to locate your add-on first and then add locations of other resources you might have bundled.

If you have helloworld/templates/view/hello.html which is required by your view, then simply use the following code:

$l=$this->api->locate('addons','gridorder','location');
$this->api->pathfinder->addLocation($this->api->locate('addons','helloworld'),array(
    
'template'=>'templates'
))->setParent($l);

You must be aware, that defaultTemplate() method is called before init() and if your view would want to use a bundled template, you should move the above code inside defaultTemplate() method.

Avoiding repetition of your add-on name

As we do not want to continiously repeat "helloworld" throughout your add-on code, you should define a constant within the namespace, then use it, as there are no __NAMESPACE__ magic. If you are using the following syntax:

Extending classes defined in add-ons

You may extend classes from your add-on in the global namespace or inside other add-ons through the followin syntax:

class Model_MyImage extends filestore\Image {
    
// ...
}