## Simple XML JavaScript Basics

Dashboards are composed of JavaScript components. Simple XML gives you a way to load custom JavaScript and CSS to customize the look-and-feel of your dashboard.

### Dependencies

Simple XML JavaScript depends on the following core JavaScript technologies:

- Require.js

  Retrieves and manages dependencies for module loading.

- Backbone.js

  Provides a lightweight client-side model/view framework.

### Dashboard components

Dashboard components have the following properties:

- Components are divided into component types:
  - Managers:
  - Views: Dashboard panels wrap view components, such as common UI header and progressbar components, and visualizations, such as a chart or table. Here is an example of a visualization panel:

        var chartPanel = splunkjs.mvc.Components.get("chart1");
        chartPanel.getVisualization(function(chartview) {
        	chartview.settings.set("charting.legend.placement", "none");
        });

- Each component has a unique ID.
- Components are retrieved with a getter method, using the component ID:
  - `var componentInstance = splunkjs.mvc.Components.get("<id>");`
- Component settings can be read or modified with the following getter and setter:
  - `componentInstance.settings.get("somesetting");`
  - `componentInstance.settings.set("somesetting", "newvalue");`

### Token Binding

Token replacement is enabled for the settings model of almost all Simple XML components. There are multiple token models:

- `default`
- `submitted`
- `url`

#### Getting token value

The following code snippet retrieves a token, for the `default` token model:

    var defaultTokenModel = splunkjs.mvc.Components.get("default");
    alert(defaultTokenModel.get("sometoken")); // Alerts the value for $sometoken$

#### Setting a token value

The following code snippet sets a token value, for the `default` token model:

    var defaultTokenModel = splunkjs.mvc.Components.get("default");
    defaultTokenModel.set("sometoken", "newvalue"));

#### Handling a change in token value

The following code snippet specifies a function to handle a change in the token value, for the `default` token model:

    var defaultTokenModel = splunkjs.mvc.Components.get("default");

    defaultTokenModel.on("change:sometoken", function(newValue) {
    	if(!newValue) { // newValue is empty
    		splunkjs.mvc.Components.get("mychart").$el.hide(); // Hide a chart
    	}
    });

### Auto-discovery

Auto-discovery is an advanced technique for re-using custom components, especially views, in multiple dashboards and apps.

To enable auto-discovery for instantiating views and managers declared in the DOM, you need to include JavaScript similar to the following example in the dashboard:

    <div id="tagcloud"
         class="splunk-view"
         data-require="/static/app/simple_xml_examples/components/tagcloud/tagcloud.js"
         data-options='{
                "minFontSize": 14,
                "maxFontSize": 55,
                "managerid": "tagcloud-search",
                "magnitudeField": "cpu_seconds",
                "labelField": "processor"
             }'>
    </div>

Auto-discovery traverses the DOM to find `splunk-view` or `splunk-manager` class elements.

The `splunkjs/ready` script needs to be loaded to perform auto-discovery:

    require(['splunkjs/mvc/simplexml/ready!'], function(){
        require(['splunkjs/ready!'], function(){
            // The splunkjs/ready loader script will automatically instantiate all elements
            // declared in the dashboard's HTML.
        });
    });

Note: the `splunkjs/ready!` loader script should not be loaded before the dashboard finishes rendering. This can be ensured by loading it within a `splunkjs/mvc/simplexml/ready!` loader script callback.

Choose one of the following methods for including the above auto-discovery code snippet:

- Use a dedicated JavaScript file in the `appserver/static` directory, for example `appserver/static/autodiscover.js`, and load the code from the dashboard using the custom `script` attribute:

      <dashboard script="autodiscover.js">
          ...
      </dashboard>

- Include the code in `appserver/static/dashboard.js`, which loads automatically for every Simple XMl dashboard within the app. With this method, auto-discovery works for all dashboards without specifically enabling it.