Recover Your Password

Return to Product Support > Learning Center > Developer References > Creating Add-ons > Add-on Return String

Add-on Return String

An Add-on may return data when it is executed. Generally, this data is a text string result that will be output on the page. The data, however can be in one of two forms, Structured and Unstructured.
  1. Unstructured Data - any type of text string not recognized by Contensive. An add-on dropped on a page is replaced by it's return string when the page is viewed. Unstructured data can be anything such as a simple text string or an XML document that does not have as it's top node a Contensive recognized tagname.
  2. Structured Data - Structured data returns meta data to a calling process in XML format. This type of data is not generally used to produce output on a page. Contensive structured data must begin with a <?Contensive type="datatype" ?> processing instruction. The default data type is "namevalues".

Structured Data Types

Simple Name Value pairs

<?Contensive type="namevalues" ?>

Tabular Data

<?Contensive type="table" ?>
<col name="Column1Name" caption="Column1Caption" align="Column1Alignment"/>
<col name="Column2Name" caption="Column2Caption" align="Column2Alignment"/>
<cell>row1 col1 data</cell>
<cell>row1 col2 data</cell>
<cell>row2 col1 data</cell>
<cell>row2 col2 data</cell>

Presentation Data

Presentation Data is a feature to separate a function's data from it's layout. A features data is typically the data managed by the content manager and may come from a database. The layout is the html and styles typically produced and controlled by the designer. Using presentation data, the designer can create a sample layout using greeked type and images for position only. The add-on then produces structured data containing the data and instructions for Contensive to manipulate and display the layout.

Presentation data is an xml document starting with the Processing Instruction:

<?Contensive type="presentation" ?>

Processing instructions always act on a single layout. The initial layout must be specified before any other processing can take place. The initial layout is started with a layout node containing a layout name.

<layout load="initialLayoutNameOrGuid" source="outerHTMLSelectorForSource" destination="innerHTMLSelectorForDestination">(instructions to process the layout)</layout>

  • defines the current layout to be processed
  • load - When included, the name or guid value will be used to locate an Add-on Layout record. All instructions within this layout will pertain to this data.
  • destination - The id, class or tagname in css format within the current element where results of the processing instructions will be appended.
  • source - When included, this is the id, class or tagname in css format which locates an HTML element inside the current layout on which to restrict the instructions contained within this layout.

<text destination="dstCssSelector">value</text>

  • replaces the innHTML of a node specified by the destination with the value specified
  • destination - the id, class or tagname in css format within the current layout where the value will be appended. The value will be placed in the innerHTML of the node specified.

<addclass destination="dstCssSelector">classname</addclass>

  • adds a class attribute to the html node specified by the destination
  • destination - the id, class or tagname in css format within the current layout where the class will be added.

<setid destination="dstCssSelector">idname</addclass>

  • sets the id attribute to the html node specified by the destination
  • destination - the id, class or tagname in css format within the current layout where the class will be added.

<item forgroups="groupIDCommaList">

  • used to create lists from a single layout source. each time an item node appears, a new copy of the source layout will be used and it's result will be appended with other item nodes in the layout. For instance, to populate a <UL> list, create a layout node with it's destination set to the UL tag, and it's source set to a sample LI within the UL. Then for each LI you want to produce, add an item node within the layout node. In each item node, specify the processing required such as a text instruction. The result will be to remove all the LI tags from the UL tag in the sample layout, and append a series of LI tags modeled after the first tag, individually modified by each item node.
  • forgroups - if present, this item will be blocked so only those users in the groups listed will get the item's content. This is a comma delimited list of Group IDs.

This is a small example of how this works.

Hello World Add-on
An add-on record is created called "Hello World". 
The addon creates only the following XML structured data block.
It could do this within a dotnet DLL, activeXDLL, visual basic script,
etc. In this case, it will simply be pasted in the HTML copy.
<?Contensive type="presentation" ?>
<layout load="Hello World Sample Layout">
<text destination="#targetLocation">World World</text>

In the styles tab of the add-on, include the styles for this layout

.helloWorldContainer {width:400px;margin:0 auto;background-color:yellow;color:red;}

In the presentation tab of the addon, check "Use on Pages"

save the addon.

Create an Add-on Layout record. In this record, set the Add-on drop-down to "Hello World" and enter the following into the layout area.

<div id="targetLocation" class="helloWorldContainer"></div>

To test this add-on, Open the admin navigator to Manage Add-ons >> advanced >> Add-ons without Collections >> click on Hello World Add-on

The html output is "Hello World"

When Contensive processes the add-on it first executes the add-on itself. The only return from the addon is the processing instructions for the structured data saved in the HTML copy. When Contensive recognizes the output of an addon as structured data, the data is processed instead of returned. This data is processed as follows:

<?Contensive type="presentation" ?>

Tells Contensive this is valid structured data, and to process it as a presentation.

<layout load="Hello World Sample Layout">

Causes the Add-on Layout record with the name "Hello World Sample Layout" to be loaded as the current layout and all instructions within this layout tag will use this layout.

<text dst="#targetLocation">Hello World</text>

Causes Contensive to find the node in the current layout with id="targetLocation" and replace it's innerHTML with Hello World.

The resulting layout is returned from Contensive for display.