Creating Add-ons

An Add-on is a data record that contains all the elements necessary to create a feature for a Contensive website. These elements include html, images, javascript, styles, server-side scripting (Jscript, VBScript, php, etc) and others.

Add-ons are packaged and distributed in add-on collections. Collections are compressed files (zip format) that include an xml format collection installation file and all resource files required for the add-on. The collection installation file guides a sites installation of a group of features, which may include one or more add-ons, as well as database indexes, database table descriptions, database records, and others.

An example of an add-on is the 'webcast and podcast' Add-on. When installed, it adds a "webcase" tab to the edit screen for each page. Upload a media file in that tab and the page displays the file automatically. Download the RSS Feed Add-on and adding this page to the RSS feed will automatically include the necessary entries to make the media file a podcast.

How Add-ons Are Executed

An Add-on can be run several ways. You control this when editing the add-on in the "Placement" tab.

Dropped on a page: If an add-on is marked "Place on Page" or "Place on Template" it can be added to any page (or template) by any content manager through the wysiwyg editor. An example would be the Personalization Add-on. Administrators drop the add-on on a page and set it to First Name. When a visitor views the page, the add-on is replaced by it's output, in this case the visitor's first name.
Added to every page in several specific locations: Add-ons can be set to run on every page at the start of the body, end of the body, start of the content or end of the content. Add-ons triggered at the end of the body have programmatic access to all the body content so they can act as filters. An example of this is the tool-tip Add-on. It runs at the end of the body on every page. It reads in the complete body html and modifies it to include tools tips under certain conditions. It returns the modified body to the
As a remote method: If an add-on is marked as a remote method, it can be called remotely with it's name as the URL. A common example of a remote method add-on is the server-side work required for an ajax method, such as the method used to open folders in the admin navigator.
As a background process: Any add-on can be executed as a background process. In this case, it's output is discarded. An example of a process add-on is the Contensive Content Spider. Periodically, it is started as a background process. It opens an HTTP interface and fetches a page from the site. It processes the reply from the site to check for errors, and to index the content it finds. There is an example of a process addon in the Add-on Samples collection in the Collection Library. Every minute, it updates the admin site header name.
As a programmatic subroutine: Any add-on can be called by any other add-on. For instance, the Process Payment add-on can be called from the Shopping Cart Add-on, the MeetingSmart Add-on or any custom add-on that needs to process payments. To make sure the subroutine addon is installed, their should be an importcollection line in the calling collection.

Using Inline Scripts

Inline Scripts is a method of adding script programs in languages like php to add-ons. Inline scripts can be placed anywhere on the page, but are executed after the page is rendered by Contensive and returned to the webserver's scriting environment.

Simple Rules

Do not start and end with the script with the script's escape sequence, like <$PHP.
Use the return command to place a string where the add-on was placed.
You can use a function(), but it is not needed. If you include your code in a function, end the script with: return myFunction()
You can use any of the script language's context objects and functions, as well as the Contensive cp object.

Example

Create a new add-on
Give it a name
In the placement tab, check In Content
In the Inline Script tab, add this: return $cp->user->name
edit a page and place the add-on on the page
View the page and the add-on shows their name

Creating Add-on Elements

Add-ons are composed of several types of elements.

Add-on Element Types

Executable Element - When the add-on is executing, this code is run. These elements include active scripting like vbScript, inline scripts like PHP, referenced to Visual Studio dotnet classes and much more.

Content Elements - When the add-on is placed on a page or template, these elements are placed on the page.

The Form Element - An xml structure used to create simple settings pages. For instance, if your code uses a site property to display the administrator's name, you could save the name in a site property and use another add-on as a setting page that the site owners could easily access and modify the site property.

Create a DotNet C-sharp Windows Library Add-on

These instructions will walk you through the basic creation of an Add-on using Visual Studio .NET in C#.

1. Install Contensive on your Development Machine. See Installation and Setup for details.

2. Open Visual Studio and create a new C# Class Library project.

3. Open project properties, click Application and set the default namespace to HelloWorldAddon.

4. On the compile tab, click build events and paste this into Post-Build event (correcting paths as needed)

copy $(TargetDir)"*.dll" "C:\Program Files\kma\Contensive\Addons"

5. Add a reference to cpBase.dll -- usually found in c:\Program Files\kma\Contensive

6. Paste the following code into the created class file.

using System;

using System.Collections.Generic;

using System.Text;

using Contensive.BaseClasses;

namespace HelloWorldAddon

{

public class helloWorld : Contensive.BaseClasses.AddonBaseClass

{

//

// execute method is the only public

//

public override object Execute(Contensive.BaseClasses.CPBaseClass cp)

{

return "Hello World";

}

7. Build the DLL.

8. Go to your admin site and open the navigator to Navigator >> Manage Add-ons >> Advanced >> click on Add-ons

9. Click Add to create a new add-on. Set the following

Set the name to Hello World

Click the DLL tab and enter "Contensive.Addons.HelloWorldClass" in the Dot Net Class Full Name

Click the Placement tab and check the box "Place on Pages"

Click OK to save and close the record

10. Go to the public site and turn on Quick Edit.

11. Put the cursor anywhere in the wysiwyg editor and click the 'addons' drop-down menu. Select "Hello World" and a green add-on will appear in your content.

12. Click OK to close the editor and in it's place on the page will be "Hello World"

13. To deploy the new add-on on another server, see Deploying an Add-on Collection

Deploying an Add-on Collection

To deploy an add-on it must be rolled-up into an add-on Collection. A collection is a single zip file that contains all the resources for one or more add-ons. For this example we will first make a small add-on, then create the add-on collection for it.

To Create a simple Add-on

If you already have an add-on to deploy, skip this step

1. Log on to the admin site and open the navigator to Navigator >> Manage Addons >> Advanced >> click on Add-ons

2. Click Add to create a new add-on

3. Fill in the following

a. Set the name to Hello World

b. Set the HTML field to "Hello World"

c. Click the Placement tab and click "Place on Pages"

d. Click OK

4. Test Your add-on by editing any page and selecting it from the add-on menu. It will render as Hello World.

Create a Collection for your add-on

1. Log on to the admin site and open the navigator to Navigator >> Manage Addons >> Advanced >> click on Add-on Collections

2. Click Add to create a new Collection

3. Fill in the following

a. Set name to Hello World Collection

b. If your add-on has any files that need to be included, add them in the resources tab. For instance, if you created a DLL called helloWorld.dll, add "helloWorld.dll" in the executable file list. If your add-on(s) needs the image "myImage.jpg" in the images folder of your website, add "/images/myImage.jpg" to the www File List.

c. Click OK to save the collection.

4. Now go edit your add-on and select "Hello World Collection" for its collection.

Deploy the Collection

1. Use the Collection Manager to install the Collection Exporter if it is not already under Tools.

2. Open the Navigator to Tools >> Export Collection

3. Select your Hello World Collection and click OK.

4. Save the resulting .zip file

5. If you have created a Visual Studio Windows Library (DLL file), drag and drop it into the zip file as well.

Add-on Arguments

The Add-on Arguments are name/value pairs you configure in the features tab of the add-on record when it is created. Then content managers can modify the value when the add-on is used.

For instance, the "Page Content Review" add-on has two arguments, 'Review after this many days' and 'Rows per page'. They are entered in the Add-on record as follows:

Review after this many days=90

Rows per page=50

When a content manager drops this addon on a page, the default value shown are used. If they turn on advanced edit and click the options icon, they can modify these values.

Argument Syntax

The argument list is a list of name=value pairs, separated by carriage returns.

Name

can not contain a carriage return or an equal sign. See the list of escape codes below.

Value

The value can be a simple string or a Value-Constructor. A value-constructor is a sequence of instructions that sets up selection options for the content manager, and returns only the selected values to the add-on. See the list of escape codes below

Value-Constructors

Name=Default[OptionList]InputType

Name is a reserved option name that the Add-on recognizes. You program the Add-on by providing values for the name options.

Default is the default value used before the add-on options have been modified

OptionList is a list of available options in square brackets, each option is separated by a vertical bar character "|". For instance

My Value = C[A|B|C]

Creates a select box next to the caption "My Value", with the options A, B or C. By default, C is selected

InputType is the method of displaying the input or options. For example, checkbox or select. Currently, these are supported:

a. text

b. select

c. checkbox

d. radiobox

e. resourcelink

f. link

An Option can also be a function

Option Value Functions

To generate an OptionList from a database table, use the List( contentName ) and ListID( contentName ) functions in the option list

List( contentName, optional criteria )

The List function creates a list of names from a content table. The optional Criteria is an sql compatible criteria statement. When a selection is made, the name of the content record is returned.

For example:

GroupName=staff[List(groups)]

When a content manager drops this on a page and edits the options, this option string will produce a drop down selector with all the groups in the Groups content. By default, the group staff will be selected. When the administrator selects one of the groups, it will replace "staff" in the instance of the Add-on on the page.

ListID( contentName )

Returns a drop down select list of names from an database content. The optional Criteria is an sql compatible criteria statement. When a selection is made, the ID of the content record is returned.

GroupName=20[ListID(groups,optional criteria)]

When the administrator drops this on a page and double clicks on it, this option string will produce a drop down selector with all the groups in the Groups content. By default, the group with ID=20 will be selected. When the administrator selects one of the groups, its ID replace 30 in the instance of the Add-on on the page.

ListFields( contentName )

Returns a drop down select list of all the fields in a content definition (meta data for a table). When a selection is made, the name of the field is returned.

FieldName=email[ListFields(people)]

When the administrator drops this on a page and double clicks on it, this option string will produce a drop down selector with all the groups in the Groups content. By default, the group with ID=20 will be selected. When the administrator selects one of the groups, its ID replace 30 in the instance of the Add-on on the page.

Reserved characters

There are several characters the system uses to parse the option list. When used in an option value, they must be replaced with the following:

&	#0038#
=	#0061#
,	#0044#
"	#0034#
'	#0039#
	#0124#
[	#0091#
]	#0093#

Webservice Add-ons

A Webservice Add-on is an object that responds directly to a request at the website.

To create a Webservice, first create an Add-on and add it to the site with the Add-on Manager. In this example, I will call the Add-on "SampleAddon". The SampleAddon will simply respond with the Message "Hello World".

Upload the Add-on to the Add-on Manager, and hit your site with:

?webservice=SampleAddon

The site will respond with "Hello World".

Your add-on code can read any other arguments from the querystring or submitted form, and change its output accordingly.

Add-onScripts

Add-on scripts are add-ons that create a javascript tag on the page. The link should return a javascript that creates the desired content.

Add-on Replacements

Use the Add-on interface to create simple replacements in the content. When a content manage drops your add-on into his content and displays the page, you can include non-dynamic replacement HTML.

One common use for this replacement code is have Contensive add a 'marker' when the content manger drops the add-on. The when Contensive creates the page for display and returns it to your website script, you can programmically replace with something you create in the script.

For instance, you may create a function HelloWorld() in your php page. Then create an Add-on called "HellowWorld" that simply adds the HTML "Template:Helloworld" to the content when it is

Add-on ActiveX Objects

Add-ons can use objects in activeX DLLs to produce content. They are created by developers, then installed with the Add-on Manager. When created, content managers can easily add them into their content by selecting them from the Add-on drop down menu.

Unlike Scripts and Replacments, Add-on Objects are NOT supported in Contensive e-Mail.

Setting Page Add-ons

A Setting Page Add-on produces a page of settings only visible in the admin site. It is an XML application. For more information, see the Collection file construction section.

Add-on Collections

An Add-on Collection is a group of resources that provide a single common feature. Resources can be settings, functionality for your site, background processes, database settings, references to other collections, and just about any of feature requirement.

A properly configured Add-on Collection can be distributed to any site and provide everything necessary to add the feature.

The Collection can be a group of files, or it can be consolidated into a zip format.

The Contensive Add-on Manager is used to unpack and install the Collection. To install an Add-on Collection from the Contensive Library, click on the Add-on Library tab, and check the Collection you wish to install.

If you have an Add-on that does not come from the Library, go to the Manual Installation tab, and upload the file(s).

A Collection consists of several basic file types:

An XML configuration file is required
Optional ActiveX DLL program files
Optional resource files to be installed to the website's root directory
Optional resource files to be installed in the website's Content Files directory

Thee files can be uploaded separately, or compressed into a single zip file for installation.

Collection Resource Files

Resource files include any file that needs to be installed for an Add-on Collection. These may include images, css files, icons, ActiveX DLLs, etc.

Resource files that are simply installed in either the website's root folder or the Contensive content files do not need to be referenced in the Collection Configuration file. They will be installed by virtue of their presence.

To install a file in the website's root folder, upload it with the collection. If the file is to be installed in a subfolder of the webs root, like 'images' for instance, you must upload a zip file with the structure in place. Contensive will unzip the Collection, and duplicate the directory structure starting at the root folder of the website.

To install files in the Contnesive files folder, put your files in a subfolder called 'ContensiveFiles'. These files will be copied to the root of the Contensive files folder. These files may also include subfolders. To install Contensive files, your collection must be in zip format.

Collection Installation File

The Collection Installation file is an XML file that contains a description of features, settings, components and content to be imported. One configuration files is required for an Add-on Collection to install. A Collection Installation file is not needed to create a collection on your site, but if after creating it, you want to copy it to another site, an installation file is needed. There is an Add-on, Add-on Collection Export, which creates this file for you from your site's settings.

The top node for an addon collection is the 'Collection'.

</Collection>

Name is used to identify the collection in displayed lists. If the GUID is not present, name is used to locate a collection for upgrades.

guid is string used to uniquely identify the collection. To create a new guid, use the Create GUID tool from Advanced Tool menu in the navigator any Contensive site

system if yes or true, the collection can not be removed. It will be updated automatically from the Library.

updatable if yes or true, the collection can be updated from the Add-on Manager and automatically if the collection comes from the Collection Library. If false, updates will be blocked.

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.

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.
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" ?>

<FirstName>FirstValue</FirstName>

<SecondName>SecondValue</SecondName>

</nameValues>

Tabular Data

<?Contensive type="table" ?>

<cols>

</cols>

<row>

</row>

<row>

</row>

Presentation Data

Presentation Data is a feature to separate a function's data from its 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.

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
- 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 add-on 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> 
```
</layout>

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.

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 add-on is the processing instructions for the structured data saved in the HTML copy. When Contensive recognizes the output of an add-on 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.

Creating Add-ons

Contents

How Add-ons Are Executed

Using Inline Scripts

Creating Add-on Elements

Create a DotNet C-sharp Windows Library Add-on

Deploying an Add-on Collection

Add-on Arguments

Setting Page Add-ons

Add-on Collections

Add-on Return String

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Learning Center

Tools