MCS Publishing | PPF Text Widget

PPF Text widget

Below is an example of ALL the options available when defining a text widget. Some options are required, the options that are not required don't need to be defined unless something other than default is desired.

var ppf_widgets = {
    example_text: { //Name of widget, these must be unique within the ppf_widget definitions
        ele: [ 'txt1', 'txt2'], //REQUIRED
        data:  'speeddata', //REQUIRED
        type: 4, //REQUIRED
		  datadepend: ['voip','act'],
        text: '<p>Custom text here</p>',
        depend: [
            ['endofmonth', 'tuesday'],
            ['endofweek', 'wednesday']
        ]
    }
}

Defining a text widget

Key	Value
ele	Required. The element(s) defined here refer to HTML elements that should be present in the HTML page that pairs with the PPF. So, if the HTML element the table should appear in is `<div id='speedtable'></div>` the ele definition would be `ele: ['speedtable']`
data	Required. Data refers to the data set name that should be used for the text. For example, if the following data set had been defined `var ppf_datasets = { data: { speeddata: { plugins: ['speed'], last: '1', unit: 'hour', by: 10 } } }` The data value for the text would be... `data: 'speeddata'`
datadepend	`datadepend: ['voip','act']` If a widget is dependant on a certain data type then define a data dependency value. The format is an array. Common test types that can be defined are voip, act (which is Quality speed data), route, and capacity.
type	Required. Text is type 4 and must be defined. When defined it should look like this `type: 4`
text	Text can be as little as one word or as much as multiple paragraphs. HTML markup is accepted, too. Below is an example of a basic text definition. `text: '<p>Custom text here</p>'` For more complex examples see: Using data metrics in a text widget Using PPF variables in a text widget Using PPF expressions in a text widget
depend	Click here for dependency information.

Text widget examples

Using data metrics in a text widget

Using data in text widgets is a useful way to add more value to a report. Metrics in text widgets can be defined in two ways.

The first is $$testtype.testmetric$$. For example, $$speed.dspeed$$ would return the average result for Download Speed for the data set defined by the text widget.

text: '<p>The download speed result is $$speed.dspeed$$</p>'

The second is $$dataname.testtype.testmetric$$. For example, $$speeddata.speed.dspeed$$ would return the average result for Download Speed for the data set named speeddata. This allows text widgets to include metrics from various data sets.

text: '<p>The download speed result is $$speeddata.speed.dspeed$$</p>'

Using PPF variables in a text widget

PPF variables are useful when the same text is going to appear in numerous section of the report. Assigning this text to a variable will avoid repetition and make changes quicker if required.

The format is $$repvars.varname$$.

The example below will search the defined report variables for the name companycopyright and print the value of this variable to text.

text: '<p>Copyright $$repvars.companycopyright$$</p>'

Using PPF expressions in a text widget

PPF expressions allow text to change based on metrics or any other report specific criteria. Expressions in techincal terms are JavaScript functions. Take for example the text specified below.

text: '<p>The overall result of this test was a $$exp.speedexp(||speed.dspeed||,||speed.uspeed||,"custom text")$$</p>'

The format is $$exp.expname(parameters to pass)$$.

In the example above, an expression named speedexp is being requested. This expression takes three parameters. The first two are metrics, the third is just custom text.

It's important to note that when defining metrics within an expression the syntax is ||, instead of $$, which is used elsewhere for metrics.

For a more detailed example see the page on PPF expressions.