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

See Also

reset()

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);

See Also

removeChild()

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);
   }

},

See Also

getContext()
isPageLoadComplete()
onContextChange()
passContextToParent()

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();

See Also

getModifiedContext()
pushContextToChildren()
setChildContextFreshness()
withEachAncestor()

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);
   });

},

See Also

getDescendants()
getModulesInTree()
getRootAncestor()
withEachAncestor())

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');

See Also

applyContext()
getModifiedContext()
onContextChange()

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();

}

See Also

getAncestors()
getModulesInTree()
getRootAncestor()

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');

}

See Also

getParam()

getLoadState()

The getLoadState() method gets the module load state.

Synopsis

loadstate = getLoadState()

Return Value

Constant

Module load state: WAITING_FOR_INITIALIZATION WAITING_FOR_HIERARCHY WAITING_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');

}

See Also

setLoadState()

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;

},

See Also

ensureFreshContexts()
getContext()
onContextChange()

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();

}

See Also

getAncestors()
getDescendants()
getRootAncestor()

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');

}

See Also

importParams()
setParam()
snapshotParamset()

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;

},

See Also

getResults()
haveResultsParamsChanged()

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();
   }  

},

See Also

getResultURL()
renderResults()
getResultsCompleteHandler()
getResultsErrorHandler()
getResultParams()
haveResultParamsChanged()

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); 

},

See Also

getResults()
getResultsErrorHandler()

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));
   }  

},

See Also

getResults()
getResultsCompleteHandler()

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

});

See Also

getResults()

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());

},

See Also

getModulesInTree()
getAncestors()
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();
   }  

},

See Also

getResults()
getResultParams()
onContextChange()

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);

},

See Also

hideDescendants()
show()
showDescendants()

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();
   }  

},

See Also

hide()
showDescendants()
show()

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!')

}

See Also

getParam()
setParam()
snapshotParamset()

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;
       }  
   }  

},

See Also

markPageLoadComplete()
onLoadStatusChange()
applyContext()

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;
   },

See Also

getLoadState()
markPageLoadComplete()
onLoadStatusChange()
pushContextToChildren()

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;
   }

},

See Also

isPageLoadComplete()
onLoadStatusChange()

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"]);

},

See Also

importParams()
snapshotParamset()

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);

},

See Also

getContext()
getModifiedContext()
haveResultParamsChanged()
applyContext()

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);
   }  

},

See Also

getLoadState()
setLoadState()
validateHierarchy()

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"));
   }  

},

See Also

getResults()
renderResults()

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;

},

See Also

applyContext()
onContextChange()
pushContextToChildren()

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());
   }  

},

See Also

applyContext()
ensureFreshContexts()
getContext()
getModifiedContext()
onContextChange()
passContextToParent()

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;
   }  

},

See Also

getResults()
onResultsRendered()

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;},

See Also

requiresDispatch()

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;},

See Also

requiresAsynchronousLoading()
someChildrenRequireDispatch()

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();

});

See Also

abortGetResults()
resetContext()
resetUI()

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();

},

See Also

abortGetResults()
reset()
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("");

},

See Also

abortGetResults()
reset()
resetContext()

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()

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);

},

See Also

ensureFreshContexts()

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);
},

See Also

getLoadState()
onLoadStatusChange()

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);

See Also

getParam()
importParams()
snapshotParamset()

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);
       }  
   }  

},

See Also

hide()
hideDescendants()
showDescendants()

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);

},

See Also

hide()
hideDescendants()
show()

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;

}

See Also

getParam()
importParams()
setParam()

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;
   }

},

See Also

requiresDispatch()

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();
   }  

},

See Also

onLoadStatusChange()

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);
   }

},

See Also

ensureFreshContexts()
getAncestors()
withEachChild()
withEachDescendant()

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;

},

See Also

someChildrenRequireDispatch()
withEachAncestor()
withEachDescendant()

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;

},

See Also

someChildrenRequireDispatch()
withEachAncestor()
withEachDescendant()