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.

1. 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.
2. 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
3. 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.
4. 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.
5. 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

1. Create a new add-on
2. Give it a name
3. In the placement tab, check In Content
4. In the Inline Script tab, add this: return $cp->user->name
5. edit a page and place the add-on on the page
6. 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#