Cognition Tag Reference

Note that attributes with an asterisk (*) are required.

Possible data types for attributes are listed in brackets [ ] with the default type in italics.

library (vs require) command net pump (vs write) adapter relay?

Adapter

The adapter tag acts like a data tag that has been dynamically wired to another data tag above it in the component tree. The control attribute determines the direction of the binding. If set to control, any writes made to the local adapter will be automatically relayed to the higher data tag. If not in control, the adapter will watch the higher data tag, mirroring its value.

The basic idea is that you can provide the name of an external data tag via configuration while the code in your cog file works with local data tags to allow generic implementations.

Examples

<adapter name="records" />
<adapter name="display" field="buttonValue" />
<adapter name="action" field="buttonCmd" control="true" />
<adapter name="color" optional="true" />
<adapter name="list" field="recordSource" item="config" />

Attributes

name*

Name to reference. [string]

item

Name of the data tag holding the configuration object for the adapter. Defaults to the injected item (if present) from the ‘item’ attribute of the parent cog. [string]

field

Looks for this property on the configuration object, which should be the ‘name’ of a higher data tag to follow or control. Defaults to the value of the ‘name’ attribute. [string, read, prop, run]

control

Will forward all writes to a higher data tag (default is to subscribe and its mirror its value). [bool]

optional

Silently fails if no valid higher data tag is found when initialized. [string]

Alias

The alias tag provides a way to create references to specific URLs. Each of these can reference a parent alias via the path attribute in order to construct chained paths.

Although ‘../’ is supported as a convenience, this tag is designed to discourage its usage.

Other cognition tags with url or path attributes can use alias names as values to handle file path resolution.

Using alias tags, one can rearrange the directory structure of an existing application without modifying the underlying code.

By convention, the name attribute of an alias tag is always fully capitalized with underscores between words.

Examples

<alias name="LIBRARY_FILE" url="/public/js/library.js" />
<alias name="CONTENT_ROOT" url="/public/app/html"  />
<alias name="PAGES" path="CONTENT_ROOT" url="pages"  />
<alias name="CHART_PAGE" path="PAGES" url="charts.html" />
<alias name="CREDITS_PAGE" path="PAGES" url="credits.html" />

Attributes

name*

Name to reference. [string]

url*

Relative or absolute file path. [string]

path

Relative or absolute directory path, prepended to the url. Can be another alias defined previously. [string]

Alloy

The alloy tag adds additional blueprint and script functionality to (as if just above) the cog in which it is declared. Alloys can act as libraries or state machines and do not have a display declaration. They can be stacked within a cog, but they cannot be nested within other alloys.

The script contents of an alloy are exposed on the script of the declaring cog (using the alloy’s name attribute).

Examples

<alloy url="menuStateMachine.html" />
<alloy url="supplyChainFeed.html" path="APP_FEEDS" />

Attributes

name

Name to reference (for routes or to find data ‘in [name]’). [string]

url*

Relative file path, absolute file path or alias name. Resolves to file containing an alloy definition that implements script and/or blueprint declarations. Alloy files are like cog files without display declarations. [string]

path

Relative or absolute directory path, prepended to the url. Can be another alias defined previously. [string]

source

External data source for configuration. [data, prop, run, read]

item

Internal data source created within the alloy (using source). [data itemData, prop, run, read]

route

Indicates a namespace (named after the alloy) for data tags. [boolean]

Chain

Chains create arrays of cogs based on a common url.

They are mapped to the keys (or indices) of a source array of data via the source attribute.

Data is injected into each via child cog via the chain’s item attribute.

Other options can help to control how these cogs are layered and applied to the DOM.

Chain Tag Examples

<chain node="body" source="records" item="record" url="row.html" />
<chain node="holder" source="prop filters" item="prop filter" url="COMBO_BOX" />
<chain node="list" source="cats" path="LAYOUTS" url="list.html" key="cat_id" />
<chain node="blogroll" source="run getBloggers" url="blogger.html" />

Chain Tag Attributes

node*

Node in the display in which to put the chain. Matched against the id attribute of nodes in the display declaration. [string]

url*

Relative file path, absolute file path or alias name. Resolves to file containing a cog definition that implements a display declaration (and possibly script or blueprint declarations). [string, data, prop, run, read]

path

Relative or absolute directory path, prepended to the url. Can be another alias defined previously. [string]

source

External data source (must resolve to an array) for configuration. [data, prop, run, read]

item

Internal data source created within each cog of the chain (using source). [data itemData, prop, run, read]

name

Name to reference (for routes or to find data ‘in [name]’). [string]

route

Indicates a namespace (named after the chain) for data tags. [boolean]

key

A way to identify data elements that persist across source changes. An item’s index in the source array is used by default. An object property name or a method to compute a key (function(data) { … return key; } can be used as key values. [index, string, prop, run, read]

Cog

The cog tag embeds a visible cog component within the HTML display of the current cog, loading (lazy-style) into the DOM node referenced by its node attribute (which is matched against the id attribute of a node in the display DOM).

Each cog is constructed from a file containing a display tag and optional blueprint and script tags.

Cog Tag Examples

   <cog node="header" url="HEADER"  />
   <cog node="panel" path="core/components" url="panel.html" />
   <cog node="alert" url="../../indicators/alert.html" />
   <cog node="page" source="configData" path="PAGES"  url="data currentPage" />
   <cog node="status" source="run getStatus" item="prop status" url="status.html" />
   <cog node="footer" url="FOOTER"  />

Cog Tag Attributes

node*

Node in the display in which to put the cog. Matched against the id attribute of nodes in the display declaration. [string]

url*

Relative file path, absolute file path or alias name. Resolves to file containing a cog definition that implements a display declaration (and possibly script or blueprint declarations). [string, data, prop, run, read]

path

Relative or absolute directory path, prepended to the url. Can be another alias defined previously. [string]

source

External data source (must resolve to an array) for configuration. [data, prop, run, read]

item

Internal data source created within each cog of the chain (using source). [data itemData, prop, run, read]

name

Name to reference (for routes or to find data ‘in [name]’). [string]

route

Indicates a namespace (named after the cog) for data tags. [boolean]

Command

A command tag creates a data tag and an associated sensor tag that watches it via the trigger attribute.

The sensor’s trigger attribute and the data tag’s name attribute are both set to the command tag’s name. While the command tag can watch, need or gather associated data using standard sensor features, it will only be triggered by writes to its primary data tag.

Commands are a shorthand to explicitly label user actions in your application while restricting them to a single point of entry.

Command Tag Examples

<command name="addTurtle_cmd" gather="turtleName,turtleType" transform="toTurtle" emit="request" pip\
e="addTurtle_net" />
<command name="activeTab_cmd" pipe="activeTab" />

Command Tag Attributes

name*

Name to reference (must be locally unique). [string]

[All other attributes are listed under the Sensor Tag]

Data

The data tag creates a named storage point owned and governed by the cog in which it is declared.

Its name must be unique within the cog. The containing cog and its descendants can read, write and subscribe via sensor tags to the data contained within it.

Child cogs can reference/expose data tags above themselves by using the prop tag.

Parent cogs have no direct access to the data contained within their children by design.

If the route attribute is set, the initial value of a data tag can be set via the url used to load the the application.

Data Tag Examples

<data name="currentPage" route="true" />
<data name="furColor" value="red" prop="true" />
<data name="eyeColor" value="run determineEyeColor"  />
<data name="numArms" value="prop armCount" />
<data name="numLegs" value="num 4" />
<data name="isHungry" value="true" inherit="true" />
<data name="theWordTrue" value="string true" />

Data Tag Attributes

name*

Name to reference (must be locally unique). [string]

value

Value stored in the data tag. Defaults to undefined. [auto, read, prop, run, string, num, bool]

inherit

Overrides the initial value with the value of a data tag of the same name (if there is a match higher up the cog hierarchy). [bool]

route

Indicates that the data tag can be initialized via a route provided by the url. [boolean]

prop

(Deprecated: will soon be true by default) Exposes the data tag as a property in the cog’s script declaration. [bool]

Net

The net tag is a reusable network request and response feed paired with a data tag whose value is the last network response.

Net tags store response data on the data tag’s default ‘update’ topic.

They initiate requests by watching for writes on the ‘request’ topic (possibly containing request parameters). Additional request settings and parameters can be supplied as defaults via the service attribute.

The status of requests can be monitored by watching the ‘condition’ topic (possible values are ‘busy’, ‘done’ and ‘error’).

Note: As net tags imply external data sources, the data tag’s route attribute is not available to them.

Order of precedence for settings and parameters (highest to lowest):

1. Piped in on the request topic (overrides params)
2. In-line attributes (except service)
3. Service attribute

Net Tag Examples

<net name="currentUser" path="SVC_ROOT" url="getUser" />
<net name="updateFacility" url="UPDATE_FACILITY"  />
<net name="configSvc" service="run determineConfigSvc"  />
<net name="movies" url="/api/movies" verb="POST" params="prop dramaFilms/>

Net Tag Attributes

name*

Name to reference (must be locally unique). [string]

url

Relative file path, absolute file path or alias name. Resolves to a network api endpoint. [string]

path

Relative or absolute directory path, prepended to the url. Can be another alias defined previously. [string]

verb

HTTP Verb [string]

service

Configuration object for the request that can hold multiple default values such as url, path, verb, params, etc. [prop, read, run]

params

Configuration object for the request parameters, overriding any service settings. [prop, read, run]

request

Automatic request on instantiation [bool]

prop

(Deprecated: will soon be true by default) Exposes the data tag as a property in the cog’s script declaration. [bool]

Preload

The preload tag requires that a file be loaded before the cog containing its declaration is initialized. Preloaded files are simply stored in a cache containing their text context.

They are not executed and are not placed in the cog hierarchy.

Preload Tag Examples

<preload url="whiskers.js" />
<preload url="returnOfTheCats.html" path="CAT_COGS" />

Preload Tag Attributes

url*

Relative file path, absolute file path or alias name. Resolves to file containing a cog definition that implements a display declaration (and possibly script or blueprint declarations). [string, data, prop, run, read]

path

Relative or absolute directory path, prepended to the url. Can be another alias defined previously. [string]

Prop

The prop tag lets one reference tags in the script declaration so that they can be directly manipulated.

This is a hack or convenience feature as the framework should not ideally require its presence.

Prop Tag Examples

   <prop find="currentUser" />
   <prop find="temperature" is="data" where="last" />   
   <prop find="defaultStation" is="config" name="station" />
   <prop find="phoneNum" name="phNum" />
   <prop find="address2" optional="true" />

Prop Tag Attributes

Pump

(NOT YET IMPLEMENTED)

Require

The require tag mandates that a JavaScript file must be loaded and executed before the cog containing its declaration is initialized.

This tag is used to declare library dependencies for the entire application, but allows the load to be deferred until needed.

Require Tag Examples

<require url="paws.js" />
<require url="kittenPower.js" path="JS_LIB" />

Require Tag Attributes

url*

Relative file path, absolute file path or alias name. Resolves to a JavaScript file. [string]

path

Relative or absolute directory path, prepended to the url. Can be another alias defined previously. [string]

Sensor

Sensors are configurable subscriptions to data tags (or DOM nodes, indirectly).

They are configurable , acting as subscription instances that can gather, filter, transform and emit message data.Â

Using the ‘watch’ and/or ‘need’ attributes, sensors can monitor data locations by name. Sensors search for each data location in turn, checking the current cog and then walking up the cog hierarchy until a match is found. Note: the search pattern can be modified using the ‘where’ attribute.

With the ‘node’ attribute, a sensor can listen for DOM events on a node with a matching ‘id’ attribute in the cog’s display declaration. Specify the event (such as ‘click’ or ‘mouseup’) using the ‘on’ attribute.

Sensor Tag Examples

<sensor watch="records" run="render" />
<sensor watch="records, filters" run="render"  />
<sensor watch="dataService" on="error" pipe="errorAlert" />
<sensor watch="config" need="user" transform="toNextPage" pipe="activePage" />

Sensor Message Lifecycle

When a sensor tag receives a message, it goes through the following series of steps in order to process it.

1. Check Enabled: If the sensor has been deactivated (dropped), the message is silently aborted.
2. Gather: The values of any data locations to ‘gather’ are bundled into a hash of values by source name, augmenting the original message data.
3. Extract: A property plucked from the message (which then replaces the message).
4. Conform: A functor to modify or replace the incoming message (before change or filters are applied).
5. Change: If ‘change’ is true, the message will silently abort if it equals (===) the last message seen (at this point in the process).
6. Filter: If present, a filter function is called with arguments (message, topic, source) and will continue if true is returned.
7. Batch and Group: If ‘batch’ or ‘group’ attributes are defined, the sensor will begin bundling messages in a list or hash, respectively.
8. Transform: The ‘transform’ attribute acts as a functor to modify or replace the outgoing message.
9. Emit: The ‘emit’ attribute acts as a functor to modify or replace the outgoing topic.
10. Queue: The message is either sent directly or queued for delivery on flush (invoked manually or by the next cycle of the event loop).
11. Cmd: If the sensor was generated by a command tag, it will not fire until a message from the command data tag has occurred.

Sensor Tag Attributes

Input Related

watch (1)

A list of names referring to named data tags that the sensor will subscribe to. If multiple names are listed, the underlying bus will automatically merge and batch them. Anything listed in the ‘need’ attribute is added to the watch list as a union of the two (distinct by tag, i.e. no duplicate subscriptions). [string (comma delimited)]

need (1)

The ‘need’ attribute subscribes to data tags just like the ‘watch’ attribute, but prevents the sensor from firing (via ‘run’ or ‘pipe’) until it has received data from every listed tag. [string (comma delimited)]

node (1)

Finds a node by id in the cog’s display declaration and listens for the event specified by the ‘on’ attribute. Use the ‘node’ attribute in lieu of the ‘watch’ and ‘need’ attributes. The message passed via run or pipe will be the associated event object. [string]

on

If the sensor is watching data tags using ‘watch’ and/or ‘need’, the ‘on’ attribute specifies a topic on the data tag. Generally, the default setting of ‘update’ should suffice. Use ‘*’ (wildcard) to subscribe to all topics on the data tag at once.

For sensors using the ‘node’ attribute, ‘on’ should be set to a DOM event name, such as ‘click’ or ‘mouseover’. [string]

optional

Makes subscriptions optional such that missing data tags in the ‘watch’ or ‘need’ attributes will simply be ignored (as opposed to throwing errors). [bool]

where

Where to search for data tag name(s) used by ‘need’, ‘watch’ or ‘gather’. [first, parent, outer, last, in (cog or alloy name)]

‘first’

looks locally and goes up the cog tree, returning the first match.

‘parent’

like ‘first’ but skips the current cog.

‘outer’

returns the second match found.

‘last’

returns the highest, final match in the cog hierarchy.

‘in (name)’

finds with ‘first’ cog or alloy with a matching name and returns a matching data tag within it

conform

Name of the function (in the script declaration) used to modify the incoming message. Note that this runs after ‘gather’ and ‘extract’ attribute operations. The function should accept three arguments: message, topic and source and runs with ‘this’ set to the script instance. It should return the new message value. [string]

filter

Name of the function (in the script declaration) to use as a filter against the message. Note that this runs after ‘gather’, ‘extract’ and ‘conform’ attribute operations. The function should accept three arguments: message, topic and source and runs with ‘this’ set to the script instance. It should return true in order to continue processing the data. If the filter method returns false, the incoming data will be silently ignored. [string]

Output Related

to

Where to search for the data tag name used by ‘pipe’. See ‘where’ for option info. [first, parent, outer, last, in (cog or alloy name)]

pipe (2)

When the sensor fires, writes to the data tag found with the name specified by ‘pipe’ (and using the ‘to’ attribute). [string]

run (2)

Name of the function (in the script declaration) to run as an output or side effect when the sensor fires. The function should accept three arguments: message, topic and source and runs with ‘this’ set to the script instance. The message argument contains the data being transferred and is typically the only argument needed. [string]

toggle (2) (deprecated: this feature will move to the data tag in the future).

Name of the data tag to toggle (as a boolean) when the sensor fires.

transform

Name of the function (in the script declaration) used to modify the outgoing message. The function should accept three arguments: message, topic and source and runs with ‘this’ set to the script instance. It should return the new message value. [string]

emit

Name of the function (in the script declaration) used to modify the outgoing topic. The function should accept three arguments: message, topic and source and runs with ‘this’ set to the script instance. It should return the new topic value. [string]

once

Fires only once. [bool]

change

Files only if the incoming message value (after ‘conform’) has changed. [bool]

keep

If ‘batch’ is true, the sensor keeps an internal history of messages received that it will process when the bus flushes. By default, it will pass along the ‘last’ message received when it fires. It can also pass the ‘first’ message seen, or even an array containing ‘all’ messages received between flushes. [last, first, all]

batch

When data is received, the sensor will note it but not fire until the bus is flushed (which occurs via requestAnimationFrame). Data stored is based on the ‘keep’ attribute. Sensors watching multiple data tags ‘batch’ automatically. [bool]

group

When data is received, the sensor will note it but not fire until the bus is flushed (which occurs via requestAnimationFrame). Sensors watching multiple data tags ‘group’ automatically, outputting a message object keyed by data tag (source) name. [bool]

1) All sensors require something to watch (some input source), be it a DOM ‘node’ or data tag(s). 2) All sensors should produce an output; they can ‘run’ a method defined in their cog’s script declaration or ‘pipe’ messages to another data tag.

Valve

The valve tag lets one sandbox portions of the cog hierarchy. It provides a communications ‘white-list’ such that descendant cogs cannot access alias or data tags that exist at the valve’s level and above. It does not apply restrictions to the cog in which it is declared.

A single valve can specify one or more permitted names and a single tag type. Multiple valves can be placed within a single cog, resulting in a white-list consisting of their union. Tag types without any associated valves can be accessed without restriction.

Valve Tag Examples

   <valve allow="currentUser" />
   <valve allow="cmdAdd, cmdView, cmdUpdate" is="data" />
   <valve allow="ENVIRONMENT_PATH" is="alias" />
   <valve allow="settings,user" is="config" />

Valve Tag Attributes