A KRL program consists of one or more that comprise multiple rules. In addition to rules, rulesets contain other sections that are used to describe and configure the ruleset. This section describes ruleset structure.
Name
Every ruleset has a name which is an identifier. The name is referred to as the Ruleset ID or RID. When a KIX card is used to initiate the actions found in the ruleset, the RID is embedded in the card.
Meta Section
The meta section stores information about a ruleset. Meta sections are optional and may be empty. The following are allowed in a meta section:
description - a string (specified in standard or extended quotes) that describes the ruleset's purpose.
logging - accepted values are 'on' and 'off'. If logging is on for a ruleset, detailed log messages will be included as comments in the JavaScript output from KNS.
name - a string giving a human readable name for the ruleset.
author - a string giving the name of the author of the ruleset.
The following will be supported in the meta section at a future date:
modified - a string indicating when the ruleset was last modified.
version - the version number for the ruleset.
This data from the meta section is returned when the "describe" method is invoked in the Ruleset KNS API.
Keys
KNS has the ability to tie your ruleset to other services like Errorstack. For services that need developer or API keys, those are placed in the meta section of the ruleset.
Errorstack
To enable ErrorStack reporting of errors from your ruleset, place your ErrorStack developer key into the ruleset like so:
key errorstack "developer_key_goes_here"
Dispatch Section
Dispatch sections are used to route a ruleset evaluation to another ruleset based on specific criteria. Dispatching allows one ruleset to be used as the master ruleset in a ruleset collection. Doing so makes rulesets shorter. Shorter rulesets are easier to read and perform better.
If none of the dispatch criteria are met, the rules in the ruleset (if any) are evaluated.
The following types are available:
domain match - when the caller domain matches the given string, the target ruleset for the dispatch is evaluated instead of the current ruleset.
The following example shows a dispatch section with three domain match dispatches.
The global section allows the programmer to create definitions that will be used throughout the ruleset. Global definitions can emit JavaScript and desclare datasets.
CSS
The global declaration can contain one or more css statements that will add a <style/> element at the end of the header. The style element will contain anything inside the css statement. The css statement is followed by a string or extended quote that gives the new CSS.
The following example would change the global value for anchor links on the page:
global {
css <<
a:link {color:#FF9}
>>;
}
Note that CSS is a global and will be injected on the page whether or not a rule is selected in the ruleset. This is subject to change as we get more experience with CSS and KRL.
Global Emits
A global JavaScript emit can be used to declare JavaScript variables and functions for later user by all rules in the ruleset as shown here:
global {
emit <<
var pagename = 'foobar';
>>;
emit <<
var pagename2 = 'fizzle';
>>
}
This is equivalent to
global {
emit <<
var pagename = 'foobar';
var pagename2 = 'fizzle';
>>
}
Datasets
Global declarations can declare a dataset for use in the rules of the program.
Dataset declarations are preceded by the keywork dataset and contain a name and URL separated by the < symbol.
An optional caching specification can added after the URL. If a caching specification is not given the data is assumed to not be cachable. The caching specification consists of the keyword cachable followed by an optional time period specified as
for <num> <period>
where <period> can be seconds, minutes, hours, days, or weeks. If the time period is not specified, the caching period defaults to 24 hours.
The following shows examples of dataset declarations.
global {
dataset public_timeline <- "http://twitter.com/statuses/public_timeline.json";
dataset cached_timeline <- "http://twitter.com/statuses/public_timeline.json" cachable;
dataset other_data <- "http://example.com/foo.json" cachable for 3 hours;
}
Notes on Usage
A dataset declaration defines variables with the data in both the KRL ruleset and in the Javascript that will be run on the browser.
The data is assumed to be JSON and is parsed on the server. If that fails for any reason, the data will be returned as a single string.
The data is retrieved and cached on the server, not directly from the data source in the browser.
To avoid server overload, a minimum caching period (currently 20 minutes) is imposed on all remote data sources. Specifying caching periods shorter than the minimum will have no effect.
Large datasets with short caching periods can cause significant load on the user's browser as these must be downloaded frequently and may cause performance problems for your ruleset.
Multiple dataset specification can cause performance problems.
Datasources
Datasource are like datasets in that they are a way of accessing remote data, but they are queried when needed rather than loaded all at once as datasets are. Like data sets, data sources are declared in the globla declaration section like so:
global {
datasource library_search <- "http://test.azigo.com:9083/solr/select/?wt=json";
}
Ruleset Structure
A KRL program consists of one or more that comprise multiple rules. In addition to rules, rulesets contain other sections that are used to describe and configure the ruleset. This section describes ruleset structure.
Name
Every ruleset has a name which is an identifier. The name is referred to as the Ruleset ID or RID. When a KIX card is used to initiate the actions found in the ruleset, the RID is embedded in the card.
Meta Section
The meta section stores information about a ruleset. Meta sections are optional and may be empty. The following are allowed in a meta section:
The following will be supported in the meta section at a future date:
This data from the meta section is returned when the "describe" method is invoked in the Ruleset KNS API.
Keys
KNS has the ability to tie your ruleset to other services like Errorstack. For services that need developer or API keys, those are placed in the meta section of the ruleset.
Errorstack
To enable ErrorStack reporting of errors from your ruleset, place your ErrorStack developer key into the ruleset like so:
Dispatch Section
Dispatch sections are used to route a ruleset evaluation to another ruleset based on specific criteria. Dispatching allows one ruleset to be used as the master ruleset in a ruleset collection. Doing so makes rulesets shorter. Shorter rulesets are easier to read and perform better.
If none of the dispatch criteria are met, the rules in the ruleset (if any) are evaluated.
The following types are available:
The following example shows a dispatch section with three domain match dispatches.
dispatch { domain "www.google.com" -> "966337974"; domain "google.com" -> "966337974"; domain "www.circuitcity.com" -> "966337982"; }Global Declarations
The global section allows the programmer to create definitions that will be used throughout the ruleset. Global definitions can emit JavaScript and desclare datasets.
CSS
The global declaration can contain one or more
cssstatements that will add a<style/>element at the end of the header. The style element will contain anything inside thecssstatement. Thecssstatement is followed by a string or extended quote that gives the new CSS.The following example would change the global value for anchor links on the page:
global { css << a:link {color:#FF9} >>; }Note that CSS is a global and will be injected on the page whether or not a rule is selected in the ruleset. This is subject to change as we get more experience with CSS and KRL.
Global Emits
A global JavaScript emit can be used to declare JavaScript variables and functions for later user by all rules in the ruleset as shown here:
global { emit << var pagename = 'foobar'; >>; emit << var pagename2 = 'fizzle'; >> }This is equivalent to
global { emit << var pagename = 'foobar'; var pagename2 = 'fizzle'; >> }Datasets
Global declarations can declare a dataset for use in the rules of the program.
Dataset declarations are preceded by the keywork dataset and contain a name and URL separated by the < symbol.
An optional caching specification can added after the URL. If a caching specification is not given the data is assumed to not be cachable. The caching specification consists of the keyword cachable followed by an optional time period specified as
where <period> can be seconds, minutes, hours, days, or weeks. If the time period is not specified, the caching period defaults to 24 hours.
The following shows examples of dataset declarations.
global { dataset public_timeline <- "http://twitter.com/statuses/public_timeline.json"; dataset cached_timeline <- "http://twitter.com/statuses/public_timeline.json" cachable; dataset other_data <- "http://example.com/foo.json" cachable for 3 hours; }Notes on Usage
Datasources
Datasource are like datasets in that they are a way of accessing remote data, but they are queried when needed rather than loaded all at once as datasets are. Like data sets, data sources are declared in the globla declaration section like so:
global { datasource library_search <- "http://test.azigo.com:9083/solr/select/?wt=json"; }Later, a data source can be queried as a user defined datasource in the pre section of any rule in the ruleset.
Data sources use the same syntax for specifying cachability as data sets.
global { datasource library_search <- "http://test.azigo.com:9083/solr/select/?wt=son" cachable for 3 hours; }Rules
Following the preceding sections, the rulset can contain as many rules as necessary to create the application.