• Developing cronks for Icinga-Web
Skip to end of metadata
Go to start of metadata

Some of this content will be updated soon

Icon

The organisation and definition of the cronks.xml files has changed since v1.5, expect some updates here.

HowTo - Developing cronks for icinga-web

Abstract

Cronks are small code snips and can be implemented in php, html or javascript. They are simple widgets running
within the icinga-web portal. Like modules, cronks are built for extensibility icinga-web. Cronks are also no standalone applications.

What you will learn here

  • Code structure of a cronk
  • Configure parameters
  • Access them within the portal

Requirements

Requirements depends on how the cronk is implements. If ExtJs is heavily used, you'll may have expert knowledge about Extjs.

  • A running icinga-web instance
  • Basic knowledge about PHP5, agavi, html, js
  • Know what phing is
  • Average knowledge about agavi and MVC

Under the hood, what are cronks?

Cronks are agavi actions which return simple html slot layouts. These actions are executed through ajax requests triggered by the icinga-web portal. The cronks concept are based on Agavi and Extjs this means:

  • Configured through agavi settings/module config
  • Some default parameters depends on ExtJS (component id's, stateful id's and parent elements)
  • May have multiple output types to provide data to the cronk itself like json or xml
  • Executed within an agavi context and create html
  • If the html contains javascript, this is executed too

File structure

Depending on the agavi action construct this looks like this:

Agavi actions are live within modules, the tree above are based on the Cronks module which lives in 'app/modules/Cronks'

actions

The action triggers what to do with the data in MVC. A simple cronk does not need complex workflows here, only parameter processing is a must. Also you can define security layers, so not everybody can access the cronk.

cache

Agavi cache configuration, if the content should be cached and how long.

templates

The cronk output. This is the last link in the chain and contains html, javascript or php code. In the most cases this holds the main cronk implementation.

validate

Contains information about used parameters (GET, POST, headers, ...) and how we can access them.

view

This prepares the output after the action. The generic output is html used to defined the cronk. If the cronk need some other data you can implement json or other formats to supply data for ExtJs implementations like grids or views.

Configuration

Cronks are also (based on the front view) preconfigured clickable items.

These configurations are made in the Cronks module config: app/modules/Cronks/config/cronks.xml.

A single cronks entry looks like this:

I think the most is self-explanatory. The name attribute of the container element must be unique.

  • module - The name of the Agavi module which holds the cronk
  • action - Agavi notation which action should be called
  • hide - Do not display the cronk in the menu (But can be called through some code anyway)
  • description - Information, shown on tooltips
  • name - The displayed name (note the name to load is the container element name attribute)
  • categories - Comma seperated list of categories
  • groupsonly - Comma seperated list of icinga-web groups the cronk will is available only
  • ae:parameter - Subcontainer of preconfigured parameters (So you can provide the same cronk multiple times with different configurations)

Right on, dude - write some code!

Ok, first you need a module which carries your cronk, let's say this is 'Cronks'. Also we'll need a namespace, because there are more cronks in the module.

Create an agavi action

Invoke the agavi build tool by typing

You will be asked for the module name and the action, please enter 'Cronks' and 'ExampleHelloWorld'. For all other queries you can keep the default values.

Create the configuration

Open app/modules/Cronks/config/cronks.xml and add your entry at the end:

The categories are predefined and must exist, if you want to add new you have to edit app/modules/Cronks/config/module.xml.

Editing the validator

Open the validator file (app/modules/Cronks/validate/Example/HelloWorld.xml) and add the default validators:

Also add the one validator which test your custom Message:

Do you notice something? Yes, it's the name of our parameter we have used in the cronk config.

Prepare the action

Open 'app/modules/Cronks/actions/Example/HelloWorldAction.class.php' and alter the content like this:

  • execute* methods are needed to process parameters write and read are agavi synonyms for GET and POST
  • isSecure configures if the actions needs a valid user session
  • getCredentials - more granular security way, test for specific credentials which attached to groups
  • handleError - Normally if an error occured (e.g. validation failues) Agavi redirects to HelloWorldErrorView which does not exist in our example

View and cache

Take a look into the files, we need no changes here.

The template

Here lives the ExtJs implementation, the template is empty on create, copy the following content into.

Cleanup

Now you're ready to run the cronk. Clean the current config cache and let the cronk come alive.

Conclusion

It's rather simple to implement a stub which runs within the portal. Take a look on the system cronk and feel what it's possible. Please note also that this is only a quick introduction.

For more information about ExtJs and Agavi, please visit their websites:

  • No labels