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

abortGetResults()

The abortGetResults() method destroys the previously submitted XHR request within the current context.

Warning: Calling this method is discouraged because misuse can cause unexpected behavior. Instead, you should call reset(). Also, overriding this method when suclassing AbstractModule is not recommended.

Synopsis

results = abortGetResults()

Return Value

Undefined

addChild()

The addChild() method adds the specified module as a child of the current instance. The child must not already have a parent.

Synopsis

status = addChild( child )

Parameters

child Object Module to be added as a child.

Return Value

Undefined

Example

var first_child = this._children[0];
var first_grandchild = first_child._children[0];
child.removeChild(first_grandchild);
this.addChild(first_grandchild);

applyContext()

The applyContext() method handles context changes that flow from descendants to ancestors, when a context change needs to traverse up the hierarchy.

Upward traversal of a context can cause unexpected behavior and should be avoided, if possible. This method

is not implemented, by default, and is intended to be overridden by modules that subclass AbstractModule.

Synopsis

results = applyContext( context )

Parameters

context Object Context to be passed upstream.

Return Value

Undefined

Example

applyContext: function($super, context) {

   if (this.isPageLoadComplete()) {
       var search = context.get("search");
       if (search.search(/\spony\W+/i) > -1) {
           alert('I found the p0ny!');
       } else {
           alert('p0ny detection phail');
       }
       return $super(context);
   }

},

displayInlineErrorMessage()

The displayInlineErrorMessage() method displays the specified message in the module.

Synopsis

results = displayInlineErrorMessage( message )

Parameters

message String Message to display.

Return Value

Undefined

Example

this.displayInlineErrorMessage('Game 0v3r!!1');

ensureFreshContexts()

The ensureFreshContexts() method propagates context changes downstream for ancestors that have stale context that has not been propagated. For example, when a user types into an input field, but submits the form by clicking "enter" on another form field.

Synopsis

results = ensureFreshContexts()

Return Value

Boolean Error indication:
False = An ancestor context contains a search that has already been dispatched.

Exceptions

TBD

Example

this.ensureFreshContexts();

getAncestors()

The getAncestors() method gets an ordered list of calling module ancestors.

Note: You should generally call the withEachAncestor() iterator instead of this method.

Synopsis

ancestors = getAncestors()

Return Value

Array Ordered list of ancestors.

Example

alertEachAncestor: function() {

   var ancestors = this.getAncestors();

   $.each(ancestors, function(i, v) {
       alert(v);
   });

},

getContext()

The getContext() method gets the most current Splunk.Context search context, which is the accumulated information from all module ancestors.

Note: This method should not be overridden.

Synopsis

context = getContext()

Return Value

Object Current context.
null = Could not get a context object.

Throws

Message: "getContext was called by <this> (moduleId)s with no baseContext. </this><this> (moduleId)s's parent returned a null context. This should not happen." </this>

Example

var context = this.getContext();
var search = context.get('search');

getDescendants()

The getDescendants() method gets an ordered list of all module descendants.

Note: This method should not be overridden.

Synopsis

results = getDescendants( self, **args )

Return Value

Array Ordered list of descendants.

Example

var descendants = this.getDescendants();
for (var i=0, len=descendants.length; i < len; i++) {

   descendants[i].reset();

getGroupName()

The getGroupName() method gets the current module group name. If a group name does not exist for the module, it returns the parent group name.

Synopsis

group = getGroupName()

Return Value

String Group name parameter of current module or parent module.
False = Group name not found.

Example

if (!this.getGroupName()) {

   alert('Neither this module nor its parent has a 'group' param');

getLoadState()

The getLoadState() method gets the module load state.

Synopsis

loadstate = getLoadState()

Return Value

Constant Module load state:
WAITING_FOR_INITIALIZATIONWAITING_FOR_HIERARCHYWAITING_FOR_CONTEXT HAS_CONTEXT

Example

if (this.getLoadState() < Splunk.util.moduleLoadStates.HAS_CONTEXT) {

   return;

} else {

   alert('I have a context and can proceed with some useful function');

getModifiedContext()

The getModifiedContext() method provides a proxy for getContext(), by default. This method is intended to be overridden to pass a modified context to children. Modified contexts might include search, time range or other functional changes.

Synopsis

results = getModifiedContext()

Return Value

Object Modified context.

Example

getModifiedContext: function() {

   var context = this.getContext();

   if (!this.isEmpty()) {  
       var search  = context.get("search"); 
       var searchTermStr = this._getUserEnteredSearch();
       this.logger.info('getModifiedContext - got search=', searchTermStr);

       if (this.baseContext)
           this.logger.warn(this.moduleType, "WARNING: clobbering base search.");
       search.abandonJob();
       search.setBaseSearch(searchTermStr);
       context.set("search", search);
   }  
   return context;

},

getModulesInTree()

The getModulesInTree() method gets a list of all modules in the current module tree.

Synopsis

results = getModulesInTree()

Return Value

Array List of modules in current module tree.

Example

var modules = this.getModulesInTree();
for (var i=0; i<modules.length; i++) {

   modules[i].reset();

getParam()

The getParam() method gets the value for the specified parameter key. You can specify a fallbackValue, if the module does not have a value explicitly set for the key. The fallbackValue supercedes the value set in the .conf file.

Synopsis

param = getParam( key, fallbackValue )

Parameters

key	`String`	Parameter key.
fallbackValue	`String`	Fallback parameter value, if the key parameter is not set.

Return Value

Undefined The key or fallbackValue value, or Null if key or fallbackValue are not defined.

Throws

Error 'getParam: Splunk cannot get param; null key name passed'

Example

var entityName = this.getParam("entityName", "events");
if (entityName === "results") {

   alert('This module has been configured to operate on results');

} else {

   alert('This module has not been configured to operate on results');

getResultParams()

The getResultParams() method gets modified/refined/extended parameters when called by functions such as getResults().

Note: This method is intended to be overridden and returns an empty object by default.

Synopsis

param = getResultParams()

Return Value

Object Results params.

Example

getResultParams: function() {

   var context = this.getContext();
   var params = {
       output_mode: this._params['outputMode'],
       fields: [],
       sort_key: this.sortBy,
       sort_dir: this.sortDir,
       count:  context.get('results.count'),
       offset: context.get('results.offset')
   };

   if (this._params['labelField']) params['fields'].push({'label': this._params['labelField']});  
   if (this._params['valueField']) params['fields'].push({'label': this._params['valueField']});
   for (var i=0, j=params['fields'].length; i<j; i++) {
       params['fields'][i] = JSON.stringify(params['fields'][i]);
   }  
   return params;

},

getResults()

The getResults() method gets the calling module HTML content to render from the server.

Upon successfully getting the data from the module controller, this method calls renderResults(). Two callback functions are also bound to the completion status of the ajax operation: getResultsCompleteHandler() and getResultsErrorHandler().

Synopsis

results = getResults()

Return Value

Undefined

Example

onJobDone: function(event) {

   if (this.getInferredEntityName()=="results") {
       this.getResults();
   }

},

getResultsCompleteHandler()

The getResultsCompleteHandler() callback function handles AJAX request completion initiated by a getResults() call.

This method is not implemented, by default, and should be overridden.

Synopsis

results = getResultsCompleteHandler( xhr, textStatus )

Parameters

xhr	`Object`	`XMLHTTPResponse` object passed by the AJAX response.
textStatus	`String`	Text status code passed by the AJAX response.

Return Value

Undefined

Example

getResultsCompleteHandler: function(xhr) {

   var length = xhr.getResponseHeader('X-Splunk-List-Length');
   var context = this.getContext();
   var callback = context.get("results.totalCountCallback");

   if (this.totalCountCallback == null && typeof callback == 'function') {
       this.totalCountCallback = callback;
   }

   if (length && this.length != length && this.totalCountCallback) {
       this.length = length;
       this.totalCountCallback(length);
   }

   var t = setTimeout(this._adjustLayout, 100);

},

getResultsErrorHandler()

The getResultsErrorHandler() callback function handles an AJAX request returning an error.

Note: This function is implemented by default but is intended to be overridden.

Synopsis

results = getResultsErrorHandler( xhr, textStatus, exception )

Parameters

xhr	`Object`	`XMLHTTPResponse` object passed by the AJAX response.
textStatus	String	Text status code passed by the AJAX response.
exception	Exception	The type of exception to throw.

Return Value

Undefined

Throws

If exception is not ' undefined', exception.

Example

getResultsErrorHandler: function(xhr, textStatus, exception) {

   if (xhr.status >= 404) {
       var errorMsg = _('An error was returned: "%(statusText)s".');
       var errorVars = {status: xhr.status, statusText: xhr.statusText};
       this.displayInlineErrorMessage(sprintf(errorMsg, errorVars));
   }

},

getResultURL()

The getResultURL() method gets the URI query string representing the path to the calling module controller, which contains module content to be rendered.

Note: This method is called by getResults().

Synopsis

uri = getResultURL( params )

Parameters

params Object result params to add to the resultURL query string.

Return Value

String URI and query string representing the path to the calling module controller.

Example

var resultUrl = this.getResultURL(params);
if (!resultUrl) {

   this.logger.warn("getResultsURL() appears to be unimplemented or returning null for this instance.");

}
this.getResultsXHRObject = $.ajax({

   type: "GET",
   cache: ($.browser.msie ? false : true),
   url: resultUrl,

   ... elided ...

});

getRootAncestor()

The getRootAncestor() method gets the root module in the module tree.

Synopsis

resp = getRootAncestor()

Return Value

Object Splunk.Module object representing the module at the module tree root.

Example

getModulesInTree: function() {

   var root = this.getRootAncestor();
   return [root].concat(root.getDescendants());

},

haveResultParamsChanged()

The haveResultParamsChanged() helper function determines if the current result parameters have changed.

Synopsis

changed = haveResultParamsChanged()

Return Value

Boolean Result parameters changed indication:
true = Result parameters changed.
false = Result parameters did not change.

Example

onContextChange: function($super){

   if(this.haveResultParamsChanged() && (search.job.isDone()
           (search.job.getEventAvailableCount() > 0))){ 
       this._pageComplete = false;
       this.getResults();
   }

},

hide()

The hide() helper function sets the calling module invisibilityMode, hidden or not hidden.

Note: This method is called by hideDescendants() and showDescendants() and is not intended to be overridden.

Synopsis

results = hide( invisibilityMode )

Parameters

invisibilityMode Constant Dictionary of URI name-value pair GET request params.

Return Value

Undefined

Example

initialize: function($super, container){

   $super(container);
   $("a", this.container).click(function(event) {
       var popup = Splunk.util.normalizeBoolean(this._params["popup"]);
       this.sendToView({}, popup);
       return false;
   }.bind(this));
   if (!Splunk.util.normalizeBoolean(this._params["dispatchBeforeRedirect"])) {
       $("a", this.container).hide();
   }  
   this.show(this.HIDDEN_MODULE_KEY);

},

hideDescendants()

The hideDescendants() method hides the calling module and all descendant modules.

Note: This module is not intended to be overridden.

Synopsis

hideDescendants( invisibilityMode )

Parameters

invisibilityMode String Invisibility mode the current module should store.

Return Value

Undefined

Example

onContextChange: function($super) {

   $super();
   this._selection = null;
   this.hideDescendants(this.DRILLDOWN_VISIBILITY_KEY + "_" + this.moduleId);
   this.renderedCount = -1;
   var context = this.getContext();
   if (this.haveResultParamsChanged()) {
       var search  = context.get("search");
       if (search.job.isDone()  (search.job.getEventAvailableCount() > 0)) {
           this._pageComplete = false;  this.getResults();
       }  
   }  
   else if (context.has("results.dataOverlayMode")){
       this.onResultsRendered();
   }

},

importParams()

The importParams() method imports module startup parameters passed by the module configuration system. Usually, configuration settings are static, so this method should not be called after view initialization.

Note: This module is not intended to be overridden.

Synopsis

importParams()

Return Value

Undefined

Example

this.importParams();
if (this._params.hasOwnProperty('foobar')) {

   alert('foobar was found!')

isPageLoadComplete()

The isPageLoadComplete() method gets the page loaded status.

Note: This module is not intended to be overridden.

Synopsis

status = isPageLoadComplete()

Return Value

Boolean Page loaded status indication:
true = Page loading is complete.
false = Page loading is not complete.

Example

applyContext: function(context) {

   if (this.isPageLoadComplete()) {
       var search = context.get("search");
       var fieldsIntention = search.getIntentionReference("setfields");

       if (fieldsIntention) {
           this.selectedFields = [];
           var fields = fieldsIntention["arg"];
           for (var i=0; i<fields.length; i++) {
               var field = fields[i];  
               if (field.charAt(0)!=="_") {
                   this.selectedFields.push(field);
               }  
           }  
           this.setSelectedFieldList(this.selectedFields);
           this.pushContextToChildren();
           return true;
       }  
   }

},

isReadyForContextPush()

The isReadyForContextPush() method sets up the contract for propagating the context to child modules when pushContextToChildren() is called, depending on whether or not page load has completed.

Note: This module is intended to be overridden.

Synopsis

status = isReadyForContextPush()

Return Value

`Boolean`	[Default] Module ready for context push indication: true = Module is ready for a context push. false = Module is not ready for a context push.
`Integer`	[Override] Module ready for context push indication: CANCEL = No selected state, stop context pushes. CONTINUE = Job is finished, push context. DEFER = Job is not finished, do not push context.

Example

isReadyForContextPush: function($super) {
	if (!$super()) return false;

       if (this.hasLoaded) return Splunk.Module.CONTINUE;
       else return Splunk.Module.DEFER;
   },

markPageLoadComplete()

The markPageLoadComplete() method sets the page load completion status.

Synopsis

results = markPageLoadComplete( self, **args )

Return Value

Undefined

Example

pushContextToChildren: function(explicitContext) {

   var readiness = this.isReadyForContextPush()

   if (readiness == Splunk.Module.CANCEL) {
if (!this.isPageLoadComplete()) {
           var propagateLoadCompleteFlag = function(module) {
               module.markPageLoadComplete(); 
               module.withEachChild(function(child) {
                   propagateLoadCompleteFlag(child);
               });  
           };  
           propagateLoadCompleteFlag(this);
       }  
       return;
   }

},

mergeLoadParamsIntoContext()

The mergeLoadParamsIntoContext() method pushes non-search parameters to child modules.

Synopsis

results = mergeLoadParamsIntoContext( namespace, paramNames)

Parameters

namespace	`String`	Namespace the params should retain.
paramNames	`Array`	Keys passed to child modules.

Return Value

Undefined

Example

initialize: function($super, container){

   $super(container);
   this.childEnforcement = Splunk.Module.NEVER_ALLOW;
   this.logger = Splunk.Logger.getLogger("events_viewer.js");
   this.mergeLoadParamsIntoContext("results", ["displayRowNumbers", "segmentation"]);

},

onBeforeJobDispatched()

The onBeforeJobDispatched() method provides a mechanism for changing job settings before the job is dispatched, typically to change result parameters. The main purpose is to set the required_field_list and status_buckets params on the POST which dispatches the job.

Note: This method is intended to be overridden.

Synopsis

onBeforeJobDispatched( search )

Parameters

search Object Splunk.Search object to be acted upon.

Return Value

Undefined

Example

onBeforeJobDispatched: function(search) {

   var fields = this.getNormalizedFields();

   if (this.entityName!="results") {
       search.setMinimumStatusBuckets(1);
       if (fields.length>0) {
           search.setRequiredFields(fields);
       }  
   }

},

onContextChange()

The onContextChange() method handles the context change event. The method is called when the underlying context instance available in this.getContext() ha s changed.

Note:This method is intended to be overridden.

Synopsis

onContextChange()

Return Value

Undefined

Example

onContextChange: function() {

   var context = this.getContext();
   var search = context.get('search');
   var new_search = 'index=example sourcetype=documentation';

   search.setBaseSearch(new_search);
   context.set('search', new_search);

},

onLoadStatusChange()

The onLoadStatusChange() handler is invoked when the current module load status changes, if the notification has not been suppressed by setLoadState().

The default implementation of this method calls validateHierarchy(), if the module has a context. This method is intended to be overridden.

Synopsis

onLoadStatusChange( status )

Parameters

status Integer New load status.

Return Value

Undefined

Example

onLoadStatusChange: function($super, statusInt) {

   $super(statusInt);
   if (statusInt == Splunk.util.moduleLoadStates.LOADED) {
       var context = this.getContext();
       if (context === null) {
           this.logger.warn('getContext could not retrieve a context');
           return;
       }  
       if (context.get("results.dataOverlayMode")) {
           this.onResultsRendered();
       }  
   }  
       else if (statusInt == Splunk.util.moduleLoadStates.WAITING_FOR_HIERARCHY) {
           this.hideDescendants(this.DRILLDOWN_VISIBILITY_KEY + "_" + this.moduleId);
   }

},

onResultsRendered()

The onResultsRendered() event handler performs any actions required after results are rendered. This method is called by renderResults().

Note: This method is not implemented, by default, so you must provide it.

Synopsis

onResultsRendered()

Return Value

Undefined

Example

onResultsRendered: function() {

   var context = this.getContext();

   if (!context.has("results.dataOverlayMode")) return false;
   switch(context.get("results.dataOverlayMode")) {
       case "none":
           this.resetHeatMap(this.container);
           this.decorateBounds(this.container, false, false);
           break;
       case "heatmap":
           this.decorateBounds(this.container, false, false);
           this.decorateHeatMap(this.container);
           break;
       case "highlow":
           this.resetHeatMap(this.container);
           this.decorateBounds(this.container, true, true);
           break;
       default:
           this.logger.warn("Context contains unsupported dataOverlayMode value of", context.get("results.dataOverlayMode"));
   }

},

onViewDataChange()

The onViewDataChange() handler is called by the app server to generate module HTML content in response to a GET request.

Synopsis

results = onViewDataChange( event, data)

Parameters

event	`Object`	jQuery event.
data	`Object`	Object literal representation of all `templateArgs` returned from the `view.py` render method.

Return Value

Undefined

Example

onViewDataChange: function(event, data){

   if(data.navConfig){
       try{
           var menuData = this.parseNavConfig(data.navConfig);
       }catch(e){
           this.logger.error("Unable to parse JSON navConfig for appbar menu", e); 
           return;
       }

       this.removeMainMenus();
       this.generateMainMenus(menuData);
       this.logger.info("onViewDataChange fired, successfully reloaded main menu data in AppBar");
   }

},

passContextToParent()

The passContextToParent() method passes the current module context to the parent module until a parent is found that accepts the context.

Note: Be careful using this method because of the inherent complexity of contexts passing in both directions of the hierarchy.

Synopsis

results = passContextToParent( context )

Parameters

context Object Module context to pass to parent.

Return Value

Boolean Context accepted indication:
True = An upstream parent accepted the context.
False = No upstream parent accepted the context.

Example

onTimestampSelect: function(event) {

   var em = $(event.target);
   var epoch = em.attr(this.TIMESTAMP_EPOCH_TIME_ATTRIBUTE_NAME);

   if (epoch) {
       epoch = parseInt(epoch, 10);
       var context = new Splunk.Context();
       var search = new Splunk.Search();
       var range = new Splunk.TimeRange(epoch,  epoch+1);
       search.setTimeRange(range);
       context.set("search", search);
       this.passContextToParent(context);
   } else {
       this.logger.error("cannot continue.");
   }  
   return false;

},

pushContextToChildren()

The pushContextToChildren() method passes the current module context to all child modules.

Note: This method is not intended to be overridden. It is recommended that you use onContextChange() to refine the context before it is passed to children.

Synopsis

results = pushContextToChildren( explicitContext )

Parameters

explicitContext Object Explicit context to be passed to children. If omitted, getContext() is called to provide the context.

Return Value

Undefined

Example

_onMenuClick: function(evt) {

   var t = evt.target;

   if ( $(t).parent('li').hasClass('timeRangePreset') ) { 
       this._setSelectedRangeToPreset($(t));
       this.setParam('default', this._getRawLabel($(t).text()));

       if (Splunk.util.normalizeBoolean(this.getParam('searchWhenChanged'))) {
           this.pushContextToChildren();
       } else {
           this.setChildContextFreshness(false);
       }

       $('.timeRangeActivator', this.container).text($(t).text());
   }

},

pushViewDataChange()

The pushViewDataChange() method broadcasts that view data has been changed by the controller. Because every module subclassed from Splunk.Module has a listener on the viewDataChange event, it is unlikely that this method needs to be called.

Note: This method is not intended to be overridden.

Synopsis

pushViewDataChange()

Return Value

Undefined

Example

this.pushViewDataChange();

removeChild()

The removeChild() method removes the specified child module from the current module hierarchy. The childModule must exist and be a child of the caller.

Note: The removed child module is orphaned.

Synopsis

removeChild( childModule )

Parameters

args Object Splunk.Module object of the child to be removed.

Return Value

Undefined

Example

this.withEachChild( function(child) {

   this.removeChild(child);
   return false;

});

renderResults()

The renderResults() method inserts content into the module results container within the DOM. The default implementation replaces the module resultsContainer content with the htmlFragment passed to it, usually from the module controller.

Synopsis

results = renderResults( htmlFragment, turbo)

Parameters

htmlFragment	`String`	Dictionary of URI name-value pair GET request params.
turbo	`Boolean`	HTML injection directive: `True` = Use shallow clone for faster html injection. (Caution: All event listeners will be lost in clone.) `False` = Do not use shallow clone for faster html injection.

Return Value

Undefined

Example

renderResults: function($super, htmlFragment) {

   $super(htmlFragment);
   if (this.getInferredEntityName()=="events") {
       this.renderedCount = $("tr", this.container).length - 1;
   }

},

requiresAsynchronousLoading()

The requiresAsynchronousLoading() method indicates whether or not the module hierarchy must be complete before loading the current module. If the module can be loaded asynchronously, the module must make sure the corresponding moduleLoadStatusChange event is fired after loading.

Subclass this module to change the behavior to depend on your specific configuration.

Synopsis

asyncLoad = requiresAsynchronousLoading()

Return Value

Boolean Asynchronous loading required indication:
True = This module does not depend on the module hierarchy to be complete.
False = (Default) This module depends on the module hierarchy to be complete.; WAITING_FOR_HIERARCHY

Example

requiresAsynchronousLoading: function() {return true;},

requiresDispatch()

The requiresDispatch() method indicates whether or not the module requires a context with dispatched search to function correctly.

Subclass this module to change the behavior to depend on your specific configuration.

Synopsis

dispatch = requiresDispatch( search )

Parameters

search Object Splunk.Search object to be dispatched.

Return Value

Boolean Module requires context with dispatched search indication:
True = Module does not require a context.
False = (Default) Module requires a context.

Example

requiresDispatch: function() {return true;},

reset()

The reset() method resets the current module context and UI. The method calls resetContext() and resetUI(), which may be overridden.

Synopsis

reset()

Return Value

Undefined

Example

this.withEachChild(function(child) {

   child.reset();

});

resetContext()

The resetContext() method resets the current context, setting the current context to null and removing the job from the job manifest..

Synopsis

resetContext()

Return Value

Undefined

Example

reset: function() {

   this.abortGetResults();
   this.resetContext();
   this.resetUI();

},

resetUI()

The resetUI() method resets the module user interface to an initial state.

Note: This module is intended to be overridden with behavior specific to the module.

Synopsis

resetUI()

Return Value

Undefined

Example

resetUI: function(){

   this.resultsContainer.html("");

},

resizeWidthToParent()

The resizeWidthToParent() handler resizes the current module to be the same width as parent module.

Note: This module should not be overridden.

Synopsis

resizeWidthToParent()

Return Value

Example

$(window).bind('resize', this.resizeWidthToParent.bind(this));

setChildContextFreshness()

The setChildContextFreshness() method marks the freshness of the context held by child modules, permitting the calling module to validate or invalidate child freshness without traversing the module tree.

Note: This module should not be overridden.

Synopsis

results = setChildContextFreshness( contextStatus )

Parameters

contextStatus Boolean Status to set child module contexts to:
True = Mark context as fresh.
False = Mark context as stale.

Return Value

Undefined

Example

pushContextToChildren: function(explicitContext) {

   this.withEachChild(function(child) {
       child.baseContext = childContext;
       child.setLoadState(Splunk.util.moduleLoadStates.HAS_CONTEXT);
       child.onContextChange();
       child.pushContextToChildren();
       if (!child.isPageLoadComplete()) {
           child.markPageLoadComplete();
       }
   });
   this.setChildContextFreshness(true);

},

setLoadState()

The setLoadState() method changes the current module load state and, optionally, invokes the onLoadStatusChange() event handler.

Synopsis

setLoadState( statusInt, suppressEvent)

Parameters

statusInt	`Integer`	Dictionary of URI name-value pair GET request params.
suppressEvent	`Boolean`	Invoke event handler indication: True = Invoke event handler. False = (Default) Do not invoke event handler.

Return Value

Undefined

Example

pushContextToChildren: function(explicitContext) {

   this.withEachDescendant(function(module) {
       module.setLoadState(Splunk.util.moduleLoadStates.WAITING_FOR_CONTEXT);
   });

   this.withEachChild(function(child) {
       child.baseContext = childContext;
       child.setLoadState(Splunk.util.moduleLoadStates.HAS_CONTEXT);
       child.onContextChange();
       child.pushContextToChildren();
       if (!child.isPageLoadComplete()) {
           child.markPageLoadComplete();
       }
   });

   this.setChildContextFreshness(true);
},

setParam()

The setParam() method sets the value of the specified parameter and, optionally, specifies the key - value persistence duration.

Synopsis

setParam( key, value, isSessionOnly)

Parameters

key	`String`	Name of parameter to persist.
value	`String`	Value of key.
isSessionOnly	`Boolean`	Instance persistence indication: `True` = Parameter value only persists for current instance. `False` = (Default) Parameter value persists independent of the current instance.

Return Value

Undefined

Throws

'... - Cannot build name; null key'

Example

this.setParam('label', 'Pony Rides per Day', True);

show()

The show() method makes the current module visible and sets the visibility mode.

Synopsis

show( invisibilityMode )

Parameters

invisibilityMode String Invisibility mode string. If a mode is not specified, the mode is set to "global."

Return Value

Undefined

Example

showDescendants: function(invisibilityMode) {

   if (!this.isSwitcherLeaf) {
       for (var i=0; i<this._children.length;i++) {
           this._children[i].show(invisibilityMode);
           this._children[i].showDescendants(invisibilityMode);
       }  
   }

},

showDescendants()

The showDescendants() method sets child modules to visible.

Synopsis

showDescendants( invisibilityMode )

Parameters

invisibilityMode String A common invisibility mode to be passed to child modules.

Return Value

Undefined

Example

onRowClick: function(evt) {

   this.showDescendants(this.DRILLDOWN_VISIBILITY_KEY + "_" + this.moduleId);

},

snapshotParamset

The snapshotParamset() method gets a snapshot of the current state of persistable module parameters.

Synopsis

snapshotParamset()

Return Value

Undefined

Example

var tempParams = this.snapshotParamset();
if ('fookey' in tempParams) {

   delete tempParams.fookey;

someChildrenRequireDispatch()

The someChildrenRequireDispatch() helper method determines if any immediate children require a dispatched search in the context pushed to them.

Synopsis

status = someChildrenRequireDispatch( search )

Parameters

search Object Splunk.Search object.

Return Value

Boolean Dispatched search required indication:
True = At least one immediate child module requires a dispatched search.
False = No child modules require a dispatched search.

Example

pushContextToChildren: function(explicitContext) {

   if (this.someChildrenRequireDispatch(search)) {
       search.abandonJob();
       this.withEachDescendant(function(module) {
           module.onBeforeJobDispatched(search);
       });
       this._fireDispatch(search);
       return;
   }

},

validateHierarchy()

The validateHierarchy() method validates the current module hierarchy and displays one of the following error messages, if the hierarchy is invalid:

	"This view has a %s module but it is configured with no child modules to push its changes to. This represents a configuration error."
	"This view has a %s module configured to push changes to downstream modules. This module never has any changes to push so this represents a configuration error."
	"This view has a %s module but that module has no parent modules to receive changes from. This module will not work in this configuration so this represents a configuration error."
	"This view has a %s module but that module receives changes from other modules upstream. Since this module will ignore all such changes, this represents a configuration error."

This method is called by the default implementation of onLoadStatusChange().

The module uses the childEnforcement and parentEnforcement values to perform validation. For example, if your module requires children to function properly, set:

this.childEnforcement = Splunk.Module.ALWAYS_REQUIRE;

to ensure that anyone consuming your module receives a hierarchy validation error.

In addition to providing error messaging, this method sets:

this._hierarchyValidated = true;

Synopsis

validateHierarchy()

Return Value

Undefined

Example

onLoadStatusChange: function(statusInt) {

   if (!this._hierarchyValidated &&
         (statusInt >= Splunk.util.moduleLoadStates.WAITING_FOR_CONTEXT)) {
       this.validateHierarchy();
   }

},

withEachAncestor()

The withEachAncestor() method passes each ancestor module of the current module to the specified callback function.

Synopsis

status = withEachAncestor( fn, reverse )

Parameters

fn	`Function`	Function that acts on ancestor module passed as an argument.
reverse	`Boolean`	Direction to traverse ancestor list: `True` = Traverse ancestor list in the direction of root to child. `False` = (Default) Traverse ancestor list in the direction of child to root.

Return Value

Boolean Status indication:
True = Ancestors successfully traversed.
False = The callback function, fn, returned False for one of the ancestors; operation terminated.

Example

ensureFreshContexts: function() {

   if (this.getContext().get('search').isJobDispatched()) {
       return;
   }

   var stale = null;
   this.withEachAncestor(function(module) {
       if (module.getContext().get('search').isJobDispatched()) {
           return false;
       }
       if (!module._childModulesHaveFreshContexts) {
           stale = module;
       }
   }, true);

   if (stale) {
       stale.withEachDescendant(function (child) {
           child.baseContext = null;
       });
       stale.setChildContextFreshness(true);
   }

},

withEachChild()

The withEachChild() method passes each immediate child of the current module to the specified callback function.

Note: Only immediate child modules are operated on, not grandchildren.

Synopsis

status = withEachChild( fn )

Parameters

fn Function Function that acts on child module passed as an argument.

Return Value

Boolean Status indication:
True = Child modules successfully traversed.
False = The callback function, fn, returned False for one of the children; operation terminated.

Example

someChildrenRequireDispatch: function(search) {

   var requireDispatch = false;
   this.withEachChild(function(child) {
       if (child.requiresDispatch(search)) {
           requireDispatch = true;
           return false;
       }
   });
   return requireDispatch;

},

withEachDescendant()

The withEachDescendant() method passes each descendant module of the current module to the specified callback function.

Synopsis

status = withEachDescendant( callback )

Parameters

callback Function Function that acts on descendant module passed as an argument.

Return Value

Boolean Status indication:
True = Descendant modules successfully traversed.
False = The callback function returned False for one of the descendants; operation terminated.

Example

someChildrenRequireDispatch: function(search) {

   var requireDispatch = false;
   this.withEachChild(function(child) {
       if (child.requiresDispatch(search)) {
           requireDispatch = true;
           return false;
       }
   });
   return requireDispatch;

},

Module System Reference

Splunk.Module

abortGetResults()

Synopsis

Return Value

See Also

addChild()

Synopsis

Parameters

Return Value

Example

See Also

applyContext()

Synopsis

Parameters

Return Value

Example

See Also

displayInlineErrorMessage()

Synopsis

Parameters

Return Value

Example

ensureFreshContexts()

Synopsis

Return Value

Exceptions

Example

See Also

getAncestors()

Synopsis

Return Value

Example

See Also

getContext()

Synopsis

Return Value

Throws

Example

See Also

getDescendants()

Synopsis

Return Value

Example

See Also

getGroupName()

Synopsis

Return Value

Example

See Also

getLoadState()

Synopsis

Return Value

Example

See Also

getModifiedContext()

Synopsis

Return Value

Example

See Also

getModulesInTree()

Synopsis

Return Value

Example

See Also

getParam()

Synopsis

Parameters

Return Value

Throws

Example

See Also