You are on page 1of 167

Developer’s Guide

How to Develop a Communiqué Solution

  • 1 PURPOSE

5

  • 2 CONTENT

6

2.1

The Page Hierarchy

6

2.2

Page Content

6

2.3

The Content Storage Definition (CSD)

7

2.4

ObjectClasses

9

2.5

Repository Structure

10

2.6

Web Site Content

10

2.7

Restrictions

11

  • 3 APPLICATIONS

12

3.1

Application Structure

12

3.2

Content Structure

13

  • 4 TEMPLATES

15

4.1

Creating the Template

15

4.1.1

Creating the Template Definition File

15

4.1.2

Editing a Template Definition File

20

4.1.3

Understanding the Template Structure

22

4.1.4

Re-Using Template Files

23

4.1.5

Testing the Template

25

4.2

Writing the Layout

27

4.2.1

Hello World

28

4.2.2

HTML Code

29

4.2.3

Dynamic Information

30

4.2.4

Pictures

31

4.2.5

Adding a Secondary Layout

34

4.2.6

More Information

38

4.3

Increasing Productivity for Authors

40

4.3.1

Restricting the Scope of the Template

40

4.3.2

Providing a Preview Image

41

4.3.3

Specifying an Explicit Sort Order

42

4.3.4

Providing Individual Icons for the Template

43

  • 5 COMPONENTS

44

5.1

Creating a Component

44

5.1.1

Setting Up a New Component

45

5.1.2

Extending an Existing Component

46

5.2

Writing the Component Script

47

5.2.1

Creating the Script File

48

5.2.2

Adding the Script to the Component

48

5.2.3

Testing the Component

49

5.3

Adding Content

50

5.3.1

Specifying the Content Structure

50

5.3.2

Adding the Content Dialog

53

5.3.3

Accessing the Content

60

5.3.4

Displaying Pictures

61

5.4

Using a Component in a Template

65

5.4.1

Adding a Component to a Template

66

5.4.2

Editing the Component Content

67

5.4.3

Configuring a Component

68

5.4.4

More Information

70

5.5

Using the Paragraph System

71

5.5.1

Adding the Paragraph System to a Template

71

5.5.2

Configuring the Paragraph System

72

5.5.3

Using your own Components in a Paragraph System

73

5.5.4

More Information

74

5.5.5

Alternatives to a Paragraph System

76

5.5.6

Editing the Component Definition

76

  • 6 SCRIPTS

80

6.1

Java Server Page (JSP) Scripts

80

6.1.1

Using Java Classes

81

6.1.2

Accessing the Repository

81

6.1.3

Debugging

82

6.1.4

HTML/JSP Code

84

6.2

Server-side JavaScript (ECMAScript or ESP)

84

6.3

Servlets

85

6.4

Java Classes

85

6.4.1

Adding a Java Library to an Application

85

6.4.2

Adding a Java Class to an Application

86

6.4.3

Adding a Java Class to a Library

86

6.4.4

Adding a Java Class to the Servlet Container

86

6.5

Using the JSR-170 API

87

6.5.1

Development Concepts

87

6.5.2

Limitations

87

6.5.3

Accessing CRX

87

6.5.4

Mapping a Virtual Workspace

88

6.5.5

Example Component

88

  • 7 DESIGNS

89

7.1

Understanding Designs

89

7.2

Design

89

7.2.1

The Design Page

89

7.2.2

The Designer Object Class

89

7.2.3

The Design Class

91

7.2.4

The HtmlDesigner Object

92

7.3

Style

92

7.3.1

The Style Class

92

7.3.2

The StyleValues Class

92

7.4

Inheritance

93

7.5

Creating a New Design

93

7.6

Editing a Design

95

  • 8 LOCALIZING

98

8.1

Web Site Content

98

8.1.1

Copying the Web Site

99

8.1.2

Manually Copying Pages

100

8.1.3

Automatically Copying Pages

101

8.1.4

Translating Page Content

101

8.1.5

Tracking Updates

102

8.1.6

Multi-Stage Translation Setups

102

8.2

Web Site Tools

103

8.2.1

Localizing a Tool

103

8.2.2

Re-Using Tool Labels

108

8.2.3

Localizing Other Labels

108

8.2.4

Avoiding Extra Work

108

8.3

Applications

109

8.3.1

How Language Files Work

109

8.3.2

Creating the Language File(s)

115

8.3.3

Adding Labels

116

8.3.4

Templates

117

8.3.5

Components

120

8.3.6

Dictionaries

120

8.3.7

Localizing Code

121

8.3.8

Setting the Content Language

122

8.3.9

Adding a Language Switch

124

  • 8.3.10 Localizing the Authoring Environment

127

 
  • 8.3.11 The CFC Library

128

  • 8.3.12 Communiqué Modules

129

9.1

Performance and the Project Plan

131

  • 9.1.1 In the Concept Phase: Design for Speed

131

  • 9.1.2 During the Development Phase: Identify Issues Early

133

  • 9.1.3 Before Going Live: Test Thoroughly

133

  • 9.2 Improving Cache Performance

134

  • 9.2.1 The Dispatcher Cache

135

  • 9.2.2 The Communiqué Output Cache

137

  • 9.2.3 Cache-Aware Web Design

140

  • 9.3 Improving Search Performance

144

  • 9.3.1 How the Search Function Works

144

  • 9.3.2 When Search Breaks Down

144

  • 9.3.3 Increasing the Search Cache

144

  • 9.3.4 Do Not Rely on Filters

145

  • 9.3.5 Using Special Flag Values

145

  • 9.4 Measuring Performance

145

  • 9.4.1 What is Good Performance?

145

  • 9.4.2 Spot Checking with the Web Browser

146

  • 9.4.3 Analyzing the Request Log

147

  • 9.4.4 Using a Proxy Server to Track Communications

147

  • 9.4.5 Monitoring Communiqué’s Status

153

  • 9.4.6 Analyzing a Thread Dump

153

  • 9.4.7 Code Benchmarking

154

  • 9.4.8 Component Benchmarking

154

  • 9.4.9 Server Benchmarking

155

  • 9.4.10 Testing the Search Engine

156

  • 9.4.11 Expert Tools

159

10 CUSTOMIZING THE AUTHORING ENVIRONMENT

160

10.1 Customizing the Sidekick

160

  • 10.1.1 Switching the Sidekick On and Off

160

  • 10.1.2 Hiding Sidekick Options

161

  • 10.1.3 Adding Custom Options

163

1 Purpose

A Communiqué Web site is based on two building blocks:

Templates specify the layout of a Web page. For example, you can use one template for product pages and a second one for employee information.

Components are re-usable building blocks of the Web pages. You can use them to store content, or for functions like search and navigation.

Communiqué comes with a number of pre-defined components. One of these, the paragraph system component, allows you to add a flexible paragraph system to a page, so your authors can comfortably add and edit the paragraphs. These paragraphs are components as well. Communiqué comes with a number of pre- defined components for paragraphs such as:

A text paragraph for formatted text (you can define which properties an author can set).

An image paragraph for images with title and annotation.

Chart paragraphs for bar charts and line charts.

A table paragraph for tabular data.

2 Content

In Communiqué, everything is content. Communiqué treats the Web site content exactly as it treats script code, template definitions and configuration files. Communiqué stores content in the CRX repository (or in the ContentBus repository if you upgraded from a previous release).

2.1 The Page Hierarchy

The repository stores content in a page hierarchy. A page hierarchy can look as follows:

2 Content In Communiqué, everything is content. Communiqué treats the Web site content exactly as it

A page has the following properties:

It has a unique path in the repository, such as /products/televisions.

It can have other pages below it.

It can store content.

2.2 Page Content

A page contains structured content in the form of content elements. There are three types of content elements:

The atom stores one value, such as the text of a paragraph, the name of a template or the date of publication of a page.

The container stores a number of content elements. For example, you can store the title and the text of a paragraph in a container.

The container list provides a list of containers of the same type. Using a container list, you can use several text paragraphs on a page.

A page provides the interface between the page structure and the content structure:

A page provides the interface between the page structure and the content structure: 2.3 The Content

2.3 The Content Storage Definition (CSD)

The Content Storage Definition (CSD) defines the structure of the page content as a hierarchical list of content elements. It also specifies where and how Communiqué stores the content.

A CSD is written in XML, for example as follows:

<?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE csd SYSTEM "cq:/system/resources/dtd/xmlcsd.dtd"> <csd name="myCsd"> <hierarchy_driver name="default" /> <container> <atom label="title" driver="default" /> <containerlist label="section_A" driver="default" >

<atom label="paragraph_title" driver="default" /> <atom label="paragraph_body" driver="default" /> </containerlist > <containerlist label="section_B" driver="default" > <atom label="product_image" driver="blob_default" isBinary="true" /> </containerlist > <atom label="disclaimer" driver="default" /> </container> </csd>

name

The name of the CSD, here “myCSD”. Communiqué refers to the CSD using this name.

hierarchy

The driver that Communiqué uses to map the

driver

content hierarchy to the repository that stores the data. You can use the default driver for most standard applications.

container

The top level container. It contains the basic page information, such as the page title. Note that you must use a top level container that contains all of the other content elements.

atom

The atom that stores the page title.

containerlist

The container list section_A provides a number of paragraphs that each have a title and a paragraph body. Section_B allows you to store a number of product images.

driver

The driver that Communiqué uses to store the content in the repository. Use “blob_default” for binary date, “default” for text data. The default driver stores the content of several atoms in one file, while the blob_default driver stores its content in separate files, which is better for large files.

isBinary

This attribute tells Communiqué that the atom stores a binary file, and not text information. This information helps Communiqué to optimize the data management.

A page that has the CSD above allows you to store the following pieces of information:

A page title.

A number of text paragraphs that each have a title and a body.

A number of images.

The following JSP example script accesses this content using the ContentBus API (the example contains only the code that is relevant for this discussion):

import com.day.cq.contentbus.*;

(

...

)

// Load the page Page page = ticket.getPage("/products/televisions");

// Load the top content container

Container top = page.getContent();

// Read the title of the page Atom title = top.getAtom("title");

// Read the container list "section_A" ContainerList containerList = top.getContainerList("section_A");

// Read all the containers in the container list for (ContainerIterator i = containerList.containerIterator(); i.hasNext();) { Container container = i.nextContainer(); Atom parTitle = container.getAtom("paragraph_title"); Atom parBody = container.getAtom("paragraph_body");

}

2.4 ObjectClasses

You can define an object class to define the structure of a page, a container or a container list.

For example, a container of the object class user must contain two sub elements:

An atom named User

An atom named Password

Similarly, a page representing a template definition must contain atoms named:

Template

DefaultCSD

AllowedLocation

Description

and so on.

A container's object class is defined by the objectclass attribute as follows:

<?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE csd SYSTEM "cq:/system/resources/dtd/xmlcsd.dtd"> <csd name="genericfile"> <hierarchy_driver name="GenericMapper" />

<container objectclass="system">

<atom label="data" driver="GenericContent"

isBinary="true" /> </container> </csd>

In this example, the container belongs to the object class system. This means that this container must contain an atom called data.

On startup, the Communiqué validates all CSDs for object class correctness.

2.5 Repository Structure

Communiqué’s repository has the following structure:

/

This is the root folder of the repository.

access/

This folder contains the security information, such as users and groups.

apps/

Here, you can develop your applications. An application is a Communiqué development project, such as a Web site.

libs/

Communiqué’s internal script libraries. Do not modify the content of this folder.

content/

This folder stores the content of the Web site.

system/

This folder stores system information. Do not modify the content of this folder.

config/

Holds all Communiqué configuration files.

etc/

This folder contains extensions to Communiqué that are available in the Misc tab of the Communiqué Management System (CMS).

bootstrap/

This folder contains initial configuration information that Communiqué needs to start up.

2.6 Web Site Content

Communiqué stores the Web site content in the /content folder of the repository. The /content folder has the following structure:

Each application has a content folder in the repository that has the same name as the application.

Each content folder has one subfolder per language. The name of the subfolder is the ISO-code of the language.

For example, the design ground that comes with Communiqué is located in the folder /apps/designground. The content folder looks as follows:

Because the design ground is only available in English, it has only one language folder, “en”.

Because the design ground is only available in English, it has only one language folder, “en”.

2.7 Restrictions

Communiqué’s repository has the following restrictions:

Page labels can use the following characters: a-z, A-Z, 0-9, and the underscore. Valid page names are “en”, “myPage”, “products”, “article_1”.

Resource files can also use the dot and dash characters. Valid names for resource files are “Dialog.any”, “atoms.xml”, “sql-contrib.jar”.

Move and rename labels and file names only using Communiqué’s tools. You may corrupt Communiqué’s search database and the internal page hierarchy if you use external tools for this.

Note: Communiqué uses the first dot in a request to identify the script it executes. For example, the request “www.myCompany.com/home.print.html” executes the print script of the home page. If you use a dot in a page label or folder name, Communiqué cannot identify the script correctly, and does not display the page.

3 Applications

An application is Communiqué’s largest development block. It contains all the templates, components, scripts and designs for a Web site or a Web solution.

In Communiqué, an application is stored in one folder in the /apps folder of the repository. Note that the content of a Web site is not stored in the /apps folder, it is in the /content folder. This allows you to share the content between several applications.

3.1 Application Structure

Each application is stored in one subfolder of the /apps folder. The default folder structure looks as follows:

/apps

/myApplication

/docroot

/templates

/global

/myFirstTemplate

/mySecondTemplate

/Components

/myFirstComponent

/mySecondComponent

apps

This folder contains Communiqué’s applications. When you install Communiqué, it already contains several internal applications and two examples, the playground and the design ground. The playground offers a simple example, while the design ground offers the more comprehensive example.

myApplication

Your application folder.

docroot

This folder contains files that are displayed in the root folder of your Web server. For example, if you place the file “logo.gif” in this folder, Communiqué displays it under the URL “www.myCompany.com/logo.gif”.

templates

This folder contains the templates for your Web site. You need one template per type of page, such as a product page or an employee page. A template can have multiple layouts, such as an online and a print layout. Note that the name must be lower case to support localization.

templates/global

This folder contains the files you use for

 

multiple templates.

Components

This folder contains your components. Components are building blocks that you can use in templates. Examples are the navigation bar, the search function or the text paragraph. Because components are modular, you can re- use them in other applications. Communiqué comes with a number of components that you can use. Note that the name must be upper case to support localization.

Note: For application names, use only the characters a-z, A-Z, 0-9 and the underscore. Do not use the dot character.

3.2 Content Structure

The content structure follows the structure of your Web site. Proceed as follows:

  • 1. Create a folder for your application, for example myWebsite.

  • 2. Create a language folder for each language you plan to support, for example en and de. Use the ISO-code of the language as the folder name.

  • 3. Add a basic page structure that mirrors your Web site. Use the same labels for the same pages in each branch.

Your content structure now looks as follows (note that the pages in the German branch have the same English labels as the ones in the English branch).

/content /myWebsite /en /products /solutions /aboutus /de /products /solutions /aboutus
/content
/myWebsite
/en
/products
/solutions
/aboutus
/de
/products
/solutions
/aboutus

Note: Even if you currently support only one language, do use a language folder. Adding one after the content is created and the scripts are written may be much more difficult.

Communiqué offers several tools to support the language folders:

The multi-site manager allows you to manage the language folders and automatically add new pages and new content.

Using designs and custom scripts, you can store language- dependant information, such as the label of the search box, on the language page, and then access them from the entire language folder.

You can give authors specific access to the folders. So a German translator may have read access on the English pages and full access on the German ones.

Note: For page labels, use only the characters a-z, A-Z, 0-9 and the underscore. Do not use the dot character.

4 Templates

In Communiqué, a template specifies one type of page. For example, you may have a template for product pages, a second template for the sitemap, and a third one for contact information.

A template consists of a template definition file and a number of additional files that specify various aspects of the template, such as the type of content it can store. The template also contains script files, which specify how the template looks.

This section tells you first how to create the template definition, and then how to create the additional files and add them to your template definition.

Note: Do not use templates for special functions, such as search or navigation. For these functions, it is usually easier and more flexible to use a component, which you can then place on a template. Components also replace the so-called “HTML includer” that was used in previous Communiqué versions to use the output of one template as part of another template.

4.1 Creating the Template

You can use Communiqué’s template wizard to create the template file, the script framework and the default files for you.

Note: Before you begin, make sure that you have created an application folder in Communiqué’s apps folder, which contains a folder named docroot. In the following examples, the application folder is named “myApplication”.

4.1.1 Creating the Template Definition File

This section tells you how to create a new template definition file in the Communiqué development environment (CQDE). The template definition file specifies the template name, the template behavior, and which additional files the template uses. Proceed as follows:

  • 1. In the CQDE, click the Templates tab. A list of all the templates on the Web site is displayed.

  • 2. Right-click below the template list, and then click Create Template. The Communiqué Template Wizard opens. Click

Next to continue.

Next to continue. 3. In the top list, click the application folder where you want to
  • 3. In the top list, click the application folder where you want to create the template. In the middle field, type the name of the template. Do not use spaces, special characters or reserved Java words for the template name. Click Next to continue.

Next to continue. 3. In the top list, click the application folder where you want to
  • 4. Type a title and a description for your template. Click Next to continue.

Next to continue. 3. In the top list, click the application folder where you want to

5.

If this template extends an existing template, click the template in the list. If the template is completely new, leave the field empty. For the example, leave the field empty. Click Next to continue.

5. If this template extends an existing template, click the template in the list. If the
  • 6. If you are using an existing Content Storage Definition (CSD), click it in the list. To create a new CSD, click create new. Click Next to continue.

5. If this template extends an existing template, click the template in the list. If the
  • 7. Next, define the script type that you want to use for the template’s main script. You can use other script types for other scripts. By default, use Java Server Pages (JSP).

Click Next to continue.

Click Next to continue. 8. Leave the default script name. Click Install default template structure to
  • 8. Leave the default script name. Click Install default template structure to have Communiqué create the template structure for you (recommended). Click Next to continue.

Click Next to continue. 8. Leave the default script name. Click Install default template structure to
  • 9. “Script Globbing” is the technical term for the scope of the main template script. Leave the default of “*” to use the default script for everything (you can always change this

later). Click Next to continue.

later). Click Next to continue. 10. Type the scope of the template. Leave the default /content

10. Type the scope of the template. Leave the default /content to make the template available for the entire Web site.

later). Click Next to continue. 10. Type the scope of the template. Leave the default /content

11. On the summary page, click Next to create the new template. Then, click Finish to exit the Template Wizard.

later). Click Next to continue. 10. Type the scope of the template. Leave the default /content

Note: If you click Next on the last screen, the Advanced Template Wizard opens, which migrates an existing layout to the new template.

4.1.2 Editing a Template Definition File

To change all the aspects of the template (except for the name) after you have created it, right-click the template, and then click Edit Template Definition. The Edit Template window opens, and you can change the settings.

Note: If you click Next on the last screen, the Advanced Template Wizard opens, which migrates

The Edit Template window contains the following elements:

Name

The name of the template in the repository. You cannot change this name, because other files may refer to it to locate the template in the repository.

Title

The title of the template. This is also the official name of the template that authors see.

Internationalized

The label under which the title is stored in a

Title

separate language file.

Description

A description of your template. Use this to tell authors when to use this template.

Internationalized

The label under which the description is stored

Description

in a separate language file.

Base Template

If the template shares several settings with another template, specify the template here. Communiqué then takes any fields you leave empty in this template definition from the base template you have specified.

Default CSD

The Content Storage Definition (CSD) of the template. The template CSD is used for page properties, such as when a page was created, who last modified it and so on.

Component

The file that stores the component hierarchy for

Hierarchy

the template. This is an internal file that Communiqué uses to keep track of the components on the page and of their content. If you leave this field empty, Communiqué creates the file in the folder of the template and names it “componenthierarchy”.

Sort Key

The sort key for the template list. When an author receives a list of templates, Communiqué sorts the templates by the value of this field. This allows you to put the frequently used templates on top of the author’s list.

Thumbnail

The preview image used when an author selects

Image

the template from the template list.

Document Icon

If it is important for authors to tell the types of pages apart quickly, you can provide your own icons. The icon is used in the page list of the author’s site view. If you do not provide an icon, all pages are displayed with a neutral page icon.

Closed Folder

The icon that is used when the page is

Icon

displayed as a closed folder in the author’s site view.

Open Folder

The icon that is used when the page is

Icon

displayed as a open folder in the author’s site view.

Scripts

The scripts that display the page content. You need to specify at least one script (by default, “start.jsp”). You can use several scripts to

 

include different layouts or to display images and offer download files. Communiqué evaluates this list from top to bottom and uses the first script where the so-called “glob” matches the client’s request.

Allow Location

This list defines the scope of the template. Communiqué evaluates this list from top to bottom to determine whether the template is allowed or denied at the current location. If the current location is outside of the scope you have defined here, the template is not available.

4.1.3 Understanding the Template Structure

If you have asked Communiqué to create the template structure for you, you have a number of files in your template folder that allow you to create a powerful template and re-use code for other templates. If you do not have this structure, you can create it manually.

Also note that you have to create the folder /global manually. This folder stores template code that you use in several templates. You can re-use template code by moving it from your template into the /global folder. If the code is not available in the template folder, Communiqué looks in the /global folder.

include different layouts or to display images and offer download files. Communiqué evaluates this list from

Communiqué has created the following files:

start.jsp

The start script. Communiqué executes this script when a user requests a page that uses this template. The start script sets the paths and executes the script main.jsp. You cannot move this script into the /global folder.

main.jsp

The main script uses Communiqué’s tag library to display the <html> and </html> tag. The script executes the script head.jsp to display the HTML <head> tag, and body.jsp to display the HTML

 

<body> tag. Typically, you use the same main script for most or all templates, so you can move it into the /global folder.

head.jsp

This script writes the HTML <head> section, including meta information.

body.jsp

This script starts Communiqué’s body component, which displays the page body.

header.jsp

This script contains import and variable definition code. It is used in the scripts head.jsp and body.jsp. You can move this file into the /global folder, so you have the same variables and classes available in all scripts.

csd.xml

This file contains a basic content storage definition for the page.

If you create a new page with this template and open it in a browser, it looks as follows. As you can see, the page bar is already there (at the top), but there is no page content yet.

<body> tag. Typically, you use the same main script for most or all templates, so you

4.1.4 Re-Using Template Files

The default start.jsp script defines two locations for template files:

The current template folder and the folder /global. If a file is not available in the current template folder, Communiqué looks for it in the folder /global.

This means that you can place default files in the /global folder which are used in all templates. You can always override this file by placing a file with the same name in the template folder.

Typically, you can move the following files to the /global folder:

header.jsp: The header containing import statements and variable definitions for the files head.jsp and body.jsp. Usually, you can use the same header for all your templates.

head.jsp: The code that writes the HTML head section of your page. This code is usually the same for all pages.

main.jsp: This script creates the main HTML structure with a head and body section. This is usually the same for all pages.

To move a file to the /global folder, proceed as follows:

  • 1. Open the Communiqué Development Environment (CQDE).

  • 2. Click the Resources tab and open your template folder.

  • 3. Right-click the file you want to move, and then click Check Out. The file now has a red check mark next to it, and you can edit it.

  • 4. Right-click the file, and then click Move. The Move File window opens. Click the global folder, and then click OK. Communiqué now moves the file into the /global folder.

If you move the file header.jsp, you need to adapt the path in the file body.jsp. Because this file includes the file header.jsp, and because it uses JSP’s include mechanism (which does not respect Communiqué’s path settings), you have to adapt the file body.jsp as follows:

<%

//---------------------------------------------

// body.jsp

//---------------------------------------------

%><%@ include

%><%

Style actstyle = null; %>

...

If you move the files into the /global folder, the structure of your application folder looks as follows:

Note: When you use the template for the first time, Communiqué creates an additional file named

Note: When you use the template for the first time, Communiqué creates an additional file named componenthierarchy. This file keeps track of the components that are used on the template. You can usually ignore it. If you add, delete or modify components, you have to delete the file, so Communiqué can re-create it with the new information.

4.1.5 Testing the Template

Before you start developing the template code, test the template to make sure that it is available and works correctly.

To test the template, create a new page based on it, and then open the page in a browser. Proceed as follows:

  • 1. Log in to the Communiqué authoring environment.

  • 2. In the content structure list (left), click a page in the DesignGround/English branch of the example Web site.

  • 3. Click the New icon (blank page). The Create Page window opens.

  • 4. In the Title field, type the title of the new page.

  • 5. In the Template list, click the template you want to test. For the example, click My First Template.

  • 6. Click OK. Communiqué creates the new page based on the template.

  • 7. Click the newly created page to open it in a new browser window. For a new template, this is an empty screen with the Communiqué Sidekick on the left, and the Communiqué

toolbar at the top.

toolbar at the top. Checking Page Content If the template seems to handle information wrong, you

Checking Page Content

If the template seems to handle information wrong, you can use CQDE to find out exactly which information is stored on a page that uses the template. Proceed as follows:

  • 1. Open CQDE (the Communiqué Development Environment).

  • 2. Click the Site tab.

  • 3. Right-click a page that uses the template, and then click Edit Content. The Edit Content window opens and displays all groups and all non-empty fields.

  • 4. To see which empty fields are available, click Show All. Now you can see all the data that is stored on the page, and which the data you can additionally store.

toolbar at the top. Checking Page Content If the template seems to handle information wrong, you

Note: From the ContentBus tab, you can use this function on all Communiqué content, such as template definitions or script files. This offers a great way to learn how Communiqué stores data of all type.

Trouble Shooting

Problem

Solution

The template does not appear in the template list.

Make sure that you have set the Allow location correctly. To make the template available everywhere, set it to /content, Allow, click Add, and then click Apply. If you omit any of these steps, Communiqué ignores your input.

When I try to create a new page with the template, nothing happens.

When you create a new page, type a name for the page. If you leave the name field empty, Communiqué does not create the page.

The page uses an existing layout instead of a new, empty one.

Make sure that the template’s CSD (Content Storage Definition) is correct, and that the template uses the CSD you have intended. If the CSD is wrong or missing, Communiqué cannot correctly store which template the page is based on.

Communiqué reports an internal

Open the file body.jsp for editing, and make sure that the include path at the top

server error in the file body.jsp.

points to the file header.jsp. If the file is in the folder global, point the include

statement to “

..

I have corrected the source of a problem, but the symptoms do not disappear.

In CQDE, right-click the template folder, and then click Refresh. Delete the file componenthierarchy. This file stores the content structure of the template. Communiqué now re-creates the file with the information you have changed.

4.2 Writing the Layout

In Communiqué, you usually write the page layout as a JSP (Java Server Pages) script. This allows you to combine all aspects of a layout:

You can write the HTML code of the page.

You can use JSP code to access Communiqué’s functions, the page content, and page properties.

You can call JAVA classes that contain business logic.

You can add components, for example to display a navigation bar, or to allow authors to add Web site content.

With the standard template structure, the primary layout is stored in the file body.jsp. This file contains all the HTML code of the page body (without the <body> and </body> tags).

• You can add components , for example to display a navigation bar, or to allow

You can edit the file in CQDE or a third-party development environment. In CQDE, double-click the file to edit it.

4.2.1 Hello World

To display a hello world message, add the words “Hello World.” at the bottom of the standard body.jsp file, as follows:

<%

//------------------------------------------------

// body.jsp

//------------------------------------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

Hello World.

Note: If you have moved the file “header.jsp” into the folder “global”, remember to change the include path to

..

/global/header.jsp”

(as above).

If you now create a new page on the basis of this template, it displays the hello world message, as follows:

Note that this page alread y includes Communiqué’s page framework, so you have a toolbar at

Note that this page already includes Communiqué’s page framework, so you have a toolbar at the top of it, and you can edit page properties.

4.2.2 HTML Code

To use an HTML layout for a page, add the layout at the end of the file body.jsp. For now, use place holders where you want to have the navigation and content in the final layout. These areas are created using Communqué’s component framework (see below).

For a raw layout frame, the code may look as follows:

<%

//----------------------------------------

// body.jsp

//----------------------------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

<table border="1" width="100%">

<tr> <td colspan="2"> Page Title </td> </tr>

<tr>

<td width="20%"> Side Navigation </td>

<td width="80%"> <br/><br/><br/><br/> Page Content <br/><br/><br/><br/> </td>

</tr>

</table>

This creates the following Communiqué page:

<td width="80%"> <br/><br/><br/><br/> Page Content <br/><br/><br/><br/> </td> </tr> </table> This creates the following Communiqué page: 4.2.3

4.2.3 Dynamic Information

You can use JSP functions to access page information, such as the page title. The following code displays the page title on the page:

<%

//--------------------------------------------

// body.jsp

//--------------------------------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

<table border="1" width="100%">

<tr> <td colspan="2">

<cfc:atomValue qualident="TitleText" default="[no title]"

/>

</td>

</tr>

<tr>

<td width="20%"> Side Navigation </td>

<td width="80%"> <br/><br/><br/><br/> Page Content <br/><br/><br/><br/> </td>

</tr>

</table>

If the page title is set to “My Page”, this looks as follows:

</tr> <tr> <td width="20%"> Side Navigation </td> <td width="80%"> <br/><br/><br/><br/> Page Content <br/><br/><br/><br/> </td> </tr> </table>

To change the page title, click the Page Properties button in the top toolbar. After you change the title, the page automatically displays the new title.

Note: In Communiqué, functional elements such as the navigation and the page content are handled by components. See below for details on how to add these to the layout.

4.2.4 Pictures

You can use your application’s docroot folder to store pictures and other files that you want to use in your layout.

Uploading a Picture

To add a picture to the docroot folder, proceed as follows:

  • 1. In CQDE, click the Resources tab.

2.

Unfold your application folder. If you have followed this guide, it contains a folder named “docroot”. If it does not, then create it.

  • 3. Right-click the docroot folder, and then click Import. A file import window opens.

  • 4. In the “Files of type” list, click All files. Select the picture file you want to upload, and then click Open. In the following window, click No to upload the file without checking it out.

  • 5. The file is now in your docroot folder, and you can use it on your Web site.

2. Unfold your application folder. If you have followed this guide, it contains a folder named

If you use a default installation of Communiqué on your local computer, you can now access the picture using you Web browser. For the above example (with a picture named leonardo.gif), and for a default installation on your local computer, type the following address into the address field of your Web browser:

http://localhost:4402/author/leonardo.gif

The picture is displayed as follows:

2. Unfold your application folder. If you have followed this guide, it contains a folder named

Adding the Picture to the Layout

In a template, you can specify the picture’s path relative to the docroot folder. Communiqué automatically extends the path when necessary, so the picture displays correctly on all servers.

To add a background image to the example, add the following code:

// body.jsp

//-------------------------------------------------------

----------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

<table border="1" width="100%">

<tr> <td colspan="2" background="/leonardo.gif">

<h3><cfc:atomValue

qualident="TitleText" default="[no title]"

/></h3>

</td>

</tr>

<tr>

<td width="20%"> Side Navigation </td>

<td width="80%"> <br/><br/><br/><br/> Page Content <br/><br/><br/><br/> </td>

</tr>

</table>

You must use the slash in front of the file name, so Communiqué treats the path as a path that starts from Communiqué’s root folder. Communiqué changes the path if necessary, so for example the path in the page HTML of a default authoring instance is automatically changed to “/author/leonardo.gif”.

The picture is now displayed in the layout as follows:

// body.jsp //------------------------------------------------------- ---------------------- %><%@ include file=" .. /global/header.jsp" %><% Style actstyle = null; %> <cfc:initComponent

Note: Pictures that are part of the page content are handled differently. They are stored by a component, with the page data.

4.2.5 Adding a Secondary Layout

If you want to display the page content in different forms, for example as a print layout, you can use a secondary layout for this.

4.2.5.1 Creating the Layout Files

To create a new HTML layout, you need to create two new script files, and you can typically re-use the global script files. The new files are as follows:

A body script that layouts the page body.

A main script that includes the modified body script.

A start script that includes the global scripts and the modified main script.

For example, to create a print layout, proceed as follows:

  • 1. In the CQDE, click the Resources tab, and unfold your application structure.

  • 2. Right-click the file body.jsp, and then click Make Copy. Make a copy in the same location, with the name bodyPrint.jsp. This file contains the print layout script.

  • 3. Right-click the file main.jsp, and then click Make Copy. Make a copy in the same location, with the name mainPrint.jsp.

  • 4. Double-click the new file to edit it, and change the last include statement to <cq:insertfile name=”bodyPrint.jsp” />.

  • 5. Right-click the file start.jsp, and then click Make Copy. Make a copy in the same location, with the name startPrint.jsp.

  • 6. Double-click the new file to edit it, and change the last include statement to <cq:insertfile name=”mainPrint.jsp” />.

Now, you have created a file structure for your print layout as follows:

4.2.5.2 Writing the Print Layout You can now change the file bodyPrint to display the print

4.2.5.2 Writing the Print Layout

You can now change the file bodyPrint to display the print layout. For example, if you want to adapt the example HTML code to a layout that has no navigation and no layout tables, the code of the file bodyPrint.jsp looks as follows:

<%

//-------------------------------------------------------

----------------------

// bodyPrint.jsp

//-------------------------------------------------------

----------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

<h3><cfc:atomValue

qualident="TitleText" default="[no title]"

/></h3>

Page Content

4.2.5.3 Adding the Print Layout to the Template

In Communiqué, you store different layouts of a page under the same page name, but with a different script selector. For example, the different layouts of the page content/mySite/en/myPage are available under the following addresses:

When you request such a page, Communiqué processes the request as follows:

  • 1. It uses the URL up to the first dot to identify the page in the repository. This means that both URLs above point to the same page (and thus, the same template).

  • 2. It uses the script selector (for example, “print”) to match the script. This means that the second URL starts a different script of the page template.

Note: The above way of setting up the different layouts means that Communiqué automatically clears all cached layouts when you update the page.

Specifying the Start Script

To add the print layout to the template, you need to tell Communiqué for which URLs to use it. Proceed as follows:

  • 1. In CQDE, click the Templates tab.

  • 2. Right-click the template for which you want to define the new layout, and then click Edit Template Definition. The Edit Template window opens.

  • 3. In the Scripts group, click and then click your new layout script(for example, startPrint.jsp). Click OK to select the script. Communiqué automatically adds the script type.

  • 4. In the Glob field, type the selector for the new layout, for example print. This means that the layout is used for all scripts that contain the selector print.

  • 5. Click Add. The script is now added to the template definition. Note that the scripts are in the wrong evaluation order yet.

Note : The order of the scripts in the Scripts list does not matter. Communiqué always

Note: The order of the scripts in the Scripts list does not matter. Communiqué always uses the most specific script that matches.

4.2.5.4 Adding a Layout Switch

To add a layout switch from the main layout to the print layout, add the following code to the script start.jsp:

<%

//----------------------------------------------

// body.jsp

//----------------------------------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

<table border="1" width="100%">

<tr> <td colspan="2" background="/leonardo.gif">

<h3><cfc:atomValue

qualident="TitleText" default="[no title]"

/></h3>

</td>

</tr>

<tr>

<td width="20%">

<a href="<%= actpage.getLabel() %>.print.html">

Print

</a>

<br/><br/><br/> Side Navigation </td>

<td width="80%"> <br/><br/><br/><br/> Page Content <br/><br/><br/><br/> </td>

</tr>

</table>

This adds a link to the print layout, as follows (see left, above the navigation place holder):

<table border="1" width="100%"> <tr> <td colspan="2" background="/leonardo.gif"> <h3><cfc:atomValue qualident="TitleText" default="[no title]" /></h3> </td> </tr> <tr> <td

4.2.6 More Information

How the Template CSD Works

The template CSD defines the content that a page can store in the repository. You do not have to specify the content of the components that you add to the page, as these are handled separately.

In Communiqué, every page must store at least one piece of information in the repository: Which template it is based on. Thus,

the CSD of every template must contain one field where Communiqué can store this information. A minimal CSD contains exactly this information. It looks as follows:

<?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE csd SYSTEM "cq:/system/resources/dtd/xmlcsd.dtd"> <csd name="myTemplate" base="cfcdefault"> <hierarchy_driver name="default" /> <container base="cfcdefault"> <atom label="Template" default="/apps/myApplication/templates/myTemplate" driver="default" isBinary="false" /> </container> </csd>

If you have created the CSD with the template wizard, the CSD already contains this information. You can read it as follows:

<?xml…

The XML header, which specifies that this is an XML file, it was written with a European character set, and its structure is defined in the file xmlcsd.dtd. Usually, you can ignore this information.

<csd…

The name of the CSD file.

<container…

The container is roughly the repository equivalent of a folder. Communiqué uses the container “cfcdefault” for internal information.

<atom…

An atom is a data field in the repository. The minimal template CSD contains one atom.

label=

The label under which the information is stored. Communiqué stores the template information always under the name “Template”.

default=

The default value that is used for all pages that are based on this CSD. This ensures that all pages that are based on this CSD automatically list this template as their template.

driver=

The driver that is used to store the atom in the repository. Usually, the default driver is used.

isBinary=

“false” indicates that you store only text data in this atom. This information helps Communiqué to store files more efficiently in the repository.

indexinghint=

Use “default” to index the content of this atom, or “ignore” to ignore the content. Setting the indexing hint correctly makes search faster and more precise.

Standard Page Properties

The page properties allow you to store information on a page, such as the page title, meta information and workflow data.

If you have created the template

By default, Communiqué uses a standard set of page information. To see the set, click the Page Properties button on any page in Communiqué’s Designground example.

The page properties allow you to store information on a page, such as the page title,

4.3 Increasing Productivity for Authors

You can configure the template in several ways to make it easier to use for authors.

4.3.1 Restricting the Scope of the Template

You can restrict where authors can use your template to create new pages. This allows you, for example, to restrict your product page template to the product branch of your Web site. Restricting templates makes it easier for authors to find the templates they want to use at any location.

To restrict the scope of a template, proceed as follows:

  • 1. In the Templates view of the CQDE, right-click the template for which you want to define the new layout, and then click Edit Template Definition. The Edit Template window opens.

  • 2. To allow authors to use the template in a part of the Web site, type the path, and click Allow. Then click Add.

3.

To deny authors to use the template, type the path where authors are not allowed to use the template, click Deny, and then click Add.

  • 4. Click Apply and close the window.

Communiqué evaluates all the statements from top to bottom. Thus, you can use a deny statement to override a previous allow statement, for example to allow a template on all pages except the product pages.

To change the order of the statements, drag the icon to the left of the statement you want to move.

Note: The scope specifies only where authors can create pages that are based on the templates. When an author moves a page, or you change the scope, a page may lie outside of the scope you have defined.

4.3.2 Providing a Preview Image

The preview image helps authors to quickly locate the template they need. To provide the preview image, proceed as follows:

  • 1. Go to a good example page that is based on the template for which you want to make the preview image.

  • 2. Create a screenshot of the page. In Micsrosoft Windows, press ALT+PRINT SCREEN to create a screenshot of the active window in the clipboard.

  • 3. Using image processing software, scale the image down to a width of 175 pixels and a height of 100 pixels.

  • 4. Save the picture on your computer. Use a name that uniquely identifies the template, such as th_myFirstTemplate.gif.

  • 5. Drag the image from your computer into the docroot folder of your application in CQDE. Click No when you are asked if you want to check out the imported file.

3. To deny authors to use the template, type the path where authors are not allowed
  • 6. In the Templates view of the CQDE, right-click the template for which you want to define the new layout, and then click Edit Template Definition. The Edit Template window opens.

7.

In the Thumbnail Image field, type the name of the thumbnail image, for example th_myFirstTemplate.gif.

  • 8. Click Apply and close the window.

Note: To make a preview image, you need at least a working prototype of the page. Typically, you can create the image after the template is finished and the Web site has content.

7. In the Thumbnail Image fiel d, type the name of the thumbnail image, for example

4.3.3 Specifying an Explicit Sort Order

If you specify an explicit sort order for the templates, you can make sure that authors always have the frequently used templates at the top of their list, while rarely used templates are at the bottom.

For simplicity, use the letters a to z as sort keys, “a” indicating a frequently used template, “z” indicating a rarely used template.

For example, to specify a template with medium use (“m”), proceed as follows:

1.

In the Templates view of the CQDE, right-click the template for which you want to define the new layout, and then click Edit Template Definition. The Edit Template window opens.

  • 2. In the Sort Key field, type the letter that mirrors the importance of the template. For a medium-use template, type m.

  • 3. Click Apply and close the window.

Note: To evaluate the importance of a template, consider the scope of the template. For example, a template with a narrow scope may always be the first choice in its scope, although it may not be used often in absolute terms.

4.3.4 Providing Individual Icons for the Template

You can provide individual icons for all the pages that are based on your template. This is necessary only if authors need to quickly distinguish between different types of pages on the Web site. If you do not specify the icons, all pages are displayed using the Communiqué default icons.

For a page, you have to create three icons:

The icon of the page in the page list. This icon is 13 on 15 pixels large.

The icon of the page in the navigation, when it is displayed as a closed folder. This icon is 18 on 22 pixels large.

The icon of the page in the navigation, when it is displayed as an open folder. This icon is 18 on 22 pixels large.

To add the icons to the Web site and the template, proceed as for adding a thumbnail picture.

5 Components

Components are Communiqué’s building blocks. They offer a wide range of advantages for development:

They are modular. A component does not depend on any central files or configuration settings. You can usually develop a component completely separately from the rest of the Web site.

They are re-usable. You can develop a component on your local computer, and then add it to a larger project, and later re-use it for other projects.

You can use Java, JSP (Java Server Page scripting), or EcmaScript (server-side JavaScript) for development.

They allow you to separate functions (which you put into components) from the main page layout (which you put into a template).

Communiqué offers a standard editing interface for components, offering a seamless user experience.

5.1 Creating a Component

The first step in creating a component is to create the component definition. A component contains several different files, and the component definition lists which files are used for what.

To create a new component definition, proceed as follows:

  • 1. In the CQDE ContentBus view, right-click the Components folder in your application folder, and click New. The Create New Page window opens.

  • 2. Type the name of your new component, for example myFirstComponent. In the CSD list, click component.

5 Components Components are Communiqué’s buildi ng blocks. They offer a wide range of advantages for
  • 3. Click OK to create the new component definition.

3. Click OK to create the new component definition. Note : The name of the component

Note: The name of the component must not contain a space, special character or a reserved Java word.

5.1.1 Setting Up a New Component

To edit the component definition, proceed as follows:

  • 1. In the CQDE ContentBus view, right-click the component, and then click Edit Component Definition. The component definition opens.

3. Click OK to create the new component definition. Note : The name of the component

When you create a new component from scratch, you have to provide the following information:

Title

The title of the component. If you use the

 

component in a paragraph system, the title is displayed to authors when they select the paragraph type.

Description

The description of the component. This is not displayed to authors, and you can leave it empty.

Allow tags

The HTML tags below which you can place the component. This is used by the advanced template wizard. Use the following settings:

* allow tr deny This means the advanced template wizard offers to include the component anywhere in an HTML layout, except directly below a table row (tr) tag.

Allow parent

Specifies where you can use the component. If

* allow

components

the component can be used as a paragraph in a

paragraph system, use the following:

If you do not want to use the component as a paragraph, use the following:

* allow apps/Components/parsys deny

5.1.2 Extending an Existing Component

To extend an existing component, proceed as follows:

  • 1. In the CQDE ContentBus view, right-click the component, and then click Edit Component Definition. The component definition opens.

  • 2. In the Title field, type the title of your component.

  • 3. In the Base component list, click the component that you want to extend.

If you extend an existing component, you can leave fields blank in the component definition to

If you extend an existing component, you can leave fields blank in the component definition to use the value from the base component.

If you fill in only the title field, the component behaves like an exact copy of the base component. This is useful if you want to use an existing component, which you want to extend later.

Note: We recommend that you always use copies of existing components. This means that you can extend the component later without having to migrate content or change the code of the source component.

5.2 Writing the Component Script

The component layout usually consists of a JSP file, so you can use HTML code, JSP code, and call Java classes from your component script. This section adds a script file to the component, which displays a hello world message.

Note: In a component, you cannot use different scripts, for example to create a separate print layout. To display the component on a page, Communiqué always uses the main component script. You can however specify scripts that Communiqué executes instead of displaying a page, for example to provide a chart image.

5.2.1 Creating the Script File

The component script file is by default named like the component, and located below the component definition file. To create it, proceed as follows:

  • 1. In the CQDE resource view, right click your new component, point to New, and then click File. The Create New File window opens.

  • 2. As the file name, use the same name as the component, and the file extension .jsp. Click OK to create the file.

Note: In a component, you cannot use different scripts, for example to create a separate print
  • 3. Double-click the script file and type Hello World!. Click Save to save it.

Note: In a component, you cannot use different scripts, for example to create a separate print

5.2.2 Adding the Script to the Component

To add the script to the component, proceed as follows:

  • 1. In the CQDE ContentBus view, right-click the component, and then click Edit Component Definition. The component definition opens.

  • 2. In the Script field, click the Browse button (to the right of the field) and select the script. Communiqué writes the full path of the script into the Script field, and sets the Script type field accordingly.

  • 3. Click Apply to save the changes.

5.2.3 Testing the Component Add the component to the template using the following code (in bold):

5.2.3 Testing the Component

Add the component to the template using the following code (in bold):

<%

//---------------------------------------------

// body.jsp

//---------------------------------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

<table border="1" width="100%">

<tr> <td colspan="2"> <cfc:includeComponent

cellId="webtitle"

componentId="/apps/Components/webtitle"

/>

</td>

</tr>

<tr>

<td width="20%"> <cfc:includeComponent cellId="navigation" componentId="/apps/Components/textnavigation"

/>

</td>

<td width="80%">

<cfc:includeComponent cellId = "myComponent" componentId =

"/apps/myApplication/Components/myFirstComponent"

/>

</td>

</tr>

</table>

If you have included the component in the template example script (as above), the result looks as follows:

cellId="webtitle" componentId="/apps/Components/webtitle" / > </td> </tr> <tr> <td width="20%"> <cfc:includeComponent cellId="navigation" componentId="/apps/Components/textnavigation" /> </td> <td width="80%">

5.3 Adding Content

Components are often used to allow authors to store, edit and publish information. For this task, a component has its own information structure and editing windows, and if necessary scripts to display pictures and media files.

When you add a component to a page, Communiqué automatically adds the component’s settings, functions and files to the template definition. As a result, the template can now use all of the component’s functions.

5.3.1 Specifying the Content Structure

You need to specify the content the component can store in a so- called Content Storage Definition, or CSD. In Communiqué, content

elements are called atoms, so the name of the default CSD is atoms.xml.

Creating the CSD file

  • 1. In the CQDE resource view, right click your new component, point to New, and then click File. The Create New File window opens.

  • 2. As the file name, use atoms.xml. Click OK to create the file. Communiqué opens the empty file for editing.

elements are called atoms , so the name of the default CSD is atoms.xml . Creating
  • 3. Add the default CSD framework (see below) to the newly created CSD file. Click Save to save the CSD.

The default CSD framework looks as follows (you can use any name for the include tag):

<?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE include SYSTEM "cq:/libs/Components/resources/dtd/csdincluds.dtd"> <include name="myContent">

</include>

Adding the CSD to the Component

To add the CSD to the component, proceed as follows:

  • 1. In the CQDE ContentBus view, right-click the component, and then click Edit Component Definition. The component definition opens.

  • 2. In the Content atoms field, click the Browse button (to the right of the field) and select the CSD. Communiqué writes the full path of the CSD into the Script field.

  • 3. Click Apply to save the changes.

Specifying Content In Communiqué, a so-called atom can store any one piece of data, such as

Specifying Content

In Communiqué, a so-called atom can store any one piece of data, such as a text, a date value, or a picture. To specify an atom, you use the <atom> tag, which has the following attributes:

label

The name of the atom.

driver

The driver used to store the atom. In Communiqué 4, this is ignored. For backward compatibility, use default and blob_default for text and picture data, respectively.

isBinary

Use true if the atom stores large binary files, such as pictures or office documents. Communiqué may use this value to optimize data storage (depending on your setup).

default

The default value of the atom.

encoder

Encodes the content before storing it. Use this for passwords.

decoder

Decodes the content before displaying it.

indexinghint

Tells Communiqué how to index the atom content:

fulltext: Indexes all words of the content. ignore: Does not index the content. exact: Indexes the entire content as one string. default: Uses ignore for atoms that have isBinary=true, and fulltext for all others.

To store text information in an atom, use the following code:

<atom label="myText" driver="default" />

To store picture data or other binary data, use the following code:

<atom label="Image" driver="blob_default" isBinary="true" />

A full CSD that can store a picture, and a text then looks as follows:

<?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE include SYSTEM "cq:/libs/Components/resources/dtd/csdincluds.dtd">

<include name="myContent"> <atom label="myText" driver="default" /> <atom label="Image" driver="blob_default" isBinary="true" /> </include>

Note: If you want to use Day’s scripts to display the image, you must use the label Image for the atom that stores the image data.

You can create more complex, hierarchical content structures in a CSD. However, for most applications a linear content structure is sufficient, and is best supported by Communiqué’s authoring interface.

5.3.2 Adding the Content Dialog

Communiqué’s dialog editor allows you to create a standardized editing window, with which authors can edit the content of the component.

Note: If you want to use your component in a paragraph system, you need to provide an editing window. For other components, you may omit this if the component does not store content.

5.3.2.1 Starting the Dialog Editor

To start the dialog editor and create a new dialog definition file, proceed as follows:

  • 1. In the CQDE Resource view, right-click, and then click New CFC Dialog Definition Wizard. A file selector opens.

  • 2. In the file selector, click the component for which you want to create the dialog. As file name, use the default, Dialog.any.

  • 3. Click OK to start the dialog editor.

  • 4. Click the Save Dialog button to create the new dialog file.

If you want to edit an existing dialog definition file, proceed as follows:

  • 1. In the CQDE Resource view, unfold your component folder.

  • 2. If the Dialog.any file is not displayed, right-click the folder, and then click Refresh.

  • 3. If the Dialog.any file is checked in (gray), right-click it, and then click Check Out.

  • 4. Right-click the Dialog.any file, and then click Edit CFC Dialog Definition. The dialog editor starts.

5.3.2.1 Starting the Dialog Editor To start the dialog editor and crea te a new dialog

5.3.2.2 Using the Dialog Editor

5.3.2.2 Using the Dialog Editor The dialog editor has the following panes: Dialog (left) The preview

The dialog editor has the following panes:

Dialog (left)

The preview of the dialog window. Double-click an element or an area to display the properties.

Controls (top

The controls that you can add to the dialog, such

right)

as text edit, date, or file download.

Properties

Displays the properties of the current control or

(center right)

the dialog element.

Actions

Buttons that allow you to save the dialog, among

(bottom right)

other actions.

Note: The dialog is active while you edit it, so you can use tabs and other functions. However, do not click the dialog’s OK, Save or Cancel button while you edit, because this results in an error, or it closes the dialog editor window.

How Dialogs Work

A dialog consists of the following parts:

One or more tab pages. To edit the tab page properties (such as the title), double-click the top or bottom of the tab content.

Each tab page contains one or more atom lines. An atom line contains two columns: A title column to the left, and a control to the right. To edit the atom line properties, double- click the left or right side of the line.

Each atom line contains one control. To edit the control properties, click the three dots to the right of the dialog.

A save group, which contains OK, Save, Delete and/or Cancel buttons. Double-click the bottom border to edit the save group properties.

Adding Controls

• Each atom line contains one control . To edit the control properties, click the three

To add a control to the dialog, proceed as follows:

  • 1. In the control pane (top right), click the control you want to add. The cursor turns into a crosshair, so you can place the new control.

  • 2. Click in the tab, below the existing controls (so that the entire tab content is marked in blue). Communiqué adds a new atom line with the new control below the existing atom lines.

  • 3. A window opens, where you can type the label of the new control. Type the name of the atom that stores the content. If you follow the example, create an Edit control with the label myText, and a picture control with the label myPicture. Click OK to continue.

  • 4. Double-click the three points next to the control to edit the control properties. Click the Submit Dialog button to transfer the changes to the dialog.

5.

Double-click the left or right end of the atom line to set the title, subtitle and description of the line. Click the Submit Dialog button to transfer the changes to the dialog.

  • 6. When you are done, click the Save Dialog button to save the changes to the dialog file.

Note: The dialog editor allows you to add controls to an existing atom line. However, for consistency and usability, we recommend to use only one control per atom line.

Adding a Tab Page

You can use multiple tab pages to structure the dialog. To add a tab page, proceed as follows:

  • 1. Click the Tab Page control button. The cursor turns into a crosshair.

  • 2. Click in the top bar (next to the existing tab). Communiqué creates the new tab page.

  • 3. Click the new tab, and then double-click the dialog window (below the tab title). The dialog editor displays the tab properties.

  • 4. Type a title for the tab page, and then click Save Dialog to save the new tab to the dialog file.

Adding an OK or Save Button

When you have added the tabs and controls, proceed as follows to add an OK or Save button:

  • 1. Double-click the dialog background next to the Cancel button. The SaveGoup properties are displayed.

  • 2. Check the button or buttons you want to use (OK, Cancel, Save or Delete).

  • 3. Click Save Dialog to save the changes to the dialog file.

Note: Place the OK or Save button only as the last step. They are active immediately, and will cause an error when you click them in the dialog editor. Also, they are next to (and bigger) than the dialog editor’s buttons, so it is easy to accidentally click them.

5.3.2.3 Adding the Dialog to the Component Definition

5. Double-click the left or right end of the atom line to set the title, subtitle

To add the dialog to the component, you have to change the component definition file. Proceed as follows:

  • 1. In the CQDE ContentBus view, right-click your component, and then click Edit Component Definition. The Edit Component window opens.

  • 2. Click the browse button to the right of the Content Dialog field. A file selector opens.

  • 3. Click the dialog file you have created (which is named Dialog.any, and is in the folder of the component you edit). Click OK.

  • 4. Click Apply. The component now uses your dialog when authors want to edit the content of your component.

5.3.2.4 Adding an Edit Bar

To make the dialog available for authors, you must add an edit bar to the component. Authors can then click the edit button to edit the component’s content, using the dialog.

To add the edit bar, add the following code (in bold) to the component:

<%@ page import="com.day.cq.contentbus.*" %><% %><%@ page import="com.day.cq.cms.components.*" %><% %><%@ taglib uri="/cqtlb" prefix="cq" %><% %><%@ taglib uri="/cfc" prefix="cfc" %><% ComponentContext cc = (ComponentContext) request.getAttribute("componentContext"); ComponentInfo ci = cc.getComponentInfo(); %>

<table border="1"> <tr> <td>

<cfc:editbar parName="<%= cc.getContainerList() %>" parNum="<%= cc.getContainerLabel() %>" storagePre="<%= cc.getStoragePre() %>" dialogAny="<%= ci.getContentDialog() %>"

/>

My Component

</td>

</tr>

</table>

The component with the edit bar looks as follows:

5.3.2.5 Testing the Dialog When you create a dialog, Communiqué does not check if the labels

5.3.2.5 Testing the Dialog

When you create a dialog, Communiqué does not check if the labels of the controls correspond to the atom names of your CSD. For this reason, we recommend that you test the new dialog as follows:

  • 1. Add the component to a page or to a paragraph system.

  • 2. Fill in all values of the dialog, and then save the dialog.

  • 3. Re-open the dialog and check if all values are displayed.

If Communiqué drops a value you have entered, the label for the control does not correspond to an atom in the CSD. Check both the CSD and the dialog definition file.

Note: The easiest way to compare and change dialog labels is to open the dialog file as text (see below).

5.3.2.6 Working with the Dialog Code

The file Dialog.any, which stores the dialog definition, is a text file, and you can edit it in CQDE. A dialog file looks as follows:

#encoding:iso-8859-1

/Type "Dialog" /Sub { /Tab { /Type "Tab" /Sub {

/page1

{ /Type "TabPage" /text "Tab One" /leftColWidth "170" /Sub {

/CFCWiz_1144661641401

{ /Type "AtomLine"

/Sub { /test { /Type "Edit" /cols "20" /rows "1" /begin "" /end "" /subBegin "" /subEnd "" }

} /title "Title" /subTitle "Subtitle" /description "This is a description text." /intlTitle " " /intlSubTitle " " /intlDescription " " }

}

}

} /intlParName " " } /dlgButtons { /Type "SaveGroup" /format "|c|" /subBegin "<td>" /subEnd "</td>" }

}

For most actions, it is easier to use the dialog editor. However, editing the text file directly has its advantages:

You can see and change the labels. The labels are section headings in the file, such as /test.

You can create multi-line edit fields. In the above example, you can do this by changing the /rows value. This function is not available in the dialog editor.

5.3.3 Accessing the Content

To access the content from JSP, you can use the <cfc:atomValue> tag. To display the text in your example component, add the following code (bold) to the script myFirstComponent.jsp:

<%@ page import="com.day.cq.contentbus.*" %><% %><%@ page import="com.day.cq.cms.components.*" %><% %><%@ taglib uri="/cqtlb" prefix="cq" %><% %><%@ taglib uri="/cfc" prefix="cfc" %><% ComponentContext cc = (ComponentContext) request.getAttribute("componentContext"); ComponentInfo ci = cc.getComponentInfo(); %>

<table border="1"> <tr> <td>

<cfc:editbar parName="<%= cc.getContainerList() %>" parNum="<%= cc.getContainerLabel() %>" storagePre="<%= cc.getStoragePre() %>" dialogAny="<%= ci.getContentDialog() %>"

/>

<cfc:atomValue qualident='<%= cc.getQualident() + ".myText" %>' default="[empty]"

/>

</td>

</tr>

</table>

Now, you can use the edit bar to edit the component content:

<table border="1"> <tr> <td> <cfc:editbar parName="<%= cc.getContainerList() %>" parNum="<%= cc.getContainerLabel() %>" storagePre="<%= cc.getStoragePre() %>" dialogAny="<%= ci.getContentDialog()

The component is displayed with the text you have typed:

<table border="1"> <tr> <td> <cfc:editbar parName="<%= cc.getContainerList() %>" parNum="<%= cc.getContainerLabel() %>" storagePre="<%= cc.getStoragePre() %>" dialogAny="<%= ci.getContentDialog()

5.3.4 Displaying Pictures

If you want to display picture data using the component, you need a so-called spool script, which provides the picture data. There are several possibilities for how to use pictures in a component:

You want to display a picture that is stored in the component content, or the media library.

You want to create a new picture, such as a bar chart, a smoothly rendered page title, or a navigation element.

You want to modify an existing picture, for example to provide thumbnail images.

5.3.4.1 Adding the Spool Script

The spool script is the script that returns the image data to the browser. You can use the spool script from Communiqué’s image component for this purpose. To add it to your component, proceed as follows:

  • 1. In the CQDE ContentBus view, right-click your component, and then click Edit Component Definition. The Edit Component window opens.

  • 2. In the Scripts group, click the field. The file selector opens.

...

button next to the Name

  • 3. Click the file apps/Component/image/image.esp, and then click OK.

  • 4. In the Glob field, type mfc_spool. This name must be unique (in this case, mfc stands for “my first component”, but you can use any other unique name).

  • 5. Click Add to add the script to the component, and then click Apply to save your changes.

The script is now used for all files that have mfc_spool as the script selector. For

The script is now used for all files that have mfc_spool as the script selector. For example, the script is used for the following URL:

www.myCompany.com/en/myPage.mfc_spool.jpg

The following section describes exactly how to call the spool script so that it returns your picture.

5.3.4.2 Writing the <img> Tag

The image script expects a URL with the following parts:

  • 1. The URL to the page (you can use Communiqué’s internal path for this, Communiqué automatically translates this to an external path when it displays the page). For example, the URL is /content/en/myPage

  • 2. The script selector, for example .mfc_spool

  • 3. The address of the container that stores the picture data, such as .content.Single. You do not need to provide the

name of the atom, as the script always uses the Image atom.

  • 4. The file extension, such as .jpg.

To access picture information, such as the picture’s width, height, and MIME type, you need Communiqué’s Layer object. The following bolded code displays the image that is stored in the component’s Image atom:

<%@ page import="com.day.cq.contentbus.*" %><%

%><%@ page import="com.day.cq.cms.components.*" %><%

%><%@ page import="com.day.image.Layer" %><%

%><%@ taglib uri="/cqtlb" prefix="cq" %><% %><%@ taglib uri="/cfc" prefix="cfc" %><% ComponentContext cc = (ComponentContext) request.getAttribute("componentContext"); ComponentInfo ci = cc.getComponentInfo(); %><cfc:defineObjects requestName="cqReq" currentPageName="actpage"/>

<table border="1"> <tr> <td>

<cfc:editbar parName="<%= cc.getContainerList() %>" parNum="<%= cc.getContainerLabel() %>" storagePre="<%= cc.getStoragePre() %>" dialogAny="<%= ci.getContentDialog() %>"

/>

<cfc:atomValue qualident='<%= cc.getQualident() + ".myText" %>' default="[empty]"

/>

<br/>

<% try { Layer myLayer = new Layer( actpage.getAtom( cc.getQualident() + ".Image" ).getStream()); %> <img src="<%= cc.getPage().getHandle() %>.mfc_spool.<%= cc.getQualident() %>.<%=

myLayer.getMimeType().substring(6).replaceFirst("jpeg","j

pg")

%>" width="<%= myLayer.getWidth() %>" height="<%= myLayer.getHeight() %>"

/>

<% } catch (Exception e) { %>

[The image cannot be displayed] <% } %> </td> </tr> </table>
[The image cannot be displayed]
<% } %>
</td>
</tr>
</table>
[The image cannot be displayed] <% } %> </td> </tr> </table> Note: Make sure you import

Note: Make sure you import the Layer class (at the top of the script). Without the import statement, the component does not run.

5.4 Using a Component in a Template

Communiqué comes with a number of pre-fabricated components which you can use in your templates. Because components are modular, you can always exchange a pre-fabricated component for a custom one later on.

5.4.1 Adding a Component to a Template

You can use Communiqué’s <cfc:includeComponent> tag to add a component to the layout. The following code adds three of Communiqué’s pre-fabricated components to the script body.jsp:

The Web title component, which displays the title of the page as a dynamically generated image.

The text navigation component, which displays a navigation area.

The rich text editor, which allows authors to add content to the page.

<%

//---------------------------------------------

// body.jsp

//---------------------------------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

<table border="1" width="100%">

<tr>

<td colspan="2">

<cfc:includeComponent

cellId="webtitle"

componentId="/apps/Components/webtitle"

/>

</td>

</tr>

<tr>

<td width="20%">

<cfc:includeComponent

cellId="navigation"

componentId="/apps/Components/textnavigation"

/>

</td>

<td width="80%">

<cfc:includeComponent

cellId="content"

componentId="/apps/Components/richtexteditor"

/>

</td>

</tr>

</table>

The page now looks as follows. Note that the blue edit bars are visible only in authoring mode, they disappear when the page is published.

The page now looks as follows. Note that the blue edit bars are visible only in

Note: For the content area, you have added a single rich text component. Usually, you use a paragraph system (see below), so authors can add multiple paragraphs, and can combine different paragraph types.

5.4.2 Editing the Component Content

Components come with a standardized authoring interface. This allows authors to edit the component content in a similar way for all components.

For example, to edit the content of the rich text component (which is empty at the start), proceed as follows:

  • 1. Log in to Communiqué’s authoring environment, and open the page for editing.

  • 2. Click the edit icon (pen) in the content area of the page. The edit window opens, and you can type the text content

into the edit field.

into the edit field. 3. Click Save . Communiqué saves the changes and displays the text
  • 3. Click Save. Communiqué saves the changes and displays the text you have typed on the page.

into the edit field. 3. Click Save . Communiqué saves the changes and displays the text

5.4.3 Configuring a Component

You can configure components using Communiqué’s authoring and administration interface. For example, to configure the text navigation component so that it displays only the English branch of the Web site, proceed as follows:

  • 1. Log in to Communiqué’s authoring environment, and open the page for editing.

  • 2. Click the Designer Mode button. Communiqué now displays buttons for all components you can configure.

2. Click the Designer Mode button. Communiqué now displays buttons for all components you can configure.
  • 3. To configure the navigation, click the Navigation (Text) button. The navigation component configuration window opens.

2. Click the Designer Mode button. Communiqué now displays buttons for all components you can configure.
  • 4. In the Start level field, type 2. In the Show root page group, click No. For a standard page structure (such as the design ground), this displays all pages in the current language.

  • 5. Click Save. Communiqué stores the settings centrally, so they affect an entire branch of a Web site, or the entire site.

Click the Edit Mode button to return to the edit mode.

Click the Edit Mode button to return to the edit mode. 5.4.4 More Information Components are

5.4.4 More Information

Components are designed to add flexibility and reusability to templates. The so-called “component includer” merges the template with the component definition to provide a seamless integration of the component in the template.

When you first call a template with a new component, the following things happen:

The component includer adds the component’s content CSD to the template CSD. The new template CSD now provides storage for both the template and the component information.

The component includer adds the component’s design CSD to the design page. The component can now store its design values on the central design page.

The component includer adds the component’s hierarchical relation to the component hierarchy file of the template.

Note: If you re-open the template definition, you can see the changes that the component includer has made to the template.

Then, every time the component is used, the component includer does the following:

It loads the component content from the page.

It loads the component design values from the central design page.

Note: If you change the component hierarchy, you need to delete the component hierarchy file manually. The component includer will then re-create a current version of the file the next time you call the page.

5.5 Using the Paragraph System

The paragraph system allows authors to freely add several paragraphs of different types to a page. For example, the content of a product page may contain:

An image of the product (in the form of an image or textimage paragraph)

The product description (as a rich text paragraph)

A table with technical data (as a table paragraph)

A datasheet for download (as a download paragraph)

Each paragraph type is represented as a component. The paragraph system itself is also a component, which contains the other paragraph components.

5.5.1 Adding the Paragraph System to a Template

The paragraph system is a component. To add it to a template, use the following code:

<%

//---------------------------------------------

// body.jsp

//---------------------------------------------

%><%@ include file="

..

/global/header.jsp"

%><%

Style actstyle = null; %> <cfc:initComponent cellId="body" componentId="/libs/Components/body"> <% actstyle = componentContext.getStyle(); %> </cfc:initComponent> <cfc:includeComponent cellId="body" componentId="/libs/Components/body" />

<table border="1" width="100%">

<tr> <td colspan="2"> <cfc:includeComponent cellId="webtitle" componentId="/apps/Components/webtitle"

/>

</td>

</tr>

<tr>

<td width="20%"> <cfc:includeComponent cellId="navigation" componentId="/apps/Components/textnavigation"

/>

</td>

<td width="80%">

<cfc:includeComponent

cellId="Par"

componentId="/apps/Components/parsys"

/>

</td>

</tr>

</table>

This adds a paragraph system to the page, where authors can add paragraphs to a page. In the authoring environment, this looks as follows (the blue edit bars disappear on the published page):

<td width="80%"> <cfc:includeComponent cellId="Par" componentId="/apps/Components/parsys" /> </td> </tr> </table> This adds a paragraph system to the

You can use the paragraph system as follows:

Click the New icon (blank page, at the bottom) to add a paragraph. You can select the type of paragraph to add.

Click the Edit icon (pen) to edit a paragraph.

Click the Delete icon (cross) to delete a paragraph.

Click the Copy icon (two pages) to copy a paragraph.

Drag the Move handle (rightmost part of the edit bar) to move the paragraph around in the paragraph system.

5.5.2 Configuring the Paragraph System

You can specify which components are available as paragraphs in the paragraph system. This allows you to restrict the types of content that authors can put onto a page.

To select the available paragraph types, proceed as follows: