Parameterize your module

Important notice: As part of Advanced XML deprecation, the Module System is officially deprecated beginning with Splunk Enterprise 6.3. For more information, see Advanced XML Deprecation.

To add your module code
To add parameters

---

Example 7

---

You can define configurable items for your module at implementation time that are applied when the module initializes.

Note: The example for this tutorial, Example 7, currently only renders in the Firefox browser.

Details

This recipe builds on the Include 3rd-party libraries recipe, which renders a treemap of fixed height and width. Here, we show you how to use module parameters to make the height and width configurable.

1. We create a new module, ParameterizedTreeMap.
2. The module configuration file defines the parameters and sets the desired height and width values.
3. When the module initializes, it reads the parameters, which are used in the call to render the treemap.

 

Simple parameterization shows you how the app can be configured at initialization. The Setup your app recipe shows you how you can achieve even more app flexibility by configuring the app after initialization.

To add your module code

Create the $SPLUNK_HOME/etc/apps/Dev_tutorial/appserver/modules/ParameterizedTreeMap directory and add the following files:

• ParameterizedTreeMap.conf
• ParameterizedTreeMap.html
• ParameterizedTreeMap.js
• ParameterizedTreeMap.py

The HTML template and ParameterizedTreeMap.py files are the same as the TreeMap recipe files, except for different class names.

You need to add code to the ParameterizedTreeMap.conf and ParameterizedTreeMap.js files for defining and handling parameters.

To add parameters

1. Define the parameters in ParameterizedTreeMap.conf.

   Define the module class name and the class from which it inherits, as usual.

   [module]className = Splunk.Module.ParameterizedTreeMap superClass = Splunk.Module.DispatchingModule

   Define the parameters you want. In this example, we define a height parameter and a width parameter.

   [param:tmapWidth]required = False default = 640 label = This parameter defines the treemap width. description = this module waits for the search to complete, formats JSON data, and renders a treemap.

   [param:tmapHeight] required = Falsede fault = 320 label = This parameter defines the treemap height.

   The parameters are not required, so the treemap is rendered using a default value for undefined parameters, as shown in the next step.

2. The client JavaScript is essentially the same as the Treemap app client handler, with the addition of parameter handling.

   For this example, we define a new class.

   Splunk.Module.ParameterizedTreeMap = $.klass(Splunk.Module.DispatchingModule, {...})

   In the initialization method, we add getting the parameters into the tmapHeight and tmapWidth instance variables using getParam(). If the parameters are not specified, we provide default height and width values as the second argument.

   initialize: function($super, container) {

      $super(container);
      this.resultsContainer = this.container;
      this.tmapHeight = this.getParam('tmapHeight', 920);
      this.tmapWidth = this.getParam('tmapWidth', 420);
   

   },

   The renderResults() method that we override uses the instance height and width variables to set the Protovis treemap height and width variables.

   renderResults: function($super, results) {

          ... elided ...
      var vis = new pv.Panel().width(this.tmapWidth).height(this.tmapHeight) /
               .canvas(document.getElementById('ParameterizedTreeMapID'));
          ... elided ...
   

   You should notice the different size of the rendered treemap.

Related recipes

Include 3rd-party libraries is the base recipe for this example, without parameters.

Setup your app shows how to configure your app, post-initialization.