HowTo - Developing cronks for icinga-web
- HowTo - Developing cronks for icinga-web
- What you will learn here
- Under the hood, what are cronks?
- File structure
- Right on, dude - write some code!
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 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
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'
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.
Agavi cache configuration, if the content should be cached and how long.
Contains information about used parameters (GET, POST, headers, ...) and how we can access them.
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.
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.
Here lives the ExtJs implementation, the template is empty on create, copy the following content into.
Now you're ready to run the cronk. Clean the current config cache and let the cronk come alive.
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: