> My Space, My Voice ***: Extending and Developing Cartridges in Endeca 11.x

In this post I have tried to explore Cartridges and Endeca Assembler Application by examining how they work together in a "Hello World" example cartridge.

So without any further delays let’s first understand what is cartridge , cartridge template , cartridge handlers and the structure of a cartridge before making our own custom Cartridges. Further we will also take a close look at Endeca assembler application to understand what it does under the hood.

Cartridges and Cartridge Templates –

A cartridge is a content item with a specific role in your application; for example, a cartridge can map to a GUI component in the front-end application. The Assembler includes a number of cartridges that map to typical

GUI components – for example, a Breadcrumbs cartridge, a Search Box cartridge, and a Results List cartridge.

You can create other cartridges that map to other GUI components expected by your business users.

Every cartridge is defined by a template. A cartridge template defines:

· The structure and initial configuration for a content item.

· A set of configurable properties and the associated editors with which the business user can configure them.

Experience Manager instantiates each content item from its cartridge template. This includes any configuration

made by the business user, and results in a content item with instance configuration that is passed to the Assembler.

Cartridge Handlers -

A cartridge handler takes a content item as input, processes it, and returns a content item as output.

The input content item typically includes instance configuration, which consists of any properties specified by a business user using the Experience Manager or Rule Manager tool in Endeca Workbench. The content item

is typically initialized by layering configuration from other sources: your application may include default values, or URL parameters that represent end user selections in the front-end application.

A cartridge handler can optionally perform further processing, such as querying a search engine for data. When processing is finished, the handler returns a completed content item to the application.

Note: Not all cartridges require cartridge handlers. In the case of a content item with no associated cartridge handler, the Assembler returns the unmodified content item.

Cartridge structure -

The template contains two main sections: the <ContentItem> element and the <EditorPanel> element.

The content item is a core concept in Assembler applications that can represent both the configuration model for a cartridge and the response model that the Assembler returns to the client application. A content item is a map of properties, or key-value pairs. The <ContentItem> element in the template defines the prototypical content item and its properties, similar to a class or type definition.

In our example (explained below) template, we defined two string properties named message and messageColor and attached two simple string editors to those properties. The result looks like this in Experience Manager:

A brief note on Endeca Assembler Application -

The Endeca assembler application enables a WEB application to query the MDEX engine and retrieve the appropriate dynamic content based on user navigation state.

The assembler application provides a RESTful web service API that returns results either in JSON or XML format.

What happens at runtime?

The business user creates and configures instances of cartridges in Experience Manager based on a template. During cartridge development you need to create at least one instance of a cartridge for testing.

The Assembler retrieves this configuration at runtime and uses it to build the response model that it returns to the client application.

For any given cartridge, the default behavior is for the Assembler to do no processing on the configuration and simply return the configuration content item as a map of properties. That is, the response object is the same as the configuration object unless specific processing logic is defined in the Assembler for that cartridge.

Cartridge creation workflow –

The high-level workflow for creating a basic cartridge is:

1. Create a cartridge template and upload it to Endeca Workbench.

2. Use Experience Manager to create and configure an instance of the cartridge.

3. Add a renderer to the front-end application.

Step 2 is necessary during development in order to have a cartridge instance with which to test. However, once the cartridge is complete, the business user is typically responsible for creating and maintaining cartridge instances in Experience Manager.

In the below sections, we'll see each of these elements of the cartridge in detail.

Hello World cartridge example –

Here we will define a new cartridge and use Workbench to configure it to appear on a page.

Follow these steps to create and configure a basic "Hello World" cartridge.

1. Navigate to the templates directory of your application (Discovery in our case), and create a subdirectory named "HelloWorld." This directory name is the template ID for your template.

For example: D:\Endeca\apps\Discover\config\import\templates\HelloWorld

2. Create a cartridge template - copy the following into the contents of the file.

Save the file with the name template.xml in the HelloWorld directory which we just created in point 1 above.

<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008"

xmlns:editors="editors" type="SecondaryContent">

<Description>A sample cartridge that can display a simple message.</Description>

<ThumbnailUrl>/ifcr/tools/xmgr/img/template_thumbnails/sidebar_content.jpg</ThumbnailUrl>

<Name>Hello cartridge</Name>

</Property>

</Property>

</ContentItem>

<editors:StringEditor propertyName="message" label="Message"/>

<editors:StringEditor propertyName="messageColor"

label="Color"/>

</BasicContentItemEditor>

</EditorPanel>

</ContentTemplate>

3.   Upload the template to Endeca Workbench –
·  Open a command prompt and navigate to the control directory of your deployed application, for example, D:\Endeca\apps\Discover\control
·  Run the set_templates command

4. Add the cartridge to a page –

· Open Endeca Workbench in a Web browser.

The default URL for Workbench is http://localhost:8006. The default Username is admin and the default Password is admin

· From the launch page, select Experience Manager

· In the tree on the left, select Search and Navigation Pages under the Content section, then select the Default Page

· In the Edit Pane on the right, select the right column section from the Content Tree in the bottom left

· Click Add.

The cartridge selector dialog displays

· Select the HelloWorld cartridge and click OK

· Select the new Hello cartridge from the Content Tree on the left and configure it as shown

· Click Save Changes in the upper right of the page.

5. Try to view the cartridge in the Discover Electronics application.

In a Web browser, navigate to http://localhost:8006/discover-authoring/

The error displays because we have not yet created a renderer for the Hello cartridge.

Scroll down to the bottom of the page and click the json link to view the serialized Assembler response model that represents the current page.

Oracle recommends that you use a browser or install a plugin that supports native JSON display.

Otherwise, you can download the JSON response as a file.

Alternatively, you can click the xml link to view the same response in XML. In this article, we use the

JSON format when examining the Assembler response.

The following shows the JSON representation of the page with most of the tree collapsed, highlighting the data for the cartridge that we just added.

{

"@type": "ResultsPageSlot",

"name": "Browse Page",

"contentCollection": "Search And Navigation Pages",

"ruleLimit": "1",

"contents": [

{

"@type": "ThreeColumnNavigationPage",

"name": "Default Page",

"title": "Discover Electronics",

"metaKeywords": "camera cameras electronics",

"metaDescription": "Endeca eBusiness reference application.",

"links": [ ],

"header": [ ... ],

"leftColumn": [ ... ],

"main": [ ... ],

"rightColumn": [

{ ... },

{

"@type": "Hello",

"name": "Hello cartridge",

"message": "Hello",

"messageColor": "#FF0000"

}

]

}

...

}

In the next section, we'll create a simple renderer that displays the message based on the values configured in Experience Manager.

Adding a basic renderer -

While there is no one way to write rendering code for an application, in this example we'll write a simple JSP renderer for our basic cartridge.

To write a basic "Hello, World" renderer:

1. Create a new JSP page (Hello.jsp) and type or copy the following:

<%@page language="java" pageEncoding="UTF-8" contentType="text/html;charset=UTF-8"%>

<%@include file="/WEB-INF/views/include.jsp"%>

<div style="font-size: 150%;

color: ${component.messageColor}">${component.message}

</div>

2. Save the above renderer to

D:\Endeca\ToolsAndFrameworks\11.1.0\reference\discover-electronics-authoring\WEB-INF\views\desktop\Hello\Hello.jsp

(You need to create “Hello” folder)

3. Refresh the Discover Electronics authoring application at

http://localhost:8006/discover-authoring/ to see the end result :-)

In future posts I would love to explore Optimizing Application URLs and Integrating with the Sitemap Generator. All the above concepts and much more is covered in Endeca Assembler Application Developer's Guide.