Open Text Web Solutions Delivery Server 9.0 Dynaments English (A4)

��

Australia

Europe (excluding UK)

General Information:RedDot Solutions Australia Pty Ltd

Level 12, 65 Berry Street

North Sydney

NSW 2060

Australia

Tel: +61 2 9925 1100

Fax: +61 2 9475 1487

E-Mail: [email protected]

Web: www.reddotsolutions.com.au

Customer Care:Tel.: +61 2 9925 1150


Extranet: www.reddotcommunity.com

Education: Tel.: +61 2 9925 1100


Web: www.reddotsolutions.com.au/customer_services_education.htm

General Information:RedDot Solutions AG

Industriestraße 11

26121 Oldenburg

Germany

Tel.: +49-441-93578-0

Fax: +49-441-93578-88


Web: www.reddot.de

Customer Care: Tel.: +49-441-93578-777


Extranet: www.reddot.de/service_technischer_support.htm

Education: Tel.: +49-441-93578-16


Web: www.reddot.de/schulungen.htm

North America

United Kingdom

General Information:Open Text Inc.

RedDot Web Solutions Group

One Battery Park Plaza

25th Floor

New York, NY 10004

USA

Tel: 1-866-REDDOTS

Tel: 1-212-425-3988

Fax: 1-212-425-3987


Web: www.reddot.com

Customer Care:Tel: 1-866-REDDOTS

Tel: 1-212-425-3988


Extranet: www.reddotcommunity.com

Education:Tel: 1-866-REDDOTS

Tel: 1-212-425-3988


Web: www.reddot.com/training.htm

General Information:RedDot Solutions Limited

Mulberry Business Park

Hummingbird Building

Fishponds Road

WOKINGHAM

Berkshire

RG41 2GY

United Kingdom

Tel: +44 (0)118 9360680

Fax: +44 (0)118 9360688


Web: www.reddot.co.uk

Customer Care:Tel: +44 (0)118 9360690


Extranet: www.reddotcommunity.co.uk/

Education:Tel: +44 (0)118 9360680


Web: www.reddot.co.uk/training.htm

Copyright

© 2008 RedDot Solutions. All rights reserved.

RedDot Documentation 11/2008 - RedDotLiveServer 9.0If you have any comments or suggestions about this documentation, please send an e-mail to [email protected].

This documentation contains information protected by copyright. Without prior written permission, any part of this documentation may only be reproduced, translated, stored or analyzed in dp-systems by RedDot Solutions.

The information in this documentation is subject to change without notice.

RedDot Solutions shall not be responsible for technical or editorial errors or omissions contained in this documentation. RedDot Solutions will not be liable for incidental or consequential damages resulting from the furnishing, performance or use of this documentation.

Trademarks

RedDot is a trademark of RedDot Solutions. All other product and service names are trademarks or registered trademarks of their respective owner.

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Contents

About this Manual ................................................................................................. 11

Conventions ............................................................................................................... 12

Structure ................................................................................................................. 12

Syntax .................................................................................................................... 12

Symbols .................................................................................................................. 13

RedDot DynaMents ................................................................................................ 14

What Are DynaMents? ................................................................................................. 15

DynaMent Structure .................................................................................................... 16

Processing DynaMents ................................................................................................ 17

Using the Results ........................................................................................................ 19

Variable Parameter Values .......................................................................................... 20

Inline Notation for Parameter Values ....................................................................... 20

Multiple Sources: The 'source' Parameter ................................................................ 22

XPath Statements in Parameters ............................................................................. 26

Inline Functions for Parameter Values ..................................................................... 29

Inline Function: Integrating Your Own Classes ......................................................... 30

Standard Parameters .................................................................................................. 31

Error Handling ............................................................................................................. 33

DynaMent Return Codes .......................................................................................... 36

DynaMent References ............................................................................................ 38

Attribute DynaMent ..................................................................................................... 40

Reading Attributes ('read') ...................................................................................... 40

Writing Attributes ('write') ....................................................................................... 49

Checking Constraints for Attributes ('condition') ..................................................... 61

Making Attribute Values or Child Attributes Available ('for-each') ............................ 69

Referencing Attributes ('reference') ......................................................................... 75

Renaming Attributes ('rename') ............................................................................... 78

Copying Attributes ('copy') ...................................................................................... 80

Moving Attributes ('move') ...................................................................................... 83

Removing Attribute Values from the Value List ('remove') ........................................ 86

Deleting Attributes or Attribute Values ('delete') ...................................................... 88

Saving User Attributes in Cookies ('flushcookies') ................................................... 91

5

Contents

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Writing Attributes Explicitly to the Repository ('flush') ............................................. 93

Using Attributes in XSL Files ('xslparam') ................................................................. 95

Cache DynaMent ......................................................................................................... 97

Setting the Validity of Entries in the Object Cache ('set-scope') ............................... 97

Renaming Entries in the Object Cache ('set-id') ..................................................... 100

Adding Cache Dependencies ('add-dependency') ................................................. 103

Removing Entries from the Cache ('notify') ............................................................ 107

Content DynaMent .................................................................................................... 110

Importing Content ('import') .................................................................................. 110

Recording Check Results ('validate') ..................................................................... 120

Deleting Content ('delete') .................................................................................... 126

Removing Data ('remove-data') ............................................................................. 127

Removing Content from the Cache ('notify-cache') ................................................. 129

CPS DynaMent .......................................................................................................... 131

Creating Unique IDs Within a Number Range ('id') ................................................. 131

Image DynaMent ....................................................................................................... 135

Inserting Images ................................................................................................... 135

Assigning Links to Images ..................................................................................... 138

Import DynaMent ...................................................................................................... 140

Importing/Deleting Metadata ................................................................................ 141

Importing Reference Lists for Metadata ................................................................. 150

Importing Reference Lists for Content or Content Data to Be Deleted ..................... 154

Defining and Assigning Tags ................................................................................. 155

Include DynaMent ..................................................................................................... 160

Integrating Internal or External Content ................................................................. 160

Including Weblet Module Placeholders ................................................................. 177

Including Content Versions ('include-version') ...................................................... 180

Including Difference Between Content Items ('diff') ............................................... 184

Iolet DynaMent ......................................................................................................... 188

Calling Iolets ......................................................................................................... 188

Link DynaMent .......................................................................................................... 195

Generating Simple Links ....................................................................................... 195

Generating Links with Parameters ......................................................................... 198

Link-Param DynaMent ............................................................................................... 202

Passing Other Link Parameters .............................................................................. 202

6

Contents

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Livelink DynaMent .................................................................................................... 205

Reading Objects from Open Text Livelink ('read') ................................................... 207

Creating Objects in Open Text Livelink ('create') .................................................... 215

Deleting Objects from Open Text Livelink ('delete') ................................................ 222

Determining Navigation Information for Objects ('navigate') .................................. 224

Using Prepared Searches ('xmlsearch') ................................................................. 227

Message DynaMent .................................................................................................. 235

Sending E-Mail ...................................................................................................... 235

MetaData DynaMent ................................................................................................. 243

Reading Metadata ('list') ....................................................................................... 243

Listing Content Versions ('list-versions') ................................................................ 250

Portal DynaMent ....................................................................................................... 252

Integrating Portal Applications as Content ('include') ............................................ 252

Reading Portal Instances of the Current Session ('session') ................................... 255

Removing Portal Instances from Sessions ('remove') ............................................. 257

Portlet DynaMent ...................................................................................................... 259

Integrating Portlet Content ('include') .................................................................... 259

Maximizing Portlets ('maximize') ........................................................................... 261

Removing Portlet Instances from Sessions ('remove') ............................................ 262

Process DynaMent .................................................................................................... 264

Restarting Processing with Child Elements ('forward') ........................................... 264

Terminating Processing and Redirecting Request ('redirect') .................................. 265

Restarting Processing Somewhere Else ('break') ................................................... 267

Controlling Processing in for-each Loops ('continue') ............................................ 269

Query DynaMent ....................................................................................................... 270

Creating Search Queries ........................................................................................ 271

Limiting Search Area with Parameter 'searchable' ................................................. 284

Listing Search Engine Indexes ('list') ..................................................................... 286

Entering Simple Search Queries ............................................................................ 287

RDB DynaMent .......................................................................................................... 289

Querying Relational Databases ('query') ................................................................ 289

Updating Relational Databases ('update') ............................................................. 293

Sending Any SQL Statement ('statement') ............................................................. 295

RedDot DynaMent ..................................................................................................... 298

Inserting Edit RedDots ('edit') ................................................................................ 298

Inserting Template RedDots ('template') ................................................................ 299

7

Contents

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reference DynaMent ................................................................................................. 301

Integrating Content References ............................................................................. 301

Setting the Validity of Entries in the Object Cache ('set-scope') ............................. 306

Editing Content Names in the Object Cache ('set-cache-id') ................................... 308

Processing Multipart Requests ('read-multipart') ................................................... 310

Reporting DynaMent ................................................................................................. 313

Reading Browser Properties ('browser') ................................................................. 313

Using Acknowledgement Mechanism ('acknowledge') .......................................... 314

Creating Live Reports ('report') .............................................................................. 316

Predefined Standard Reports ................................................................................ 328

Diagram Types and Parameters ............................................................................. 334

Repository DynaMent ................................................................................................ 341

Reading Content from External Repository ('read') ................................................. 342

Searching External Repository ('query') ................................................................. 348

Creating Content in External Repository ('create') .................................................. 357

Creating Folder in External Repository ('create-folder') ........................................... 363

Updating Content in External Repository ('update') ............................................... 368

Updating Folder in External Repository ('update-folder') ........................................ 374

Deleting Content from External Repository ('delete') .............................................. 378

Deleting Folder from External Repository ('delete-folder') ...................................... 380

Checking Content into External Repository ('checkin') ........................................... 382

Checking Out Content from External Repository ('checkout') .................................. 387

Removing Content Lock ('cancel-checkout') .......................................................... 389

Listing Content Classes/Categories for Content ('list-classes') ............................... 391

Listing Content Classes/Categories for Folders ('list-classes-folder') ..................... 393

Listing Folder Items ('list') ..................................................................................... 395

Script DynaMent ....................................................................................................... 402

Calling Scripts ....................................................................................................... 402

Tagging DynaMent .................................................................................................... 407

Using Tagging and Voting ...................................................................................... 408

Defining Tags ('defineTags') .................................................................................. 409

Reading Tags ('getTags') ....................................................................................... 412

Deleting Tags ('deleteTags') .................................................................................. 415

Renaming Tags ('renameTag') ............................................................................... 419

Assigning Tags ('assignTags') ................................................................................ 420

Deleting Tag Assignments ('unassignTags') ........................................................... 424

8

Contents

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Suggesting Tags ('suggestTags') ........................................................................... 427

Reading Tag Assignments ('getAssignments') ........................................................ 429

Reading Assigned Tags ('getAssignedTags') .......................................................... 436

Reading Assigned Target Objects ('getTargets') ..................................................... 440

Consolidating Tagging Data ('consolidateData') .................................................... 447

Providing Consolidated Tagging Data ('getConsolidatedData') .............................. 453

Deleting Consolidated Tagging Data ('deleteConsolidatedData') ........................... 459

Target DynaMent ....................................................................................................... 461

Selectively Accessing Content ('select') ................................................................. 461

User DynaMent ......................................................................................................... 474

Using the User DynaMent ...................................................................................... 475

Example: Forcing Password Change at Logon ........................................................ 477

Reading Data of Active Users ('session') ................................................................ 482

Determining User's Logon Details ('session-check') ............................................... 485

Logging On Users ('login') ..................................................................................... 487

Logging On Users Without Password ('login-trusted') ............................................ 492

Logging Off Users ('logout') ................................................................................... 493

Verifying Existence of Users ('exists') .................................................................... 496

Deleting Users ('delete') ........................................................................................ 498

Creating Users ('create') ........................................................................................ 499

Loading Users to Active Sessions ('load') .............................................................. 502

Updating Users ('update') ..................................................................................... 506

Editing Group Assignment of Users ('groups') ........................................................ 509

Reading Properties of Selected Users ('report') ...................................................... 514

WebComponent DynaMent ....................................................................................... 523

Integrating Web Components ('include') ............................................................... 523

Reading Instances of Current Sessions ('session') ................................................. 526

Remove Instances from Session ('remove') ........................................................... 527

Integrating CSS Style Sheets from Web Components ('include-css'). ..................... 528

WebService DynaMent .............................................................................................. 531

Calling Web Services ............................................................................................. 531

Receiving and Processing Attachments ................................................................. 540

Wrapper DynaMent ................................................................................................... 543

Calling Content in New Environments .................................................................... 543

Example of a News Wrapper .................................................................................. 544

9

Contents

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Appendix ............................................................................................................ 547

Predefined Attributes and Placeholders .................................................................... 548

Predefined Attributes for source='request' ............................................................ 548

Predefined Attributes for source='session' ............................................................ 553

Predefined Attributes for source='content' ............................................................ 555

Predefined Attributes for source='user' ................................................................. 557

Predefined Attributes for Source 'user' for Loaded Users ....................................... 558

Predefined Attributes for source='system' ............................................................. 560

Predefined Placeholders ....................................................................................... 561

Syntax of Preassigned Placeholders ...................................................................... 564

Predefined XSL Parameters ................................................................................... 567

Inline Functions as Reference .................................................................................... 569

Inline Functions as Reference ................................................................................ 569

Index .................................................................................................................. 576

10

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

About this Manual

The RedDot DynaMents manual provides you with a complete guide to the DynaMents and how they work. It is designed for people responsible for project overview, whose job it is to deliver dynamic and personalized content with the help of the RedDot LiveServer. Using DynaMents you can implement all the essential functions of a dynamic, personalized Web site without being required to do any programming.

The introductory chapter, RedDot DynaMents, contains basic information about DynaMent functions, construction, syntax, editing, standard parameters, and error handling.

The DynaMents are described in alphabetical order in the reference section. Each DynaMent and its respective tasks are described in detail. The parameters available for individual DynaMents are listed and explained. Examples are also provided to illustrate some possible applications of the individual DynaMents.

The appendix to this handbook contains lists with predefined attributes and placeholders, standard functions included and other information for your reference.

Some DynaMents—for example, the Iolet DynaMent—are not part of the basic RedDot LiveServer functions. They are only available with an extra license and are labeled accordingly.

For more information on the actual use of DynaMents in projects, see the RedDot LiveServer Quick Start documentation.

11

About this ManualConventions

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Conventions

The simpler the documentation is, the faster you can acquire essential knowledge and work more professionally with RedDot LiveServer. That is why the following conventions have been set up for this documentation:

Uniform structure

Uniform syntax

Defined symbols

Structure

Descriptions of individual DynaMents or modes will basically follow the structure outlined below. Description of some DynaMents, however, may differ somewhat from this schema:

Task: Short description of a DynaMent or mode function

Syntax: A list of the possible parameters and child elements

Simple call (optional): A typical example of a call with the important parameters

Parameters: Detailed explanation of the individual parameters

Child elements (optional): Detailed explanation of the individual child elements of a DynaMent

Note (optional): Additional information where appropriate/necessary

Result (optional): The results of executing a DynaMent

Error processing: List and meanings of return codes (especially error codes)

Example: Sample DynaMent calls in a given mode

Syntax

The descriptions of individual DynaMents will all have the same syntax to help you get acquainted faster with the material.

Under the heading Syntax you will find a list of all the possible parameters and their values for each DynaMent.

The individual parameter values are listed in quotes. Example: mode ="read"

Where alternate values are possible they will be separated by a vertical bar | and enclosed in square brackets. Example: source ="[user|session|request]"

Where placeholders replace values-which are not value themselves-they will be enclosed in braces. Example: project ="{projectname}"

Descriptions found under the heading Parameter will use the following syntax:

The DynaMents child elements will be displayed as tags in a bold Courier font: <child-element>.

12

About this ManualConventions

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

DynaMent parameters will be displayed in a bold Courier font: parameter.

Values that can be entered for a parameter are displayed in quotes and a courier font: "value".

Symbols

The document contains text passages with warnings, background information, tips, and examples. These various types are indicated by the following symbols:

This symbol indicates a warning that must be taken note of.

This symbol indicates useful background information.

This symbol indicates tips on how to make better use of certain functions.

This symbol alerts you to examples of the described function.

13

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

RedDot DynaMents

The main task of RedDot LiveServer is the personalization, integration, and delivery of content. You can add dynamic structure to the content yourself that will control these tasks. This controlling structure consists of dynamic XML elements called RedDot DynaMents. RedDot developed DynaMents to help you implement these and other functions in a flexible yet easy manner:

Personalization

Content handling

Integration

Dynamic page construction

Generally, you define DynaMents in CMS templates. DynaMents are automatically added to edited content by CMS during the publication process. Going a step further, editors can set up the DynaMent parameters that dynamically control the delivery of content. DynaMents are constructed using XML syntax. But the XML format does not have to be applied everywhere. It is far more a way to extend HTML content by applying an XML DynaMent structure, which makes the interplay of RedDot CMS and RedDot LiveServer very simple and gives editors the ability to directly influence the delivery of personalized content. Almost every RedDot LiveServer project will also contain pure XML content, for example, to manage structured data or create functional modules such as search, targeting, and integration.

This flexible way of working with XML is summed up by the term base data type XML. In this way you can optimally integrate the advantages of HTML with the structural possibilities of XML-especially with respect to rendering via XSL, which allows you to individually modify each project. This is where RedDot LiveServer differs from other Web techniques such as JSP.

Here is a list of other topic discussed in this chapter:

What are DynaMents and which tasks do they perform?

How are DynaMents constructed?

How are DynaMents processed in RedDot LiveServer?

Which standard parameters are used with DynaMents?

How is error handling organized?

How are the most important DynaMent functions used?

14

RedDot DynaMentsWhat Are DynaMents?

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

What Are DynaMents?

RedDot DynaMents are XML elements that you add to content to take advantage of dynamic functionalities for use during content delivery. You can add DynaMents to the following content types: HTML, XML, and XSL. DynaMents are processed at runtime by RedDot LiveServer and the results inserted into the content. You can use a style sheet to render the results or insert them directly into content as dynamic elements. The DynaMents are no longer visible in the delivered content.

In short: In other words, DynaMents are functional calls in XML syntax. They make it possible to access the personalization functions of RedDot LiveServer directly, and therefore constitute the core of projects.

15

RedDot DynaMentsDynaMent Structure

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

DynaMent Structure

This section describes the general structure and syntax of DynaMents.

DynaMents are subject to XML syntax rules and must therefore always start with an opening tag and end with a corresponding closing tag.

The DynaMent tag names contain the declaration of the namespace, rde-dm:, which always precedes the tag name itself.

Each DynaMent contains additional parameters (as XML attributes) which affect DynaMent execution.

Some DynaMents may contain child elements while others may not.

DynaMents can be nested, containing other DynaMents.

In the RedDot CMS Template Editor, DynaMents can be inserted as DynaMent placeholders or as DynaMent block marks.

Attribute DynaMent "read" mode:

<rde-dm:attribute mode="read" attribute="name"

/>

This is an example of an Attribute DynaMent in "read" mode. In this mode, attributes are read out and inserted into the content - in this case, the current value of the user attribute "name." The DynaMent is closed with />.

The DynaMent is executed and replaced by the attribute value while the content is being processed. The result for a user with the name "Miller" would look like this:

<name>Miller</name>

16

RedDot DynaMentsProcessing DynaMents

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Processing DynaMents

A number of steps are involved in the processing of DynaMents, from their insertion in CMS templates through to the delivery of the personalized content. The figure below illustrates the sequence:

Content processing in CMS and RedDot LiveServer to the delivery of personalized pages

1. Entry: DynaMents are inserted in the content either in an external system or in RedDot LiveServer itself. DynaMents can be added to templates in RedDot CMS in the same way as RedDot placeholders and have access to the same dialog support. When pages are published in RedDot CMS, the RedDot placeholders are processed and replaced, but the DynaMents remain in the published page for processing in RedDot LiveServer.

2. Import: RedDot LiveServer imports the published pages to the LiveServer Repository, where all content is stored or referenced.

3. Querying RedDot LiveServer: Each query sent to RedDot LiveServer for rendered content that cannot be supplied by the cache will access the LiveServer Repository, where personalized content is put together.

4. Processing: Requested content is processed by the RedDot DynaMent processor:

First, the content's DynaMent structure is parsed.

Next, the processor executes the DynaMents.

Then it creates a result document-a copy of the content in which the DynaMents are replaced by their resulting values.

DynaMents in the child elements of a DynaMent are also processed.

If the result contains other DynaMents-for example, when additional content is included via an Include DynaMent-their results will generally be processed and added to the content already processed.

DynaMent results can be evaluated during processing by using XPath expressions if the respective DynaMent is identified via the parameter rde-id.

The result is the processed content.

5. Rendering: The processed content will be rendered by the publisher to create the output format (generally HTML). This process makes use of the XSL style sheet contained in the request URL.

6. Delivery: The personalized, rendered content is displayed to the visitor to the Web site. The DynaMents themselves are no longer visible in the published page.

17

RedDot DynaMentsProcessing DynaMents

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

XSL style sheets are created and processed in RedDot LiveServer as XSL type content. XSL style sheets are very well suited for including DynaMents. They will be executed as described in step 4 before the style sheet is applied. XSL is always processed prior to any processing of XML or HTML content.

For Experts: Processing generally takes place in the RedDot LiveServer Application Server components. Exceptions to this rule are DynaMents that create external URL connections, such as the Include DynaMent as Weblet module or the Query DynaMent, which accesses a search engine.

The role of the cache has not been discussed at this point in order to preserve clarity.

Processing Steps Using the Include DynaMent as an Example

Original entry in a RedDot CMS template: <rde-dm:include tag="login"

content="<%target%>" />

Replacement of RedDot placeholders by RedDot CMS after publishing the page: <rde-dm:include tag="login"

content="login.htm" />

Result in RedDot LiveServer after processing the content and executing the DynaMent: <login> content of the file "login.html" </login>

Result in RedDot LiveServer after rendering: Content of the file "login.html"

RedDot DynaMents in the RedDot CMS Template Editor

Beginning with Version 4.5, the Template Editor of the RedDot Content Management Server (CMS) includes two new drop-down lists for inserting RedDot DynaMents as placeholders and block marks. Once you select a DynaMent from these drop-down lists, additional specific dialog windows are displayed in which you can enter the required parameters. This provides you with a simple way of integrating DynaMents into RedDot CMS templates, similar to that used for RedDot placeholders.

The DynaMent placeholders and block marks listed and the dialog windows they open are generated from an XML DynaMent configuration file, which is provided for each project. You will find the accompanying standard file (dynament_declaration.xml) in the following RedDot LiveServer subdirectory: <RedDot Web application path>/WEB-INF/additions/xml/templateeditor/.

18

RedDot DynaMentsUsing the Results

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Using the Results

During processing, DynaMents are normally replaced by their respective result. In general, where the DynaMent was previously located, the processed content now contains a DynaMent result in the form of an XML structure.

You can use DynaMent results in processed content in different ways, or a combination of these.

1. Delivery A DynaMent result can be delivered directly as part of the processed content, without any further processing. The XML structure of the DynaMent result is thus directly visible, e.g., in the form of data for a report.

2. Rendering A DynaMent result can be rendered as part of the processed content (with an XSL style sheet), and delivered. This normally happens with delivery via the Exchange Weblet. You define the style sheet to determine the transformation of the DynaMent result as you require it, e.g., to select or format data, or to control the transformation of other parts of processed content. Exception: Any part of a DynaMent result that is located within a CDATA section cannot be accessed by the XSL style sheet.

3. Reuse in processing with XPath A DynaMent result can also be directly evaluated when processing other DynaMents with the same content. This determines further processing. RedDot LiveServer therefore gives full access to the XPath functionality. There are numerous possible uses. You can simply retrieve a report value from the result of a WebService DynaMent; or extract a list of employees from the result of a personalized database query, and use the Query DynaMent to select and display content assigned to each name. (If your caching setting is adequate, this is a very flexible procedure.)

4. Error Handling The execution of DynaMents may result in internal or external errors, like any other call. You can view the details about these errors in general via the predefined attribute request:rde-rd:dynament-result, or details about individual cases via the DynaMent parameters result-attribute and report-tag. You can use this information to directly influence the processing of other DynaMents via the Attribute DynaMent.

You could say that the first two uses mentioned above describe the basic concept of RedDot LiveServer. For detailed information about the last two uses, please refer to the sections listed here:

See also:

XPath Statements in Parameters (Page 26)Error Handling (Page 33)

19

RedDot DynaMentsVariable Parameter Values

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Variable Parameter Values

You can enter the parameter values for DynaMents in various ways. The following options are available:

Fixed value: You can enter it directly into the CMS template or content.

CMS placeholder: You can enter it directly into the CMS template. This provides your editor with the possibility to influence the personalization rules.

Attribute: You can enter it as any current attribute of the following objects: request, session, user, user group, content, etc. In other words, as any of the attributes available to the Attribute DynaMent.

Values edited using inline functions: You can add additional inline functions via Java methods.

Inline Notation for Parameter Values

By utilizing inline notation, you can include attributes as parameter values for DynaMents. The inline notation is a short form for establishing reading access to attributes. It consists of the following parts:

The source of the attribute It determines whether a request, session, user, user group, content, system, XPath, context, registry attribute, or cookie should be read.

The attribute (attribute name) Can contain a complete hierarchy path.

The index, which determines the position of a value within a value list. Enables direct access to a value in the value list for multivalued attributes.

The defaultvalue (default value) This value will be used if the attribute cannot be found in the given source or if its value is blank.

General Syntax

The general inline notation syntax is:

[#<source>:<attribute>[<index>]#<defaultvalue>#]

Example: [#user:profile.level#5#]

The syntax for (source="content") content attributes can contain additional information. You can use index notation for multivalue attributes. See the information below for more details.

Detailed Information

Everything in bold print is required (i.e., [##])—the rest is optional.

The following <source> values are allowed: "request", "session", "user", "group", "content", "system", "xpath", "context", "cookie", and "registry". They are divided by colons. The default value "user" can be omitted.

20


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

The <attribute> is the name of the called attribute or cookie. With a hierarchical organization of the attributes, the entire attribute path must be given (separated by dots, for example: "profile.favorite"). A hierarchical structure is not possible for attributes with source="request" or "session". You must specify an applicable expression for source="xpath", as described below in section "XPath Statements in Parameters".

The following special features apply to source="content": To address content attributes from a content item other than the active item, you have to specify additional values for project, content, locale policy, and language ahead of the actual attribute name, separated by colons: {project}:{content}:{localepolicy}:{locale}:. You can leave individual elements blank, but you cannot omit them. Example: [#content:lsforum:config.xml::de:locale#] Reads attribute locale from content item config.xml in project lsforum in language de and uses the default locale policy.

When multivalue attributes are used, you can use the index notation to access a targeted value in the value list. To do so, enter the index of the value — that is, the sequence number within the value list — after the attribute name. The notation is <attribute>[<index>]. The index can be any positive integer. Counting starts with the number 1. Example: [#user:profile.level[3]#]. In this example, only the third value from the value list of user attribute profile.level is read.

The <defaultvalue> is used if no value for the attribute can be determined from the <source> or if the value is blank. We recommend using a <defaultvalue>.

You can use one or several inline notation at various locations in DynaMent parameters.

The individual parts of the inline notation (i.e., <source>, <attribute>, and <defaultvalue>) may also contain inline notation themselves: [#request:[#request:name#]#<defaultvalue>#]. The maximum nesting depth is 5.

More information about the inline functions that you can use to supplement the inline notation, as well as the origin of attributes and the source parameter, are contained in separate sections.

Information about read access to attributes using the Attribute DynaMent in "read" mode, as well as about using XPath in parameters, is also contained in separate sections.

For more information, see:

Inline Functions for Parameter Values (Page 29)Multiple Sources: The 'source' Parameter (Page 22)Reading Attributes ('read') (Page 40)XPath Statements in Parameters (Page 26)

21


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Log Entries for Inline Notation

Log entries for the execution of inline notation, including the inline functions, are written to the rde.log log file (in the <RedDot Web application path>/WEB-INF/var/log/ directory). To do so, category 67 (Inline Notation/Functions) must be active in the log settings. This is the default setting.

The amount of data written to the log file depends on the log level that has been set. You can activate and deactivate log categories and log levels in the Set Log Configuration dialog window (Main Menu -> Administer RedDot LiveServer -> Configuration -> Log Configuration -> Configure).

Example: Parameterizing a Database Query

<rde-dm:rdb mode="query"

alias="mysql" sql="SELECT * FROM hotellist WHERE

Cat=[#request:varCategory#0#];"

/>

In this example, an RDB DynaMent is used to submit an SQL query to a database with the name "mysql". The goal is to select hotels from the category that is currently being queried, for example, by an HTML form. The value of the requested category is determined in the URL parameter varCategory or set to the default value, "0".

Multiple Sources: The 'source' Parameter

Attributes and their values play an important role in controlling personalization and in the processing of a RedDot LiveServer application. You can assign attributes to the following object types:

Users

Requests

Sessions

Content items

Systems

User groups

Registry

Responses

Portal instances

Context

22


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

XPath

Cookie

To use an attribute or value of an attribute, you have to declare its source. You do this in DynaMents with the source parameter. In the short syntax of inline notation, you can use a colon to separate the source from the actual attribute name. Each of the object types listed above represents a source value.

source="user" Calls an attribute of the user loaded to the current session. source="user" is the default setting and can be omitted.

For non-anonymous users, the user attributes that have been changed during a session will be stored permanently in the LiveServer Repository at logoff or when a session times out, if nothing else has been configured prior to this. With the Attribute DynaMent in "flush" mode, it is also possible to write the current user attributes of the active session to the repository. Changes to the user attributes in the repository do not affect the attributes of the user loaded to an active session but only new sessions, for which the user is loaded from the repository. For User attributes, there are some predefined names for the predefined functions (see Appendix).

source="request" Calls an attribute of the current request (user request).

Request attributes are generally created as URL parameters directly in the URL or via HTML forms. However, they can also be written via the Attribute DynaMent and are available only while a request is running. Request attributes cannot be organized hierarchically. For Request attributes, there are some predefined names for the predefined functions (see Appendix).

source="session" Calls an attribute of the active session (user session).

Session attributes make it possible to store values during a session independent of specific requests, without permanently saving them to the user. Session attributes are usually written using the Attribute DynaMent and are only available for the life of the session—until logoff or a session timeout. Session attributes cannot be organized hierarchically. For Session attributes, there are some predefined names for predefined functions (see Appendix).

source="content" Calls an attribute of a content item. The content must be declared in other parameters or taken from context.

When using content attributes, keep in mind that content can be used by several parallel sessions at the same time. This means that competing situations can develop when allowing write access to content attributes. Content attributes are thus initially buffered in the proxy for attribute accesses and are then written to the LiveServer Repository asynchronously and in consolidated form.

23


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

For content attributes, there are some predefined names for the predefined functions (see Appendix).

source="system" Calls a system attribute of the RedDot LiveServer runtime environment.

For system attributes of the RedDot LiveServer runtime environment, there are some predefined names for predefined functions (see Appendix). But you can also use the Attribute DynaMent to write your own system attributes. Keep in mind that parallel active sessions use the same attributes. System attributes are not permanently stored in RedDot LiveServer, and they are only visible in the same Java Virtual Machine of a specific server.

source="group" Calls an attribute of the user loaded to the current session not directly assigned to the user itself but one inherited from one of its user groups.

From a technical standpoint, source="group" ensures that the path rde-groupattributes. precedes the actual attribute name, but otherwise it is handled just like source="user".

In order to understand the origin source="group", you need to understand the relationship between the user group attributes and those of the user. This relationship is described in the chapter about users in the Users/Administration manual. To put it simply: User group attributes take precedence. When a user logs on (connects to a session), the attributes of the user group to which the user belongs are loaded. These attributes replace or are added to the user attributes. They can be used like normal attributes during the session with the Attribute DynaMent. To allow high-performance access to the original group attributes, they are also written as write-protected attributes under the path name rde-groupattributes. You can establish transparent access to these attributes by using the source notation source="group".

source="registry" Calls an attribute of the RedDot LiveServer registry.

You can use source="registry" to read registry attributes, for example, connector data. Registry attributes can only be accessed for reading. The full attribute paths are shown in the Administer Registry dialog window (Administer RedDot LiveServer -> System -> Administer Registry).

source="response" Calls an attribute used in the HTTP response (server response to a RedDot LiveServer query) as the name and value of a header field.

Read and write access to the attributes of the response is possible. You can overwrite the default header fields. The reserved attributes set-cookie and status only permit read access.

24


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

source="portalinstance" Calls an attribute of an instance of a portal application in the active session.

Read and write access to the attributes of the portal instance is possible. The written values are only valid for the duration of the session. They are not saved in the registry.

source="context" Calls an attribute that is used within a for-each loop of the Attribute DynaMent.

source="context" is very specific and is described in the section about the Attribute DynaMent in "for-each" mode.

source="xpath" Calls a value that is determined via an XPath expression from the result of a previously processed DynaMent. The DynaMent must be identified via the rde-id parameter. The XPath expression itself is syntactically formulated within the RedDot LiveServer inline notation: [#xpath:{expression}#]. Any XPath expression prefixed by the node selection rde-node is valid. The next section, XPath Expressions in Parameters, describes the use of source="xpath" in detail.

source="cookie" Calls a cookie that was sent in the current request.

Read and write access to the values of cookies is possible. Cookies cannot have multiple values. RedDot LiveServer provides the Servlet API methods for cookies.

For more information on using XPath expressions, see the separate sections.

See also:

Using the Results (Page 19)XPath Statements in Parameters (Page 26)

For more information, see the Appendix:

Predefined Attributes for source='request' (Page 548)Predefined Attributes for source='session' (Page 553)Predefined Attributes for source='content' (Page 555)Predefined Attributes for source='user' (Page 557)Predefined Attributes for source='system' (Page 560)

For more information about attributes of users and user groups, see the Users/Administration documentation.

25


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

XPath Statements in Parameters

With the xpath source notation, you can use XPath expressions to assign attributes and evaluate DynaMent results that have already been processed. There are numerous possible uses. You can simply retrieve a report value from the result of a WebService DynaMent; or extract a list of employees from the result of a personalized database query, and use the Query DynaMent to select and display content assigned to each name.

XPath is a W3C recommendation and defines a language with which you can address and evaluate the data of an XML structure. It contains syntax for describing paths, axes, and attributes, and also contains a series of standard functions (see http://www.w3.org/TR/xpath). Currently RedDot LiveServer uses the XPath implementation by Xalan.

The syntactic application of XPath expressions in RedDot LiveServer uses inline notation, for e, in the value parameter of an Attribute DynaMent:

[#xpath:rde-node( '{node-id}' ){XPath-expression}#{default-value}#]

or

[#xpath:rde-node( '{node-id}', '{node-name}' ){XPath-expression}#{default-

value}#]

Explanation:

node-id Identifies the DynaMent, on whose results the XPath expression should apply. This node-id is a freely definable string, which is entered as the value of the standard parameter rde-id="{node-id}" of the respective DynaMent. The special node-id '.' describes the result of the last DynaMent to be executed. The rde-id parameter does not have to be set in this case.

node-name (optional) The XPath expression is sequentially applied to all the concept elements of the DynaMent result ("nodes" in the XML terminology, not their child elements). In most cases, a DynaMent result consists of a single element, but DynaMent results can also contain several concept nodes (see the example below). If this is the case, the XPath expression is applied several times and the XPath inline notation creates a multivalued attribute (in string form separated by semicolons). By specifying the node name, you limit the application of the XPath expression to the topmost element that has this name.

XPath-expression The actual XPath expression that is applied to the result element. The expression must conform to the XPath recommendations made by W3C as implemented by the executing engine (currently the XPath implementation by Xalan in RedDot LiveServer). A pure XPath expression can deliver various result types (node, node set, number, string, ...). The following applies when using inline notation:

Numbers and Boolean values are transformed into strings

26


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

For a node, its value is determined (analog to value-of in XSLT)

For several nodes, their individual values are determined and all values are returned, separated by semicolons: {value1};{value2};.... You can use the value-separator=";" parameter to convert the result of the XPath expression into a multivalued attribute.

default-value The default value used in case of errors. Errors may occur, for example, if the DynaMent addressed by the node-id cannot be found or does not return a value.

Namespaces DynaMent results can make use of XML namespaces. For example, WebService DynaMent results usually use their own namespaces, which have not been defined in RedDot LiveServer. In order to evaluate an XPath expression, these namespaces have to be declared in the DynaMent, which uses the XPath inline notation. The standard namespaces used by RedDot LiveServer, such as rde-idea, rde-rd, and rde-dm, do not have to be declared.

Nodes and Addressing Modes in XPath

The various types of nodes are:

Elements: Elements have a name, and can contain further nodes. Examples: <path/> or <path id="XXX">hello</path> or <path><a>b</a></path>.

Text: Text or CDATA sections only have one value. One text node is addressed in xpath=/path/text().

Attribute: Element attributes have a name and a value. Attributes sometimes require special handling. The addressing mode is: path/@id

Notes on addressing:

Names can be replaced by the "*" character.

//path finds all elements with the name path. (The double slash (//) means: in the DOM tree; a simple slash (/) means: starting at the root; an entry without a slash means: relative to the context node)

//path/@id addresses all attributes of the path element with the name id.

27


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Evaluating the Result of a User DynaMent with XPath

The following example will help you get acquainted with how to use the logic and syntax. Create test content of type XML in a test project and add the following content information. Release the content and call it using the Exchange Weblet (xchg), unrendered.

<test> <rde-dm:attribute mode="condition" process-mode="execute" rde-id="01"> <rde-dm:constraint>true</rde-dm:constraint> <rde-dm:user report-tag="report" tag="userdata" /> </rde-dm:attribute> message='<rde-dm:attribute attribute="report-value" default="[#xpath:rde-node('01','report')/rde-rd:message/text()#no report-value#]" mode="read" source="request" />' values='<rde-dm:attribute attribute="report-value" default="[#xpath:rde-node('01','userdata')//*/rde-idea:value/text()#]" mode="read" source="request" />'

</test>

In this example, a User DynaMent is executed and the result is evaluated with two XPath expressions. Their results are assigned to attributes, which in turn are displayed in the final result. To give the report and userdata elements unique names, the User DynaMent result is enclosed by a further element that has an rde-id with the help of the Attribute DynaMent.

Example: Appropriate Use of the Result of an XPath Expression if Several Nodes Are Returned/Expected:

<rde-dm:... rde-id="01"/> <rde-dm:attribute mode="write" attribute="test" source="request" value="[#xpath:rde-node('01')//values#???#]" value-

separator=";"/> <rde-dm:attribute mode="for-each" attribute="test" source="request" >

...

</rde-dm:attribute>

This simplified example shows how you can use the value-separator=";" parameter to convert the result of an XPath expression into a multivalued attribute and process the individual values further.

28


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Inline Functions for Parameter Values

You can formulate the inline notation outlined in the section "Inline Notation for Parameter Values" even more flexibly by adding function calls. The value of the expression contained in the inline notation is passed to the respective function and replaced by its return value.

The inline functions allow you, for instance, to format, edit, or check user entries.

The syntax for adding inline functions to the inline notation is given below:

....#].<function>(<parameter list>)

Please note:

The inline function begins with a dot directly behind the closing squared bracket of the inline notation.

This is followed by the name of the inline function and its parameter list, enclosed in parentheses. Multiple parameters within the parameter list are separated using commas. The available inline functions are described in the Appendix.

Spaces within the parameter list will be ignored when the function is processed. The only exception is if they belong to the return value of the inline notation. If there are supposed to be spaces in the parameter values, the values must be in double or single quotation marks (" or '). To prevent a character from being interpreted as a control character, you need to put a backslash (\) before it: The backslash itself is ignored. For example, a comma does not count as a separator for parameter values if there is a backslash before it.

Multiple functions can be used sequentially: [#name#].split('.',2).trim().toLowerCase().

Parameters can also contain inline notation, which again can contain inline functions, for example: [#name#].split([#separator#.#],[#number#]). The nesting depth within parameters is limited to 5 levels.

If the syntax is not correct (for example, no opening or closing parentheses, or the function's name cannot be found), the function will not be executed and thus remains unchanged.

The String type is used for parameter list values that are not numbers or that are enclosed in single quotes ('...'). The Integer type is used for values that can be evaluated as a number.

For your reference, all inline functions are described in the Appendix. You can write your own inline functions in Java to complement those already available. Instructions are provided in the following section.

See also:

Inline Functions as Reference (Page 569)Inline Function: Integrating Your Own Classes (Page 30)

29


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Inline Function: Integrating Your Own Classes

The inline functions described in the Appendix are shipped with the RedDot LiveServer and accessed automatically using a Java class.

To use a different Java class with custom inline functions, you have to specify the name of this class in a hot deployment configuration under type Class for inline functions (with Main Menu -> Java-Based Additions -> Administer Hot Deployment Configurations -> Area: Other classes).

RedDot LiveServer employs the methods of the class by using Java Reflection: The Java method name is also the name of the inline function. All methods that meet the following requirements can be called from the class:

The first parameter is of type String or String Array. The entry is filled with the value from RedDot LiveServer (or value list), that is, either the inline notation value or the return value of the immediately preceding inline function.

All parameters are either of type Integer/int or String.

If the return value is neither a String nor a String Array, the toString() method of the return value is called.

The return value is never null.

The class is thread proof. There is only one object created by this class and it is stored in a static variable.

Instances can be created from the class (not abstract or interface).

Implementing inline functions is easy. Here is an example of how the supplied inline functions substring and decode were implemented:

public String substring(String value, int beginIndex, int endIndex) { return value.substring(beginIndex, endIndex);

}

public String decode(String value) { return URLDecoder.decode( value );

}

This shows you that you can use all means available in Java for inline functions.

See also:

Inline Functions as Reference (Page 569)Inline Functions for Parameter Values (Page 29)

30

RedDot DynaMentsStandard Parameters

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Standard Parameters

Some parameters can be used in different DynaMents to perform the same function. These standard parameters and their meanings are described below. Keep in mind that the default values can be different in each DynaMent if the parameters are not specified explicitly.

mode: The desired sub-function (mode) of the DynaMent in question.

tag: This is the tag name of the XML element that displays the result of the DynaMent. With tag="notag" the result is shown without the enclosing XML element. Note: Using the tag="notag" parameter in XML content after the execution of DynaMents can result in invalid XML when the DynaMent is the root element. Accordingly, you should always use a different element as the root element.

project: The project name contained in and accessed by a DynaMent.

timeout: The longest period of time (in seconds) that will elapse before the processing of a DynaMent is terminated and an error message is sent back. Using a timeout may reduce the performance. Therefore, you should only use it in very important cases.

cachingtime: The maximum time (in minutes) that the processed and rendered content will remain in the component cache. The actual time that content remains in the component cache is determined by the shortest component cache time. If nothing is specified for the parameter, the DynaMent will then normally have no effect on the content's caching time. For DynaMents that use a default caching time if no value has been specified, the default value must be explicitly defined. Certain DynaMents cannot use this parameter (see information below).

roles: Limits to the user roles that the user of the active session must have in order to execute the DynaMent. You can specify multiple alternative roles (separated by semicolons). You can use this parameter in almost all DynaMents. Note: Another way of preventing or restricting the execution of DynaMents is to define DynaMent security rules for a content group or an entire project.

report-tag: Tag name of the XML element with which the return code as well as other information used for the processing the DynaMent is displayed. You can use this parameter in almost all DynaMents.

result-attribute: Path name of a request attribute into which the return code is written after the DynaMent has been executed. If the attribute does not exist, it will be created. The return code can be read by the Attribute DynaMent. You can use this parameter in almost all DynaMents.

rde-id: Freely definable string of characters that identifies the result of the DynaMent during further processing. You can use this parameter in almost all DynaMents. It is evaluated e.g., when accessing a DynaMent result with the XPath notation. DynaMent results marked with rde-id are valid for the entire period of processing.

process-mode: Way in which a DynaMent is processed. You can use this parameter in almost all DynaMents. The following options are possible:

standard (default setting) The DynaMent is processed; its result is included in the processed content.

standard-recursive Like standard, but the result is processed again (it could contain "new" DynaMents).

none The DynaMent is not processed; it is removed from the processed content with any child elements it may have.

31

RedDot DynaMentsStandard Parameters

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

remove The DynaMent is not processed; it is removed from the processed content. Any child elements it may have remain as child elements of its parent element. They are processed consecutively.

execute The DynaMent is processed; its result is not included in the processed content. This mode is useful if you are using the DynaMent only to trigger side effects, for example, an Iolet call, or if the result of the DynaMent is marked with the rde-id parameter, to allow later access with an XPath expression.

ignore The DynaMent and its child elements are not processed; they remain unchanged when a content item is processed. Only the value "ignore" is removed. "You can use ""ignore" with another value for process-mode, using this format: process-mode="ignore;{process-mode}". This mode is used, for example, when importing content via the Content DynaMent.

Please observe the following comments on working with DynaMents:

It is not necessary to set the parameters for which a default value is specified in the description of the DynaMent in question. In this case, the default setting is used.

For some DynaMents (Iolet DynaMent and Script DynaMent, for example), you can use parameters that you have defined yourself. When naming these parameters, make sure that you do not use any predefined parameter or variable names; otherwise they will be overwritten.

DynaMents with "0" Caching Time

For the following DynaMents, the component cache time is always set to "0." The DynaMent prevents content from being placed in the component cache. The standard parameter cachingtime cannot be used in these DynaMents:

Content DynaMent

CPS DynaMent

Message DynaMent

User DynaMent

You can, however, use these DynaMents to cache a complex page by inserting them into special content that you include via the Include DynaMent.

32

RedDot DynaMentsError Handling

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

When executing RedDot DynaMents, errors may occur and warnings or additional information may be produced. Errors occur, for example, as a result of trying to access an external resource that is not available or the desired content cannot be found. For some of these errors you will want to be able to react to them in your project at runtime; others temporarily appear during the development phase of the project and are subsequently used for debugging. Some errors are even planned, so that you can generate information about the project and its users.

RedDot LiveServer provides the following mechanisms to help you flexibly define how you want to react to errors that occur when executing DynaMents:

Return code for request parameters Each execution of a DynaMent provides a number as return code. You can determine the return code of a DynaMent by entering any attribute name in the DynaMent with the result attribute parameter. The return code will then be written as the value of a request attribute with this name and you can read it using the Attribute DynaMent in "read" mode. Codes that are less than zero mean that an error has occurred. If the code is greater than or equal to zero, it means that the DynaMent was executed without errors and provides information on an otherwise successful DynaMent execution. The lower three decimal places of the code are reserved for the description, while the upper places provide information about the DynaMent that created the return code. The meaning of the individual return codes will vary from DynaMent to DynaMent but follows the schema described in the next section.

Collective error code as request parameter Furthermore, every error code created as the result of a DynaMent is written into the request attribute that has the following fixed name: rde-rd:dynament-result. You can read the value for this attribute using the Attribute DynaMent in "read" mode. In this process, the code of a new error will overwrite the code of the previous error. This has the advantage of providing you with a single attribute for determining whether an error took place during the request or not. Generally, you can immediately recognize by the error code which DynaMent caused the last error. For specific information about the individual DynaMent, use the result-attribute parameter described above.

33


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Optional report-tag If you enter the name in the report-tag parameter, the DynaMent will create an XML element in addition to its result. This XML element contains the given tag name whose attribute describes the error or errors. In XML content, you can match this element via XSL and use it for display purposes. The report-tag element contains the original DynaMent in quotes and is constructed as follows: <report-tag code="..." general-code="..."

dynament="..." > <rde-rd:message code="..." general-code="..."

dynament="..." > ... the message ...

</rde-rd:message> <rde-rd:dynament name="..."

... all processed parameters of the calling dynament ... />

<rde-rd:operation-messages> <rde-rd:message level="..." op-pos=".." op-name="..." > ...the message...

</rde-rd:message> <rde-rd:message ... </rde-rd:message> </rde-rd:operation-messages> <rde-rd:details > <rde-rd:detail code="..." general-code="..."

seq="..." type="..." > <rde-rd:level>[Info|Warn|Error|Fatal]</rde-rd:level> <rde-rd:message> ... the message ...

</rde-rd:message> </rde-rd:detail>

</rde-rd:details>

</report-tag> The code contains the entire return code, while the general-code contains the three first decimal places of the code that identify the error type. Generally, you will also see an error message. Rule operation error messages will be output in <rde:rd:message> tags within the <rde-rd:operation-messages> tag.

Log file "rde.log" In addition to these specific mechanisms that allow you to process project errors yourself, you can also use the RedDot LiveServer log file rde.log to analyze your project (in the subdirectory <RedDot Web application path>/WEB-INF/var/log/). To take advantage of this you need to activate the log category 48 (DynaMent processing). The log is divided up into levels: log level 2 (error) contains the errors, log level 3 (warn) contains the warnings, and log level 4 (info) contains all the messages. You can configure the log level and log category settings via a dialog window in RedDot LiveServer (Main Menu -> Administer RedDot LiveServer -> Configuration -> Log Configuration -> Configure), or selectively adjust your settings with the CPS DynaMent.

34


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling with Separate Web and Application Components

Some DynaMents are executed partially or completely on the RedDot LiveServer's Web server components. This is normally the case when during processing, Web services are accessed, e.g., when accessing search engines. If in this situation the connection between the Web and application server components is interrupted, it is possible, for security reasons, to block the services of the latter. Therefore they are executed by the Web server components. Error processing in this case is handled as described above. It takes place however at different times-in other words, after all of the DynaMents have been executed for the queried content on the application server components. Therefore it is not possible to create one query in which the return codes created on the Web server components are queried with DynaMents that are executed on the application server components-even when the DynaMents are ordered sequentially in the content.

Error Processing for Deliveries from Cache

Querying error codes via the Attribute DynaMent only makes sense if you do not retrieve the respective content from the component cache. The reason being that generally the component cache already contains the stored results of the DynaMent, which means that DynaMents are no longer active.

For more information about the cache, see the Users/Administration documentation.

35


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

DynaMent Return Codes

Errors and information DynaMent return codes consist of integers. Here is a description of how to read them:

Codes less than zero indicate an error

Codes greater than or equal to zero indicate information or warnings.

Encoded: Initiating DynaMent The lower three decimal places (ones, tenths, hundredths) of the code refer to the meaning, while the upper places provide information about the DynaMent that created the return code. The individual DynaMents are labeled by the following offsets in the thousands' place in the return code:

The hundreds place digits in the return code have the following meaning:

1 = Error, probably in using the DynaMent. Result available.

3 = Error, probably in using the DynaMent. No result.

5 = Error, probably caused by errors in RedDot LiveServer.

9 = Very critical error, probably caused by a system error.

DynaMent Thousands place

DynaMent Thousands place

Attribute DynaMent 3 Message DynaMent 19

Target DynaMent 4 Portal DynaMent 23

Query DynaMent 5 CPS DynaMent 24

User DynaMent 6 WebService DynaMent

25

Include DynaMent 7 Content DynaMent 26

MetaData DynaMent 8 Repository DynaMent

27

RDB DynaMent 9 Reporting DynaMent 28

Iolet DynaMent 10 Process DynaMent 29

Script DynaMent 11 WebComponent DynaMent

30

Link DynaMent 12 Livelink DynaMent 31

Image DynaMent 13 Cache DynaMent 32

Reference DynaMent 14 Portlet DynaMent 33

Wrapper DynaMent 15 Tagging DynaMent 35

RedDot DynaMent 17

36


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Within these groupings, specific meanings are defined for each DynaMent. In general they follow the divisions outlined below:

Code Description

1 Processing finished with confirmation

2 Processing finished with confirmation; message available

10 Processing stopped; user has none of the requested roles

20 Processing complete with one security rule breach.

100 Processing finished successfully; result negative

110 Processing finished successfully; result positive

11x Processing finished successfully, results have value x

402 Value of the attribute parameter is not an XML name. Use the tag parameter

403 Value of the tag parameter is not an XML name

404 Value of the item-tag parameter is not an XML name

501 Object not found

502 Object not found—no results

503 No session required for processing

510 No user for processing

-1 General error

-2 General error—no results

-30 Defined conditions were not fulfilled

-100 Processing was not successful, result negative

-1xx Processing unsuccessfully completed, results have value xx

-301 Missing parameter

-302 Missing parameter - no result

-311 Wrong parameter

-312 Wrong parameter - No result

-313 Incorrect parameter 'mode'

-314 Incorrect parameter 'mode' - no result

-320 Incorrect parameter 'project' - no result

-513 The object is locked

37

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

DynaMent References

This section describes all the DynaMents in alphabetical order

Attribute DynaMent: Reads and writes user, content, session, and request attributes (metadata) of objects.

Cache DynaMent: Used to control cache processing flexibly during runtime.

Content DynaMent: Used for importing content or content data into LiveServer Repository at runtime, or for deleting content or content data from the LiveServer Repository.

CPS DynaMent: Provides access to RedDot LiveServer system functions.

Image DynaMent: Used to include image data in the delivered page.

Import DynaMent: The Import DynaMent is used to import metadata. The Import DynaMent is not a "true" DynaMent, as it is executed when importing content to the LiveServer Repository, not when processing content. It is, however, addressed using the same syntax as other DynaMents and is therefore called the Import DynaMent.

Include DynaMent: Inserts additional content in a content item at runtime. In addition to internal content items, external pages can also be used, such as JSP or PHP pages. Session and user information for external pages can be transmitted in both directions using this DynaMent.

Iolet DynaMent: Calls Iolets (see Open API), thus permitting the integration of customer-created modules and applications. Available only with the appropriate license.

Link DynaMent: Used to generate validated links in the delivered page.

Link-Param DynaMent: Used to set additional link parameters.

Livelink DynaMent: Enables access to objects on Open Text Livelink Enterprise Server using a repository connector.

Message DynaMent: Makes it possible to send messages (such as e-mails).

MetaData DynaMent: Reads metadata of content items and provides information about content items in a LiveServer Repository.

Portal DynaMent: Communicates with the applications of the application portal. Available only with the appropriate license.

Portlet DynaMent: Addresses integrated portlets through a portlet connector. Available only with the appropriate license.

Process DynaMent: Used to control DynaMent processing.

Query DynaMent: Uses a search engine to deliver search results (Verity search engine included). Available only with the appropriate license.

RDB DynaMent: Makes it possible to exchange data with an external database via SQL.

RedDot DynaMent: Used to prepare content for editing in preview mode and supply the content with the corresponding red dots.

Reference DynaMent: Contains functions for various objects that are called by a reference.

Reporting DynaMent: Controls the recording of data used in reports. Available only with the appropriate license.

38

DynaMent ReferencesError Handling

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Repository DynaMent: Enables data exchange with external repositories. Available only with the appropriate license.

Script DynaMent: Executes scripts for the dynamic display of content.

Tagging DynaMent: Used for automatic keyword creation of content using tags and to make tag clouds.

Target DynaMent: Selects content by matching content attributes and comparison values, for example, user attributes of the current session.

User DynaMent: Used for actions such as registering, logging on and off, and editing and deleting users, as well as for reporting user data (such as user attributes).

Voting DynaMent:

WebComponent DynaMent: Accesses Web Components in RedDot LiveServer.

WebService DynaMent: This DynaMent makes it possible to call a desired Web service. Available only with the appropriate license.

Wrapper DynaMent: Calls up content again in a new environment.

39

DynaMent ReferencesAttribute DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Attribute DynaMent

Attributes and their values contain information you can use to personalize your application. Attributes are available for all major object types in RedDot LiveServer, such as user, content, session and request. You can use the Attributes DynaMent to read, write or edit all of these attributes. The following Attribute DynaMent modes are available:

Read attributes (mode="read")

Write attributes (mode="write")

Verify attributes (mode="condition")

Edit attribute values and subattributes (mode="for-each")

Read attribute values (mode="reference")

Rename attributes (mode="rename")

Copy attributes (mode="copy")

Move attributes (mode="move")

Delete attribute values (mode="delete")

Remove values from the value list of multivalued attributes (mode="remove")

Save user attributes in cookies (mode="flushcookies")

Copy attributes directly to the LiveServer Repository (mode="flush")

Use attribute values as XSL variables for rendering (mode="xslparam")

For attributes from a number of sources (such as source="user"), there are some predefined names for predefined functions (see Appendix).

See also:

Multiple Sources: The 'source' Parameter (Page 22)

For more information see the Appendix:

Predefined Attributes for source='request' (Page 548)Predefined Attributes for source='session' (Page 553)Predefined Attributes for source='content' (Page 555)Predefined Attributes for source='user' (Page 557)Predefined Attributes for source='system' (Page 560)

Reading Attributes ('read')

Purpose

The "read" mode of the Attribute DynaMent lets you read attribute values with various origins. The values read are inserted in the processed content in place of the Attribute DynaMent.

Note: Attribute values (such as passwords) for which you selected the "Display value as asterisks" check box in the RedDot LiveServer GUI will also be displayed as asterisks in the plain text returned by the Attribute DynaMent.

40


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:attribute mode ="read"

attribute ="{attributename}" source ="[user|session|request|

content|system|group|registry| response|portalinstance| cookie|context]"

op ="[parent|xml|cdata|length]" default ="{default value}"

value ="[value|name|path]" value-separator ="{separator}" sortedby ="[index|number|text{,locale}]" sortorder ="[asc|ascending|desc|descending]" content ="{contentname}" project ="{projectname}" cache-content ="[yes|no]" locale ="{locale string}" locale-policy ="[none|default|any]" inline-function ="{function-with-params}"

rule ="{rule name}" runtime ="[no|yes|content]"

item-tag ="[{tagname}|notag]"

/>

The following standard parameters are also available:

tag ="[{tagname}|notag]" cachingtime ="{cachingtime in minutes}" roles ="{userrole1;userrole2}" result-attribute ="{attributename}" report-tag ="{tagname}" rde-id ="{rde-id}" process-mode ="[standard|standard-recursive|

none|remove|execute|ignore]"

Simple Call

<rde-dm:attribute mode="read" attribute="address.name"

/>

Parameters

mode Mode of the Attribute DynaMent, here "read".

attribute (optional) Name of the attribute that is to be read. For source="cookie", the name of the cookie to be read. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). For information about the correct path specification for source="portalinstance", see the information below. If no value or an empty string is specified: value of the default parameter. Note: When multivalued attributes are used, you can use the index notation to access a targeted value in the value list. To do so, enter the index of the value that is, the sequence number within the value list after the attribute name. The notation is attribute="<attribute name>[<index>]". The index can be any positive integer. Counting

41


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

starts with the number 1. Example: attribute="profile.level[3]": In this example, only the third value in the value list is read.

source (optional) Source of the attribute that is to be read. The following options are available:

"user": Attributes of the current user.

"session": Attributes of the active session.

"request": Attributes of the current request.

"content": Attributes of the specified content item.

"system": Attributes of the RedDot LiveServer runtime environment.

"group": Attributes of the specified user group.

"registry": Attributes of the RedDot LiveServer registry.

"response": Attributes from the header fields of the HTTP response.

"portalinstance": Attributes of a portal instance from the active session.

"cookie": Value of a cookie.

"context": Only valid in an Attribute DynaMent when in "for-each" mode. Attribute used in a for-each loop.

If no value is specified: "user"

op (optional) Operator: way in which the attribute value is to be inserted in the processed content.

"parent": The DynaMent is replaced by adding an attribute/value pair {tag}={attributevalue} to the "parent" element of the Attribute DynaMent. In this case, the value for the tag parameter is used as an attribute name in the result. Note: The tag="notag" value is not evaluated in this case; instead, "notag" is used as the tag name.

"xml": The content of the attribute value is returned as an XML tree. If the content is not valid XML, the operator is not evaluated.

"cdata": The content of the attribute value is inserted as a CDATA section.

"length": The number of values in the attribute is calculated and returned.

"{operator}: Deprecated, should no longer be used. The DynaMent is replaced by an XML element without any content and with the attribute/value pairs "{op}" select="'{attributevalue}'". If the value of the op attribute starts with an underscore, then the attribute value is not enclosed in single quotation marks. In this case, the value of the generated name attribute is created without the underscore.

If no value is specified:

If tag="notag" then the attribute value is transferred directly to the result tree.

Otherwise the attribute value is transferred to the result tree as the content of an element with the tag name of the tag attribute.

42


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

default (optional) The value that is to be used if no value can be determined for the attribute. If no value is specified: "" (empty string)

value (optional) Used only for source="context": Specifies which attribute information should be read. The following options are available:

"value": The attribute value is read.

"name": The attribute name is read.

"path": The complete attribute path is read.

If no value is specified: "value"

value-separator (optional) Only used with multivalued attributes: Specification of a separator used between individual values of the attribute. A separator can consist of one or more characters. If the parameter is specified, all the values contained in the attribute's value list will be read and output separated by the specified separator. Note: The parameters value-separator and item-tag are mutually exclusive. If value-separator is used, item-tag is ignored. If no value is specified: no separator. Even if multivalued attributes are specified, only the first value is used.

sortedby (optional) Only used with multivalued attributes: Sort method for value list output. The following options are available:

"index": The values are not sorted. They are output in the same sequence in which they are contained in the value list.

"number": The values are numbers. If one of the values is not a number, all values are interpreted as text. Sequence (for example): 1, 2, 10, 15, 100

"text{,locale}": The values are interpreted as text. Sequence (for example): 1, 10, 100, 15, 2. If you enter a value for the locale (optional), this affects the sort sequence for non-ASCII characters. If you do not specify a locale, the value is set to that of the reddot.locale.default.language key from the system configuration.

If no value is specified: "index"

sortorder (optional, only effective when used together with sortedby) Only used with multivalued attributes: Sort order for the entries:

"asc" or "ascending": ascending order

"desc" or "descending": Descending

If no value is specified: "asc"

content (optional) Used only for source="content": Name of the content. Only required if the content that is to be addressed is not the current content contained in the DynaMent. If names of content items and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

43


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

project (optional) Used only for source="content": Project name. Only required if the content that is to be addressed belongs to a different project than the content in which the DynaMent is located.

cache-content (optional) Used only for source="content": Determines the cache handling of content when reading content attributes.

"yes": Content attributes are read from the entry for a content item in the object cache. If the object is not in the object cache yet, it is loaded into the cache. This procedure minimizes read times for content attributes.

"no": When a content attribute is read, its contents are not loaded into the content cache.

If no value is specified: "yes"

locale (optional) Used only for source="content": Language for which content should be selected. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. The locale parameter affects both the respective content attribute and the output of content data of the selected content. If there is no content data for the selected language in the repository, a replacement language is determined in accordance with the locale policy. This is usually the default project language. If no value is specified: Default project language.

locale-policy (optional) Used only for source="content": Locale policy for accessing content attributes: If an attribute has no value for the language variant determined by the locale parameter, the value for a different variant is read. Possible settings:

"none": If an attribute value is not available in the language you require, no values are read in any other language.

"default": If an attribute value is not available in the language you require, the value for the project default language specified in the project settings is read. If no value is available there either, the value for the default language specified in the system configuration (key: reddot.locale.default) is read. If no value is available in this language, nothing is read.

"any": If an attribute value is not available in the language you require, the value for the project default language is read. If no value is available there either, the value for the default language specified in the system configuration (key: reddot.locale.default) is read. If no value is available in that language, the system searches for and reads the first available value in one of the languages, following the order of languages specified in the project settings.

If no value is specified: The setting from the reddot.xmaps.locale.default.[content type] key of the system configuration is used (see tip below).

inline-function (optional) Specification of a defined inline function. The information consists of the inline function name plus the parameter list, which, depending on the particular function, may be empty. The inline function is applied to each individual attribute value after the attribute is read, so the return value for the inline function

44


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

is effectively used. The inline function is executed prior to the rule (if any) specified in the rule parameter (optional). If no inline function corresponding to the name is found, the system proceeds as if no rule were specified. Please note that when you specify an inline function, the caching function for content in the component cache is only correct if the return value for the function depends exclusively on its parameters, that is, if no variable external information is used.

rule (optional) Name of a defined formatting and validation rule. Consists of the name of a rule, followed by a colon and the language name. If no language name is specified, either the language of the user session or a rule defined without a language name is used. If the rule is defined but not for the required language, the rule is always used without the language definition. The system searches within the project-specific rules first. If no rule is found there, the system rules are searched. If no rule corresponding to the name is found in the global rules, the system responds as if no rule were specified. The rule is applied to each individual attribute value after the attribute is read. The rule is executed after the inline function (if any) specified in the inline-function parameter (optional). The attribute values are also read if the validation result of a rule is not valid. In this case, application of the rule is only cancelled here. The value is read with the successful operations up to the point where the rule was canceled. Please note that when you specify a rule, the caching function for content in the component cache is only correct if the result for the rule depends exclusively on its parameters, that is, if no variable external information is used.

runtime (optional) Defines whether or not access to the attribute in question is added to the dependency list for the component cache. You should only set this parameter in special cases where accessing the attribute will not change the content delivered to other personalized user sessions. As the name implies, the attribute only serves as a runtime attribute.

"no": Add to the dependency list

"yes": Do not add to the dependency list

"content": Although the dependency is entered in the dependency list, if a content-fixed XSL engine is used, it is not transferred from the content item to the dependency list of the content-fixed XSL engine (see the content-fixed parameter of the Include DynaMent).

If no value is specified: "no"

item-tag (optional) Only used with multivalued attributes: Only set for multivalued attributes, in order to make it possible to read and output the entire value list of the attribute. If this parameter is not set, then only the first value of an attribute is output. If the parameter is set, then all the attribute's values are output:

"{tagname}": All the values in the value list are output individually in sequence below this tag name.

"notag": All the values in the value list are concatenated in a string, separated by semicolons, and output in the result.

Note: If value-separator is used, item-tag is ignored.

45


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

tag (optional) This is the tag name of the XML element that displays the results of the DynaMent.

"{tagname}": Explicit specification of tag name.

"notag": The results are listed without the surrounding XML elements.

If no value is specified: Name of the specified attribute.

Results

The Attribute DynaMent is replaced by the returned attribute, based on the specification made for "op" and "tag".

Error handling

The Attribute DynaMent's information, warning, and error messages begin with 3 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="read":

For more information about the "source" parameter, see the separate section.

See also:


You can link any values that are available through the Attribute DynaMent dynamically in the parameter values of DynaMents. This is made possible by special syntax known as inline notation.

See also:

Inline Notation for Parameter Values (Page 20)Inline Functions for Parameter Values (Page 29)Inline Function: Integrating Your Own Classes (Page 30)

Return code Description

-3320 The project was not found

-3501 General error when executing a rule

-3502 Rule was not found

-3503 Execution of the rule failed

-3505 The alias specified in source="context" was not recognized.

3603 Rule completed with Info type message

3605 Rule completed with Warning type message

3607 Rule completed with Error type message

46


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Locale Policy for Content Attributes

If an attribute has no value for the current language variant, the value for a different variant is read, as specified in the Locale policy. The Locale policy is defined for each content type using the configuration parameter in the system configuration (key: reddot.xmaps.locale.default.{content type}. These settings are available:

none: If an attribute value is not available in the language you require, no values are read in any other language.

default: If an attribute value is not available in the language you require, the value for the project default language specified in the project settings is read. If no value is available there either, the value for the default language specified in the system configuration (key: reddot.locale.default) is read. If no value is available in this language, nothing is read.

any: If an attribute value is not available in the language you require, the value for the project default language is read. If no value is available there either, the value for the default language specified in the system configuration (key: reddot.locale.default) is read. If no value is available in that language, the system searches for and reads the first available value in one of the languages, following the order of languages specified in the project settings.

Evaluation of Parameter Values yes/no and true/false

Some parameters of RedDot LiveServer have true and false as possible values, while others have yes and no. As of Version 3.5 of RedDot LiveServer, you can use both true and yes, as well as both false and no. You can use either upper or lower case.

This simplification applies to all areas of RedDot LiveServer. It applies in particular to the parameters of RedDot DynaMents.

Short Notation for Parameters attribute and source

You can use the following short notation to specify the attribute and source parameters in the Attribute DynaMent: attribute="{source}:{attributename}. In this case, the source parameter is ignored.

Example:

<rde-dm:attribute mode="read" attribute="content:rank" />

instead of: ... attribute="rank" source="content" ...

47


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Attribute Paths for Portal Instance Attributes

The attribute path for a portal instance attribute is constructed as follows:

<portal application>:<instance>.<scope>.<attribute name>

Set <scope> to one of the following values:

runtime: The values set at runtime

properties: Configuration data

You can omit the value for the portal instance. In this case, you also leave out the colon after the portal application name.

Examples: reddot:instance.runtime.lasturl

reddot.properties.app-auth-loginurl

Example: Reading a User Attribute

Since the default value for the source parameter is "user", no value is required:

<rde-dm:attribute mode="read" attribute="address.name"

/>

Result for a user named "Mr. Expert":

<address.name>Mr. Expert</address.name>

Example: Reading a Registry Attribute

This attribute describes the returned RDB connector for the hotel database.

<rde-dm:attribute source="registry" mode="read" attribute="reddot.idea.rdb.services.ms-access.description" tag="notag"

/>

Result for the returned database:

Hotel

48


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Function of the tag Parameter

Example 1:

<rde-dm:attribute mode="read" attribute="address.name" tag="username"

/>


<username>Mr. Expert</username>

The result is enclosed by an XML element. The name of this element is specified in the value of the tag parameter.

Example 2:

<rde-dm:attribute mode="read" attribute="address.name" tag="notag"

/>


Mr. Expert

The result is not enclosed by an XML element.

Writing Attributes ('write')

Purpose

The "write" mode of the Attribute DynaMent lets you write attribute values. If no attribute with the specified name exists, it is created. You specify the value (or values) either in parameter value or in the optional child element <rde-dm:value>.

When using content attributes (source="content"), keep in mind that content can be used jointly by several parallel sessions. This means that conflicting situations can develop when allowing write access to content attributes. Content attributes are thus initially buffered in the proxy for attribute accesses and are then written to the LiveServer Repository asynchronously and in consolidated form.

49


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:attribute mode ="write" attribute ="{attributename}" source ="[user|session|request| content|system|response| portalinstance|cookie]" op ="[set|increase|decrease|add| add-list|concat|truncate|length]" value ="{value}" default ="{default value}" content ="{contentname}" project ="{projectname}" locale ="{locale string}" value-separator ="{separators}" delimiters ="{delimiters}" cookie ="{cookie name}" inline-function ="{function-with-params}" rule ="{rule name}" runtime ="[no|yes]" set-readonly ="[false|true]" set-password ="[false|true]" set-nonpersistent ="[false|true]" cookie-domain ="{cookie- domain}" cookie-path ="{cookie path}" cookieduration ="{max. age of cookie (Tage)}" cookie-maxAge ="{max. age of cookie (Sekunden)}" cookie-version ="{cookie version}" cookie-comment ="{cookie comment}" > <rde-dm:value> {value}

</rde-dm:value>

</rde-dm:attribute>

The following standard parameters can also be used:

cachingtime ="{cachingtime in minutes}" roles ="{userrole1;userrole2}" result-attribute ="{attributename}" report-tag ="{tagname}" process-mode ="[standard|standard-recursive|


50


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:attribute mode="write" op="set" attribute="level" value="10"

/>

Alternative

<rde-dm:attribute mode="write" op="set" attribute="level"> <rde-dm:value>10</rde-dm:value>

<rde-dm:attribute>

The value of user attribute level is set to 10 in both cases.

Parameters

mode Mode of the Attribute DynaMent, here "write".

Attributes Name of the attribute that is to be addressed. For source="cookie", the name of the cookie to be addressed. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). For details on the correct path specification for source="portalinstance", see the information below. Note: When attributes are used, you can use the index notation to access a targeted value in the value list. To do so, enter the index of the value — that is, the sequence number within the value list — after the attribute name. The notation is attribute="<attribute name>[<index>]". The index can be any positive integer. Counting starts with the number 1. Example: attribute="profile.level[3]": In this example, only the third value in the value list is addressed.

source (optional) Source of the attribute that is to be addressed. The following options are available:








"cookie": Value of a cookie. Note: Cookies cannot have multiple values.

Value if nothing is specified: "user"

op (optional) Operator, the way in which the specified attribute is to be influenced. The following options are available:

"set": All attribute values are replaced by the value from value. If an index is specified in the attribute parameter, only the value in the specified position is replaced. Examples:

51


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

a,b,c,d set "a" at index 3 => a,b,a,d

a,b,c,d set "a" at index 6 => a,b,c,d,,a

"increase": The first value of the attribute is increased by the specified value. If the attribute value is not an integer, it is interpreted as 0. If the value is not an integer, it is interpreted as 1. If the value is negative, the value of the attribute is decreased. If an index is specified in the attribute parameter, the value in the specified position is increased.

"decrease": The first value of the attribute is decreased by the specified value. If the attribute value is not an integer, it is interpreted as 0. If the value is not an integer, it is interpreted as 1. If the value is negative, the value of the attribute is increased. If an index is specified in the attribute parameter, the value in the specified position is decreased.

"add": The value is appended to the value list for the attribute as another value at the end, provided it is not part of it already. If an index is specified in the attribute parameter, the value is added at the specified position. If the value exist already, it will first be deleted and then added at the specified position. All following values move down accordingly. If the specified index is more than one greater than the index of the last existing value, then missing values are added as empty values. Examples:

a,b,c add "d" at index 2 => a,d,b,c

a,b,c,d,e add "x" at index 8 => a,b,c,d,e,,,x

a,b,c,d add "b" at index 4 => a,c,d,b

"add-list": The value is appended at the end of the attribute value list as an additional value. If an index is specified in the attribute parameter, the value is added at the specified position. If a value already exists in the list, it remains there and is added again at the specified position. Example:

a,b,c,d, add "b" at index 4 => a,c,d,b

"concat": The value is appended to the first value of the attribute as a string. If no value exists yet, this parameter sets it. If an index is specified in the attribute parameter, the value is appended at the specified position.

"truncate": Depending on the value value attribute values are deleted:

If the value parameter is positive: All attribute values that have a higher position than the specified value are removed. Example: If an attribute has five values and value="3", the fourth and fifth attribute values are removed.

If the value parameter is negative: Attribute values are removed, starting from the first value, until - value values are left. Example: If an attribute has five values and value="-2", only the last two values remain.

"length": The number of attribute values from the value parameter is written to the attribute specified under attribute.

Value if nothing is specified: "set"

52


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

value (optional) Value that is to be used for the operation (op). Note for multivalued attributes: You can write value lists for multivalued attributes by entering their values here separated by a delimiter defined in the value-separator parameter. Note: As an alternative to the value and default parameters, you can also specify attribute values in the optional <rde-dm:value> child element. The child element is only evaluated if neither value nor default are specified. If nothing is specified: value of the default parameter.

default (optional) Value used if the value parameter is not specified. If nothing is specified: value from the <rde-dm:value> child element. If nothing is specified there either, the following values are used: For op= "set", "add", "add-list", "concat", "truncate", and "length": "" (empty string) For op="increase" and "decrease": "1"

content (optional) Used only for source="content": Name of the content. Only required if the content that is to be addressed is not the current content in which the DynaMent is located. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).


locale (optional) Used only for source="content": Language for which content should be selected. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. The locale parameter affects both the respective content attribute and the output of content data of the selected content. If there is no content data for the selected language in the repository, a replacement language is determined in accordance with the Locale Policy. This is usually the default project language. Value if nothing is specified: Default project language.

value-separator (optional) Only used with multivalued attributes. Is ignored for the <rde-dm:value> child element. The specification of one or more characters to be used as a separator for the attribute of the value parameter. When entering more than one separator: Enter the chosen characters one right after the other (do not use any other characters to separate the specified characters). Every character you enter will be interpreted as a separator. Spaces cannot be used as separators. If the value parameter is used, its value is divided by the characters specified in value-separator. The operation will then run for each of the identified partial strings. Note: For op="set", the set option is used to assign the first value, after which "add" is used to append any others. Note: No separator will be evaluated if it appears within segments enclosed by text block separators. Text delimiters can be specified as values of the delimiters parameter (see also the example below for information about combining the two parameters). Note: You may not use the same character for the value-separator and delimiters parameters simultaneously, because this will lead to unpredictable results.

53


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

If nothing is specified: No separator will be used.

delimiters (optional) Text block separators for enclosing attribute values. These make it possible for you to use a variety of characters in values, for example, even those defined as separators. The specification of one or more text block separators for attribute values. Enter the characters one right after the other (without spaces or separators). Each character you enter is interpreted as a text block separator. Spaces cannot be used as text block separators. If the first character of an attribute value is one of the characters specified as a text block separator, it will be treated as the opening separator for this value and thus must also close the value. Note: If you want to use double quotation marks (") and backslashes (\) as text delimiters, you have to model them as an escape sequence—that is, with a leading backslash (example: delimiters="\""). Note: You may not use the same character for the value-separator and delimiters parameters simultaneously, because this will lead to unpredictable results.

If nothing is specified: No text block separator is used.

cookie (optional) Used only for source="user": Specify a cookie name. The attribute is written to the User attributes, and also connected to the cookie name specified here, provided your browser allows this. With the aid of an additional Attribute DynaMent in "flushcookies" mode, it is possible to send the connected User attributes to the client as cookies (see also "flushcookies" mode). Advantage: several cookies can be written simultaneously. The User attributes saved in the cookies are automatically read by RedDot LiveServer when a new user is loaded into a session with this browser. Requirement: The "Allow modification of cookies with Attribute DynaMent" check box must be selected in the project settings (Main Menu -> Select Project -> Edit Project Settings -> Users area). Note: You can assign the same cookie name to several user attributes. This does not mean that a cookie is created for every attribute but that all attribute value pairs will be stored in a cookie and that the respective attributes will be automatically created when the respective cookie is detected.

inline-function (optional) Specification of a defined inline function. The information consists of the inline function name plus the parameter list, which, depending on the particular function, may be empty. The inline function is applied to the attribute value before the attribute is written, so effectively the return value for the inline function is written. If the <rde-dm:value> child element is used, the inline function is applied to each specified attribute value individually. The inline function is executed prior to the rule (if any) specified in the rule parameter (optional). If no inline function corresponding to the name is found, the system proceeds as if no rule were specified. Please note that when you specify an inline function, the caching function for content in the component cache is only correct if the return value for the function depends exclusively on its parameters, that is, if no variable external information is used.

rule (optional) Name of a defined formatting and validation rule. Consists of the name of a rule, followed by a colon and the language name. If no language name is specified, either the language of the user session or a rule defined without a language name is used. If the rule is defined but not for the required language, the rule is always used without the language definition. The system searches within the project-specific rules first. If no rule is found there, the system rules are searched. If no rule corresponding to the name is found in the global rules, the system responds as if no rule were specified.

54


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

The rule is applied to the attribute value before the attribute is written. If the <rde-dm:value> child element is used, the rule is applied to each specified attribute value individually. The rule is executed after the inline function (if any) specified in the inline-function parameter (optional). The attribute values are also written if the validation result of a rule is not valid. In this case, application of the rule is only canceled here. The value is written with the successful operations up to the point where the rule was canceled. By querying a return code that is stored in the standard parameter result-attribute, you can, for example, react directly to the result of a rule using the Attribute DynaMent in "condition" mode. Please note that when you specify a rule, the caching function for content in the component cache is only correct if the result for the rule depends exclusively on its parameters, that is, if no variable external information is used.



"yes": Do not add to the dependency list.

Value if nothing is specified: "no"

set-readonly (optional) Used only for source="user"|"system": Determines whether an attribute can be edited. When the DynaMent is executed, the attribute is given the property specified here:

"false": Default setting. Attribute values can be written. The attribute itself can be edited or deleted.

"true": Attribute values can neither be written in the dialogs for editing nor using the Attribute DynaMent. The attribute itself cannot be edited or deleted. This setting is equivalent to selecting the Read only check box in the dialogs for editing attributes.

Value if nothing is specified: "false".

set-password (optional) Used only for source="user"|"system": Defines how attribute values are displayed. When the DynaMent is executed, the attribute is given the property specified here:

"false": Default setting. All characters of attribute values are displayed unencrypted.

"true": All characters of attribute values are displayed as the placeholder "*****". This applies to the display of values in the GUI, in log files, and in projects. Even after processing by an Attribute DynaMent (such as reading), placeholders are shown for these attribute values. This setting is equivalent to selecting the Display value as asterisks check box in the dialogs for editing attributes.


55


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

set-nonpersistent (optional) Used only for source="user"|"system": Defines whether changes to the attribute are saved. When the DynaMent is executed, the attribute is given the property specified here:

"false": Default setting. Changes to the attribute are saved to the LiveServer Repository or a directory service.

"true": The attribute can be edited, but the changes are not written to the LiveServer Repository or a directory service. This setting is equivalent to selecting the Do not store value check box in the dialogs for editing attributes.


cookie-domain (optional) Used only for source="cookie": Value for server, which the cookie sends to the client in format Server:Port. Note: Browsers are not required to accept cookies from domains other than that from the last request. Otherwise the cookie might not be written, due to security issues. We therefore recommend that you do not use this parameter. If nothing is specified: Current server

cookie-path (optional) Used only for source="cookie": Path information for the server to which the client sends the cookie. In most cases, you do not have to set this parameter. Value if nothing is specified: "\"

cookieduration (optional) Used only for source="cookie": Time in days after which a cookie is deleted. You can use this parameter as an alternative to the cookie-maxAge parameter. If nothing is specified: value of the cookie-maxAge parameter.

cookie-maxAge (optional) Used only for source="cookie": Time in seconds after which a cookie is deleted. Note: You can delete a cookie by specifying cookie-maxAge="0". If you delete the value of a cookie, you have to write it again. Value if nothing is specified: "-1": The cookie is only valid for the duration of the session.

cookie-version (optional) Used only for source="cookie": Version of the cookie format, as described in the Servlet API. Value if nothing is specified: "0"

cookie-comment (optional) Used only for source="cookie": Short text comment that describes the cookie.

Child Elements

The Attribute DynaMent in "write" mode has an optional child element called <rde-dm:value>.

You can specify the values to be written in this child element as an alternative to the value and default parameters. The child element is only evaluated if neither value nor default are specified. One advantage of specifying the value in the child element is that it can be

56


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

written to CDATA. DynaMents within values of a child element are processed. Inline notation is not supported, but the inline-function parameter can be used and applied to each individual value. The child element can be used several times.

<rde-dm:value> (optional) You can specify a value to be written for each child element. If you specify several child elements, a multivalued attribute is written. The write operation is applied to each value individually. The set operation is set on the add operation after the first value. The value-separator parameter is ignored.

Result

The DynaMent is removed from the content. The attribute is written.

Error Handling

The Attribute DynaMent's information, warning, and error messages begin with 3 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="write":


See also:


For more information about the "cookie" parameter, see the separate section.

See also:

Saving User Attributes in Cookies ('flushcookies') (Page 91)



-3321 The specified attribute could not be reached (for example, content not found)

-3322 The specified attribute is read-only.

-3332 General error when writing an attribute

-3501 General error when executing a rule

-3502 Rule was not found.

-3503 Execution of the rule failed

3603 Rule completed with Info type message

3605 Rule completed with Warning type message

3607 Rule completed with Error type message

57


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



Example:












<rde-dm:attribute mode="write" op="set" source="user" attribute="level" value="10"

/>

The value of the level attribute is replaced by the value in the result.

58


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example of writing content attributes (source="content")

<rde-dm:attribute mode="write" source="content" attribute="rank" content="content.xml" op="increase" value="1"/>

<rde-dm:attribute mode="flush"/>

The result: The "rank" attribute is incremented for the specified content (content.xml) if the asynchronous process has terminated. Using the Attribute DynaMent in "flush" mode writes the attributes to the repository immediately.

Examples for combining the value-separator and delimiters parameters:

Write the following Attribute DynaMents in your example project, demo, in a page called test.xml:

<rde-dm:attribute mode="write" source="request" attribute="input" value-separator="," delimiters="[#request:delimiters#]" value="[#request:value#]"/> <rde-dm:attribute attribute="input" mode="read" source="request" item-

tag="item"/>

Simple example

Parameters: value= "123","456","789" delimiters= "

Call specifying both parameters: cps/rde/xchg/demo/

test.xml?value=%20%22123%22,%22456%22,%22789%22&delimiters=%20%22

The result: <input> <item>123</item> <item>456</item> <item>789</item>

</input>

Complex example

Parameters: value= 123, 456, "' 789'", "'abc", '"def"', 'g,hi"' delimiters= "'

Call specifying both parameters: cps/rde/xchg/demo/test.xml?value=123,%20456,%20%22'%20789'%22,%20%22'abc%22,%20'%22def%2

2',%20'g,hi%22'&delimiters=%22'

59


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

The result: <input> <item>123</item> <item>456</item> <item>' 789'</item> <item>'abc</item> <item>"def"</item> <item>g,hi"</item>

</input>

60


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Checking Constraints for Attributes ('condition')

Purpose

When you use the Attribute DynaMent in "condition" mode, an attribute condition is compared against a specified value. The dependent output values are either delivered or removed, depending on whether or not the condition is fulfilled. This mode is the default setting for the Attribute DynaMent.

The Attribute DynaMent can be used with or without child elements in "condition" mode. The following child elements are possible: <rde-dm:constraint>, <rde-dm:if> and <rde-dm:else>. With the <rde-dm:constraint> child element, you extend "condition" mode; it lets you specify not only one condition, but also a logical expression that connects multiple conditions. The <rde-dm:if> and <rde-dm:else> child elements let you specify which content is processed if a condition is met, and if it is not met.

Syntax

<rde-dm:attribute mode ="condition" attribute ="{attributename}" source ="[user|session|request|

content|system|group|registry| response|cookie|context]"

op ="[eq|ne|gt|ge|lt|le|contains| (not)containsall|(not)containsany| (not)existsinall|(not)existsinany]"

value ="{value}" default ="{default value}"

content ="{contentname}" project ="{projectname}" locale ="{locale string}" locale-policy ="[none|default|any]"

runtime ="[no|yes]" >

<rde-dm:constraint> {constraint expression}

</rde-dm:constraint>

<rde-dm:if> Content if condition is fulfilled

</rde-dm:if>

<rde-dm:else> Content if condition is not fulfilled

</rde-dm:else>

</rde-dm:attribute>

61


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Simple Call

<rde-dm:attribute attribute="level" mode="condition" op="eq" value="0" tag="notag">

...

</rde-dm:attribute>

Parameters

mode (optional) Mode of the Attribute DynaMent, here "condition". Default setting; can be omitted.

attribute (optional if child element <rde-dm:constraint> is specified) Name of the attribute that is to be read. For source="cookie", the name of the cookie to be read. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). If the specified attribute does not exist or the attribute value is blank, the value of the default parameter is used. Note: When multivalued attributes are used, you can use the index notation to access a targeted value in the value list. To do so, enter the index of the value that is, the sequence number within the value list after the attribute name. The notation is attribute="<attribute name>[<index>]". The index can be any positive integer. Counting starts with the number 1. Example: attribute="profile.level[3]": In this example, only the third value in the value list is read.











"context": Only valid in an Attribute DynaMent when in "for-each" mode. Attribute used in a for-each loop.

62


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


op (optional if child element <rde-dm:constraint> is specified) Operator, method used to compare the specified attribute with the value. If an index is specified in the attribute parameter for multivalued attributes, the value in that position is compared with the comparison value from value. Be aware of the sometimes varying treatment given to attributes with one or more values. The following options are available:

"eq" (equals): Checks whether the attribute value and the comparison value of the value parameter are equal.

"ne" (not equal): Checks whether the attribute value and the comparison value of the value parameter are not equal.

"gt" (greater than): Checks whether the attribute value is greater than the comparison value from the value parameter.

"ge" (greater equal): Checks whether the attribute value is greater than or equal to the comparison value from the value parameter.

"lt" (less than): Checks whether the attribute value is less than the comparison value from the value parameter.

"le" (less equal): Checks whether the attribute value is less than or equal to the comparison value from the value parameter.

"contains": Checks whether the value parameter's comparison value is present in the attribute's value. Other values of multivalued attributes will not be evaluated.

"containsall/notcontainsall": For value lists of multivalued attributes: Checks whether all comparison values from value are contained in the attribute values. To negate the statement, use the "not" prefix. Note: The index notation in the attribute parameter is ignored.

"containsany/notcontainsany": For value lists of multivalued attributes: Checks whether at least one comparison value of the value parameter is contained in the attribute values. To negate the statement, use the "not" prefix. Note: The index notation in the attribute parameter is ignored.

"existsinall/notexistsinall": For value lists of multivalued attributes: Checks whether all attribute values are contained in the comparison values of value. To negate the statement, use the "not" prefix. Note: The index notation in the attribute parameter is ignored.

"existsinany/notexistsinany": For value lists of multivalued attributes: checks whether at least one attribute values contained in the comparison values of value. To negate the statement, use the "not" prefix. Note: The index notation in the attribute parameter is ignored.

value (optional) Value that is to be used for the operation (op). For value lists of multivalued attributes: The individual values are separated by semicolons. If no value is specified: "" (empty string)

default (optional) The value that is to be used if no attribute value can be determined. Note: We recommend entering a default value. You should choose a default value that does not fulfill the condition if it is used.

63


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

If no value is specified: "" (empty string) or If no value is specified: "0" if value is a number and one of the following operators is used: "eq", "ne", "gt", "ge", "lt", "le". As a result, if an attribute does not exist and a default value is not defined, the condition is fulfilled with op="eq" and value="0", for example.

content Used only for source="content": Name of the content. Required even if the content that is to be addressed is the current content contained in the DynaMent. If names of content items and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

project (optional) Project name for source="content". Only required if the content that is to be addressed belongs to a different project than the content in which the DynaMent is located.






If no value is specified: The setting from the reddot.xmaps.locale.default.[content type] key of the system configuration is used (see tip below).


64


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


"yes": Do not add to the dependency list.






Child elements

The Attribute DynaMent in "condition" mode has several possible child elements. DynaMents within values of child elements are not processed. Inline notation is supported in the <rde-dm:constraint> child element.

<rde-dm:constraint> (optional if the following parameters are specified: attribute, op, and value) Expression that can consist of several conditions connected by logical operators (AND, OR, NOT) and parentheses. If the whole expression is met, the dependent output values are delivered. When you use this child element, you need not specify the parameters attribute, op and value

A single constraint consists of: operand operator operand.

Operator: Identifies the operators used to link the operands. All operators for the op parameter are permitted (see above). Operators are not case-sensitive.

Operand: Comparison values linked by operators to form a constraint. You can use simple values, attributes, or inline notations as operands.

Value: String that is enclosed in single or double quotation marks, or a number (integer). To prevent quotation marks within a string being interpreted as control characters, precede them with a backslash (for example, "\""). The backslash itself is ignored.

Attribute: Consists of source:attributepath. The source (along with the ":" separator) is optional. If no value is specified, source=user. Any RedDot LiveServer source is permitted. "content", "xpath", and "context" are replaced with their current values. They are not supported in the evaluation of the component cache.

Inline notation: Inline notations as they are used in DynaMents, including all functionalities such as inline functions. Any RedDot LiveServer source is permitted. "content", "xpath", and "context" are replaced with their current values. They are not supported in the evaluation of the component cache.

Logical operators: The following logical operators can be used to link multiple constraints. When using brackets to clarify the processing sequence, make sure that you use parentheses.

AND: AND operator for conditions

65


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

OR: OR operator for conditions

NOT: Negation for conditions

Note:

Parts of an <rde-dm:constraint> expression that are not well-formed must be enclosed in CDATA sections.

Only the necessary parts of an <rde-dm:constraint> expression are evaluated.

<rde-dm:constraint> expressions must not contain DynaMents, because they are not processed.

You can specify multiple <rde-dm:constraint> elements. These must follow each other. If all constraints are met, the dependent output values are delivered.

<rde-dm:if> (optional) For content that is processed if the condition is fulfilled.

<rde-dm:else> (optional) For content that is processed if the condition is not fulfilled.

Notes

The if/else procedure is triggered only if the Attribute DynaMent has exactly one of the two child elements (or both in the exact if/else sequence).

Results

The DynaMent is processed if the condition is fulfilled or when a child element is processed. The results are handled as follows:

If tag="notag", they are transferred directly to the result tree.

Otherwise they are transferred to the result tree as child elements of an element with the tag name of the tag attribute.

If the condition is not fulfilled or a child element is not processed, then the Attribute DynaMent and its child elements are not displayed in the result tree.

If an error occurs, an appropriate error message is shown.

Error handling

The Attribute DynaMent's information, warning, and error messages begin with 3 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="condition":


-3320 Project was not found.

-3504 Parsing of a constraint child failed.

-3505 The alias specified in source="context" was not recognized.

66


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


See also:

Multiple Sources: The 'source' Parameter (Page 22)Inline Notation for Parameter Values (Page 20)Inline Functions for Parameter Values (Page 29)

For more information about inline notation and inline functions, see the separate sections.

<rde-dm:attribute mode="condition" source="request" attribute="value1" op="eq" value="[#request:value2#0#]" tag="notag"> ...

</rde-dm:attribute>

This example checks whether "value1" is equal to "value2" in the current request. If there is no current value for "value2" then the default value "0" is used. The result depends on whether or not the condition is fulfilled. The content that is enclosed by the DynaMent is displayed when the values are equal.

Use of the <rde-dm:constraint> child element:

<rde-dm:attribute mode="condition" > <rde-dm:constraint>

(user:profile.interest EQ 'sport' OR user:profile.interest EQ 'literatur')

AND user:profile.age LT 40 AND (content:countries containsany user:interest.countries)


<rde-dm:if> ... Content ...

</rde-dm:if> <rde-dm:else>

... Content ... </rde-dm:else>

</rde-dm:attribute>

The attribute, op and value parameters are omitted here, as they are not required for use of the <rde-dm:constraint> child element.

Within the <rde-dm:constraint> expression, several constraints are linked: The user attribute profile.interest must have either "sport" or "literature" as its value. In addition, the value for the profile.age user attribute must be less than 40. At the same time, the multivalued attribute countries must contain at least one value for the interest.countries user attribute. If all conditions are met, the content enclosed by the <rde-dm:if> child element is delivered. If one of the conditions is not met, the content enclosed by the <rde-dm:else> child element is delivered.

67


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



Example:



Locale Policy for Content Attributes

If an attribute has no value for the current language variant, the value for a different variant is read, as specified in the Locale policy. The Locale policy is defined for each content type using the configuration parameter in the system configuration (key: reddot.xmaps.locale.default.{content type}. These settings are available:

none: If an attribute value is not available in the language you require, no values are read in any other language.

default: If an attribute value is not available in the language you require, the value for the project default language specified in the project settings is read. If no value is available there either, the value for the default language specified in the system configuration (key: reddot.locale.default) is read. If no value is available in this language, nothing is read.

any: If an attribute value is not available in the language you require, the value for the project default language is read. If no value is available there either, the value for the default language specified in the system configuration (key: reddot.locale.default) is read. If no value is available in that language, the system searches for and reads the first available value in one of the languages, following the order of languages specified in the project settings.

68


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Making Attribute Values or Child Attributes Available ('for-each')

Purpose

The Attribute DynaMent in "for-each" mode lets you make each value of a multi-value attribute available for editing. Attributes can contain multiple values. You can use the "add" operator in "write" mode of the Attribute DynaMent, for example, to add another value to the value list of an attribute.

The type="children" parameter lets you make child attributes of an attribute available for editing.

Syntax

<rde-dm:attribute

mode ="for-each"

attribute ="{attributename}" source ="[user|session|request|content|

system|group|registry|response| portalinstance|cookie]"

type ="[multivalue|children"] alias ="{attributename}" sortedby ="[index|number|text{,locale}]" sortorder ="[asc|ascending|desc|descending]" content ="{contentname}" project ="{projectname}" cache-content ="[yes|no]"

locale ="{locale string}" locale-policy ="[none|default|any]"

/>




Parameters

mode Mode of the Attribute DynaMent, here "for-each".

attribute (optional for type="children") Name of the attribute that is to be read. For source="cookie", the name of the cookie to be read. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). For information about the correct path specification for source="portalinstance", see the information below.

If no value or an empty string is specified for type="children": All attributes of the top hierarchy level of the relevant source are read.

69


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8













type (optional) Information about which data will be provided. The following options are available:

"multivalue": Values of a multivalued attribute are provided.

"children": The child elements of an attribute are provided.

If no value is specified: "multivalue"

alias (optional) Alias name of the attribute for the source parameter with the value "context". The current value of the parameter's attribute or its child elements is determined by each consecutive for-each loop (in no specific order). If no value is specified: Name of the attribute.

sortedby (optional) Sort method for value list output. The following options are available:

"index": The values are not sorted. They are output in the same sequence in which they are contained in the value list.

"number": The values are numbers. If one of the values is not a number, all values are interpreted as text. Sequence (for example): 1, 2, 10, 15, 100

"text{,locale}": The values are interpreted as text. Sequence (for example): 1, 10, 100, 15, 2. If you enter a value for the locale (optional), this affects the sort sequence for non-ASCII characters. If you do not specify a locale, the value is set to that of the reddot.locale.default.language key from the system configuration.

If no value is specified: "index"

sortorder (optional, only effective when used together with sortedby) Sort order for the entries:



If no value is specified: "asc"

70


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



cache-content (optional) Used only for source="content": Determines the cache handling of content when reading content attributes.

"yes": Content attributes are read from the entry for a content item in the object cache. If the object is not in the object cache yet, it is loaded into the cache. This procedure minimizes read times for content attributes.

"no": When a content attribute is read, its contents are not loaded into the content cache.







71


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

If no value is specified: The setting from entry reddot.xmaps.locale.default.[content type] of the system configuration is used.




If no value is specified: The name of the attribute in the attribute parameter. If no attribute or a blank value is specified there, the default value for tag is "notag".

Notes

To access the current value of the attribute/child elements, there is a source parameter with value "context" that is only valid within a for-each loop. You can use this parameter with the Attribute DynaMent in "condition" or "read" mode. You can nest additional for-each loops within a for-each loop, but you can only use the name of the alias parameter once each time. Changes to the attributes within a for-each loop do not affect the remainder of the value list that is waiting to be processed.

Results

The Attribute DynaMent is processed for each value of a multivalued attribute or its child elements in a sequential loop. These values can then be processed further, for example, using the Attribute DynaMent in "read" or "condition" mode. You can use the Attribute DynaMent in "read" mode to output them in a list, for example.

Error handling

The Attribute DynaMent's information, warning, and error messages begin with 3 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="for-each":


See also:


Controlling Processing in for-each Loops ('continue') (Page 269)


-3351 Attribute name is already in use

72


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



Example:












<rde-dm:attribute mode="for-each" attribute="companies" source="user" alias="company"> <rde-dm:attribute mode="read" attribute="company" source="context"/>

</rde-dm:attribute>

In the above example, the multi-value attribute "companies" is supposed to have three values: RedDot Solutions, Microsoft, SAP. The Attribute DynaMent is used in "read" mode to read the values in sequence. In the process, the source="context" parameter, which is only valid here, is used to access the current attribute value in every for-each loop.

73


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result in XML:

<companies> <company>RedDot Solutions</company> <company>Microsoft</company> <company>SAP</company>

</companies>

Example: Using the parameter type="children"

<rde-dm:attribute mode="for-each" source="request" attribute="attribute" type="children" alias="alias"> <rde-dm:attribute mode="condition" source="context"

attribute="alias" op="gt" value="5"> <rde-dm:if>if</rde-dm:if> <rde-dm:else>else</rde-dm:else>

</rde-dm:attribute>

</rde-dm:attribute>

With the Attribute DynaMent in mode "for-each", the child elements of this attribute are added to the alias parameter (in no specific order). An Attribute DynaMent in mode "condition" checks a child of the current attribute to see if its value is greater than 5. In the process, the source="context" parameter, which is only valid here, is used to access the current attribute value in every for-each loop. Depending on the results, the contents of the child elements <rde-dm:if> and <rde-dm:else> may differ.

Example: Listing the registered classes of the operations from the registry:

<rde-dm:attribute mode="for-each" attribute="registry:reddot.idea.operations" alias="parent" type="children"> <rde-dm:attribute mode="read" tag="notag" attribute="parent" source="context" value="path"/> <rde-dm:attribute mode="read" tag="notag" attribute="parent" source="context"/>

</rde-dm:attribute>

74


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Referencing Attributes ('reference')

Purpose

In "reference" mode, the Attribute DynaMent does not integrate personalized attribute values into a content item directly, but instead as references using a placeholder. The placeholder is added to the component cache. This placeholder is replaced with the current value of the attribute only after the content is delivered from the cache. So even with personalization, it is possible to take advantage of component cache performance, without having to store numerous variants in the component cache. This mode is not available for XSL content.

Syntax

<rde-dm:attribute

mode ="reference"

attribute ="{attributename}" source ="[user|session|request|

content|system|group| registry|response|cookie]" default ="{default value}" content ="{contentname}" project ="{projectname}" locale ="{locale string}" locale-policy ="[none|default|any]"

inline-function ="{function-with-params}" />




Parameters

mode Mode of the Attribute DynaMent, here "reference".

attribute (optional) Name of the attribute that is to be read. For source="cookie", the name of the cookie to be read. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). If no value or an empty string is specified: value of the default parameter.






75


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8







default (optional) The value of the referenced placeholder to be used if no value can be determined for the attribute. If no value is specified: "" (empty string)






76


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



If no value is specified: The setting from the key reddot.xmaps.locale.default.[content type] of the system configuration is used.

inline-function (optional) Specification of a defined inline function. The information consists of the inline function name plus the parameter list, which, depending on the particular function, may be empty. The inline function is applied to the returned attribute value. If no inline function corresponding to the name is found, the system proceeds as if no rule were specified.





Results

The Attribute DynaMent is replaced by the read attribute.

Error handling

The Attribute DynaMent's information, warning, and error messages begin with 3 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".


See also:

Multiple Sources: The 'source' Parameter (Page 22)Predefined Placeholders (Page 561)Syntax of Preassigned Placeholders (Page 564)

77


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



Example:



Renaming Attributes ('rename')

Purpose

With the "rename" mode of the Attribute DynaMent, you can rename attributes from various sources, provided write access is allowed.

Note: From a technical standpoint, renaming an attribute involves copying and then deleting the original attribute. Some attributes that are generated automatically, such as the user fields in the user:rde-fields attribute tree, cannot be moved.

Syntax

<rde-dm:attribute mode ="rename" attribute ="{attributename}" source ="[user|session|request|

content|system|response]" content ="{contentname}" project ="{projectname}" locale ="{locale string}"

name ="{attributename}"

/>




78


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:attribute

mode="rename" attribute="address.name" name="surname" />

User attribute address.name is renamed as address.surname.

Parameters

mode Mode of the Attribute DynaMent, here "rename".

attribute Name of the attribute to rename. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index").

source (optional) Source of the attribute. The following options are available:











79


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

name New name for the attribute after renaming. The attribute name is specified without the attribute path.

Results

The specified attribute is copied as an attribute with the name specified in parameter name and then deleted. When an attribute is copied, its values and all its child elements and their values are copied (child elements are copied recursively). If one of the target attributes already exists, its existing values are deleted and overwritten with the copied values. If the target attribute contains child elements that are not present in the source attribute, these child elements are not changed.

Error handling


Copying Attributes ('copy')

Purpose

With the "copy" mode of the Attribute DynaMent, you can copy attributes from various sources, provided read access is allowed. The copied target attribute can have a different source. Target attributes can be any attributes that permit write access.

Notes: From a technical standpoint, copying an attribute creates an attribute with a new name. If an attribute with this name already exists, it is deleted beforehand. Some attributes that are generated automatically, such as the user fields in the user:rde-fields attribute tree, cannot be copied.

Syntax

<rde-dm:attribute mode ="copy" attribute ="{attributename}" source ="[user|session|request|

content|system|group|registry| response|cookie]"

content ="{contentname}" project ="{projectname}" locale ="{locale string}"

targetattribute ="{attributename}" targetsource ="[user|session|request|

content|system|response|cookie]" targetcontent ="{contentname}" targetproject ="{projectname}" targetlocale ="{locale string}"

/>

80


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Simple Call

<rde-dm:attribute mode="copy" source="user" attribute="address.emails.office" targetsource="session" targetattribute="contacts.email"

/>

User attribute address.emails.office is copied as a session attribute with the name contacts.email.

Parameters

mode Mode of the Attribute DynaMent, here "copy".

attribute Name of the attribute to copy. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index").

source (optional) Source of the attribute to copy. The following options are available:












81


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



targetattribute Name of the target attribute. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). Notes: Enter the name (and path, if necessary) of the target attribute itself, not the parent attribute into which the source attribute is copied as a childlike a type of directory. The target attribute cannot be a child of the attribute you want to move, nor can it be identical to that attribute. An error message is displayed in both of these cases.

targetsource (optional) Source of the target attribute. The following options are available:









targetcontent (optional) Used only for source="content": Name of the content. Only required if the content that is to be addressed is not the current content contained in the DynaMent. If names of content items and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

targetproject (optional) Used only for source="content": Project name. Only required if the content that is to be addressed belongs to a different project than the content in which the DynaMent is located.

targetlocale (optional) Used only for source="content": Language for which content should be selected. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. The locale parameter affects both the respective content attribute and the output of content

82


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

data of the selected content. If there is no content data for the selected language in the repository, a replacement language is determined in accordance with the locale policy. This is usually the default project language. If no value is specified: Default project language.

Results

The specified attribute is copied as an attribute with the name specified in parameter targetattribute. The source notation of the target attribute is defined in parameter targetsource. When an attribute is copied, its values and all its child elements and their values are copied (child elements are copied recursively). If one of the target attributes already exists, its existing values are deleted and overwritten with the copied values. If the target attribute contains child elements that are not present in the source attribute, these child elements are not changed.

Error handling


Moving Attributes ('move')

Purpose

With the "move" mode of the Attribute DynaMent, you can move attributes from various sources, provided write access is allowed. The copied target attribute can have a different source. Target attributes can be any attributes that permit write access.

Note: From a technical standpoint, moving an attribute involves copying and then deleting the original attribute. Some attributes that are generated automatically, such as the user fields in the user:rde-fields attribute tree, cannot be moved.

Syntax

<rde-dm:attribute mode ="move" attribute ="{attributename}" source ="[user|session|request|

content|system|response]" content ="{contentname}"

project ="{projectname}" locale ="{locale string}"

targetattribute ="{attributename}" targetsource ="[user|session|request|

content|system|response|cookie]" targetcontent ="{contentname}"

targetproject ="{projectname}" targetlocale ="{locale string}"

/>

83


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Simple Call

<rde-dm:attribute mode="move" attribute="address.name" targetattribute="address.name"

targetsource="session />

User attribute address.name is copied to session attribute address.name and then deleted.

Parameters

mode Mode of the Attribute DynaMent, here "move".

attribute Name of the attribute to move. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index").

source (optional) Source of the attribute to move. The following options are available:










locale (optional) Used only for source="content": Language for which content should be selected. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. The

84


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

locale parameter affects both the respective content attribute and the output of content data of the selected content. If there is no content data for the selected language in the repository, a replacement language is determined in accordance with the locale policy. This is usually the default project language. If no value is specified: Default project language.

targetattribute Name of the target attribute. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). Notes: Enter the name (and path, if necessary) of the target attribute itself, not the parent attribute into which the source attribute is moved as a childlike a type of directory. The target attribute cannot be a child of the attribute you want to move, nor can it be identical to that attribute. An error message is displayed in both of these cases.

targetsource (optional) Source of the target attribute. The following options are available:









targetcontent (optional) Used only for source="content": Name of the content. Only required if the content that is to be addressed is not the current content contained in the DynaMent. If names of content items and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

targetproject (optional) Used only for source="content": Project name. Only required if the content that is to be addressed belongs to a different project than the content in which the DynaMent is located.

targetlocale (optional) Used only for source="content": Language for which content should be selected. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. The locale parameter affects both the respective content attribute and the output of content data of the selected content. If there is no content data for the selected language in the repository, a replacement language is determined in accordance with the locale policy. This is usually the default project language. If no value is specified: Default project language.

85


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Results

The specified attribute is copied as an attribute with the name specified in parameter targetattribute and then deleted. The source notation of the target attribute is defined in parameter targetsource. When an attribute is copied, its values and all its child elements and their values are copied (child elements are copied recursively). If one of the target attributes already exists, its existing values are deleted and overwritten with the copied values. If the target attribute contains child elements that are not present in the source attribute, these child elements are not changed.

Error handling


Removing Attribute Values from the Value List ('remove')

Purpose

The Attribute DynaMent in "remove" mode permits you to remove one or more specific attributes from the value list of a multivalued attribute.

Syntax

<rde-dm:attribute mode ="remove" attribute ="{attributename}"

source ="[user|session|request| content|system|response]"

content ="{contentname}" project ="{projectname}" locale ="{locale string}"

value ="{value;value;...}"

/>


cachingtime ="{cachingtime in minutes}" roles ="{userrole1;userrole2}" result-attribute ="{attributename}" report-tag ="{tagname}" rde-id ="{rde-id}" process-mode ="[standard|standard-recursive|


Simple Call

<rde-dm:attribute mode="remove" source="user" attribute="favorites" value="a;b"

/>

86


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Attribute DynaMent, here "remove".

attribute Name of the attribute that is to be addressed. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). Note: When multivalued attributes are used, you can use the index notation to access a targeted value in the value list. To do so, enter the index of the value that is, the sequence number within the value list after the attribute name. The notation is attribute="<attribute name>[<index>]". The index can be any positive integer. Counting starts with the number 1. Example: attribute="profile.level[3]": In this example, only the third value in the value list is addressed.












87


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

value (optional) Values to remove from the value list of a multivalued attribute. Multiple values are separated by semicolons. The values are case-sensitive. Note: If index notation is used in the attribute parameter, the value parameter is ignored.

Error handling


Deleting Attributes or Attribute Values ('delete')

Purpose

The "delete" mode of the Attribute DynaMent lets you delete attributes with various origins from the LiveServer Repository. Depending on the setting of the op parameter, you delete only the values of an attribute or the attribute itself-including all its child attributes.

Note: The values of system attributes predefined by RedDot, such as "cps.log.level" and "cps.log.categories", must not be deleted.

Syntax

<rde-dm:attribute mode ="delete" attribute ="{attributename}"

source ="[user|session|request|content| system|response|portalinstance]"

content ="{contentname}" project ="{projectname}" locale ="{locale string}" op ="[remove|delete|cleanup]"

/>

The following default parameters can also be used:



88


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Attribute DynaMent, here "delete".

attribute Name of the attribute that is to be addressed. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news.index"). For details about the correct path specification for source="portalinstance", see the information below.








"portalinstance": Attributes of a portal instance from the active session. Can only be used for op="remove".

Value if nothing is specified: "user"

content (optional) Used only for source="content": Name of the content. Only required if the content that is to be addressed is not the current content in which the DynaMent is located. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).


locale (optional) Used only for source="content": Language for which content should be selected. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. The locale parameter affects both the respective content attribute and the output of content data of the selected content. If there is no content data for the selected language in the repository, a replacement language is determined in accordance with the Locale Policy. This is usually the default project language. Value if nothing is specified: Default project language.

op (optional) Operator, the way in which the specified attribute is to be influenced.

"remove": The attribute values are deleted from the LiveServer Repository. Note: The values for predefined system attributes (such as cps.log.level) must not be deleted.

89


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"delete": The attribute and all its child attributes are deleted from the LiveServer Repository.

"cleanup": Used only for source="user": All changes that are made to an attribute during a session are not saved. Normally, these changes are written to the LiveServer Repository or a directory service during logout, after a session timeout, or explicitly in "flush" mode of the Attribute DynaMent.

Value if nothing is specified: "remove"

Error Handling

The Attribute DynaMent's information, warnings, and error messages begin with 3 in the thousands' place. You can send the return codes with the default parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the "RedDot DynaMents" chapter.










See also:

Predefined Attributes for source='system' (Page 560)

90


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Saving User Attributes in Cookies ('flushcookies')

Purpose

You can use the "flushcookies" mode of the Attribute DynaMent to save user attributes in cookies. In this mode, all user attributes referenced to a cookie name through the "cookie" parameter in "write" mode are stored in a cookie on the requesting browser, if the browser settings permit this. The "flushcookies" mode is only used in connection with an Attribute DynaMent in "write" mode (see example). Requirement: The "Allow modification of cookies with Attribute DynaMent" check box must be selected in the project settings (Main Menu -> Select Project -> Edit Project Settings -> Users area).

It is possible to save a user's data (such as name or date of last visit) beyond the current session by storing it in user attributes. The same is not possible for anonymous users, however, without taking additional steps. That is why RedDot LiveServer uses anonymous user cookies to store user attributes on the user's computer. This allows temporary session information to be stored in attributes, which are accessed the next time the user visits the site. The server sends cookies to the client, where the browser stores them for retransmission the next time the user visits the Web site.

User attributes are transmitted by cookies as follows:

The Attribute DynaMent in "write" mode, together with the "cookie" parameter, references user attributes to a cookie name and then saves them for the current user.

All the user attributes referenced to a cookie name through the Attribute DynaMent in "flushcookies" mode are sent in a cookie to the client. The cookie stores the attribute path and attribute value.

The cookie is then transmitted to RedDot LiveServer with the next request. This updates or creates the respective attribute for the current user, which then can be read in "read" mode.

Syntax

<rde-dm:attribute mode ="flushcookies" cookieduration ="{maximum age of cookies}"

/>


cachingtime ="{cachingtime in minutes}"

roles ="{userrole1;userrole2}" result-attribute ="{attributename}" report-tag ="{tagname}" rde-id ="{rde-id}" process-mode ="[standard|standard-recursive|


91


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Attribute DynaMent, here "flushcookies".

cookieduration (optional) Time in days after which the cookies will be deleted. If no value is specified: "10"

Results

All user attributes referenced to a cookie name via the "cookie" parameter in "write" mode are stored in a cookie on the requesting browser.

Error handling

The Attribute DynaMent's information, warning, and error messages begin with 3 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the Error Handling section in the chapter About RedDot DynaMents.

The Interplay of Modes "write", "flushcookies", and "read":

last visit: <rde-dm:attribute mode="read" attribute="login.date" source="user"

/>

<rde-dm:attribute mode="write" attribute="login.date" source="user" value="[#nop#].getSystemDate ('dd.MM.yy HH:mm:ss')" cookie="lastLogin" />

<rde-dm:attribute mode="flushcookies"/>

If an anonymous user visits the respective site, the system's date is assigned to the user attribute login.date the Attribute DynaMent in "write" mode and connected to the cookie name lastLogin. The Attribute DynaMent in mode "flushcookies" then ensures that a cookie containing this attribute is sent back to the browser along with the response. A cookie with the name lastLogin containing the name and value of the user attribute login.date is created for the user.

When the user later returns to the site, without logging on, the user attribute login.date would not exist-or would be filled with the general value of the "anonymous" user. RedDot LiveServer automatically evaluates cookies that are sent back to it that were created in mode="flushcookies", and it uses the value contained in the cookie to set the respective user attribute. As a result, the login.date attribute is still available in our example.

See also:

Writing Attributes ('write') (Page 49)

92


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Writing Attributes Explicitly to the Repository ('flush')

Purpose

You can use the Attribute DynaMent in "flush" mode to save changed attributes permanently in the repository. Normally, RedDot LiveServer saves these attributes automatically.

User attributes of the active session (type="user") These attributes are saved permanently in the repository automatically at logoff or after a session timeout.

Proxy attributes for attribute accesses (type="attribute-proxy") These attributes are saved permanently in the repository asynchronously and automatically when the configured maximum time since the last save is reached or when the proxy reaches a configured upper limit.

You only use "flush" mode if your project requires permanent saving at an earlier time. Each additional save operation increases the server load, particularly because database activity is needed.

Syntax

<rde-dm:attribute mode ="flush" type ="[user|attribute-proxy]" source ="content" content ="{contentname}"

project ="{projectname}"

/>




Parameters

mode Mode of the Attribute DynaMent, here "flush".

type (optional) Defines from which object attributes are written to the LiveServer Repository:

"user": Active session user

"attribute-proxy": Proxy for attribute access


93


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

source (optional) Used only for type="attribute-proxy"; required in this case: Source of the attribute that is to be addressed. The following options are available:


content (optional) Used only for source="content"; required in this case: Name of the content whose attributes that have been changed in the proxy for attribute access are to be written to the LiveServer Repository. Required even if the content that is to be addressed is the current content contained in the DynaMent. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).


Notes

For type="user": The user's actual object fields are not normally written to the LiveServer Repository. The object fields contain the following user data:

login: User name for logging on to RedDot LiveServer

password: Password for logging on to RedDot LiveServer

language: User language

country: Country

name: Name of the user

Results

The attributes are written to the LiveServer Repository.

Error handling


94


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Using Attributes in XSL Files ('xslparam')

Purpose

"xslparam" mode of the Attribute DynaMent is only used in conjunction with XSL content. It defines an XSL parameter and its value dynamically for the current query and passes it on to the XSL engine as a runtime parameter before rendering.

If an XSL style sheet from RedDot LiveServer is used for rendering, all the attributes of the current request will be passed to the XSL engine. To be able to access the request attributes in XSL, you must declare them as global XSL parameter in the style sheet. RedDot LiveServer automatically adds specific declarations (see the link "Predefined XSL Parameters" below).

You can use the Attribute DynaMent in "xslparam" mode to add more declarations, allowing you to access other attributes of the current request in the style sheet.

Syntax

<rde-dm:attribute mode ="xslparam" attribute ="{attributename}

/>


cachingtime ="{cachingtime in minutes}" roles ="{userrole1;userrole2}"

result-attribute ="{attributename}"

Parameters

mode Mode of the Attribute DynaMent, here "xslparam".

attribute Name of the request attribute that will be accessed in the style sheet.

Results

The declaration of the XSL parameter is inserted at the beginning of the XSL file.

Error Handling

The Attribute DynaMent's information, warning, and error messages begin with 3 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the Error Handling section in the chapter About RedDot DynaMents.

95


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example of a call:

<rde-dm:attribute mode="xslparam" attribute="test"/>

The result:

<xsl:param name="test"/>

Value is read in XSL, for example, using:

<xsl:value-of select="$test"/>

See also:

Predefined XSL Parameters (Page 567)Predefined Attributes for source='request' (Page 548)

96

DynaMent ReferencesCache DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Cache DynaMent

The Cache DynaMent is used to control RedDot LiveServer cache processing flexibly during runtime.

Read more about the following actions:

Setting the validity of entries in the object cache (mode="set-scope")

Renaming entries in the object cache (mode="set-id')

Adding dependencies to the list of dependencies in the cache, either for the content processed currently or for an existing cache entry (mode="add-dependency")

Marking entries as changed, thus clearing them from the cache (mode="notify").

Setting the Validity of Entries in the Object Cache ('set-scope')

The Cache DynaMent in "set-scope" mode lets you change the validity entries in the object cache. Content items can be saved in the object cache longer than the duration of the current request, this is especially useful for temporary items such as attachments or file uploads. You address the cache entry using the <rde-rd:entry> child element.

Background: Attachments received via a Web service are stored as temporary content in the object cache; initially they are only valid for one request. To allow processing of an attachment in later requests, its validity within the session must be extended.

Syntax

<rde-dm:cache mode ="set-scope"

cache ="object" scope ="{session|request|server}" timeout ="{timeout in seconds}" >

<rde-rd:entry

type ="[content|name|entry-id]" content ="{content}" project ="{project}" name ="{name}"

entry-id ="{complete key}" />

</rde-dm:cache>




97


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:cache mode="set-scope" cache="object" scope="request">

<rde-rd:entry type="content" content="test.xml/>

</rde-dm:cache>

The retention period of the specified entry in the object cache is changed and defined as the duration of a request.

Parameters

mode Mode of the Cache DynaMent, here: "set-scope".

cache Name of the cache to be used in the DynaMent. Currently, only the "object" value is used for the object cache in "set-scope" mode.

scope (optional) Retention period of a cache entry:

"request": The cache entry is valid during a request.

"session": The cache entry is valid during a session.

"server": The cache entry is valid during the run time of the server and uses memory permanently.

Value if nothing is specified: "session"

timeout (optional) Maximum amount of time in seconds for which a cache entry remains valid.

cachingtime (optional) Maximum amount of time in minutes for which the entry remains in the cache. With the specific value "-1", the cachingtime parameter is not interpreted. Value if nothing is specified: "0"

Child Elements

The Cache DynaMent has a child element called <rde-rd:entry>. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:entry> The child element references a cache entry whose retention period is to be changed.

type (optional) Type of referencing of the cache entry. A cache entry can be referenced in different ways:

"content": References individual or multiple cache entries that are assigned to a content item by specifying the content. It uses the content and project parameters.

"name": References a cache entry of an object that was added to the cache under a name in the Open API. It uses the name parameter.

"entry-id": References a cache entry using its direct key. It uses the entry-id parameter.

98


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Value if nothing is specified: "content"

content (only for use with type="content") Name of content that is referenced. In particular, this can be temporary content in the object cache that, for instance, was loaded using the Repository, Reporting, or Reference DynaMent. You can also specify a project name, separating it with a colon (project name:content name). Note: If no project with the specified name exists, the entire entry is interpreted as the content name. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

project (optional; only for use with type="content") Name of the project containing the content. If nothing is specified: Project name specified in the content parameter. If no project has been specified there either, the project containing the Cache DynaMent is used.

name (only for use with type="name") Name of the object that was put in the cache using the Open API.

entry-id (only for use with type="entry-id") Gives the complete key of the cache entry, for instance for referencing entries in the search result cache. The key can be obtained using a Target or Query DynaMent (cache-id-attribute parameter).

Result

No result is returned. The retention period of the specified entry in the cache is changed.

Error Handling

The Cache DynaMent's information, warning, and error messages begin with 32 in the thousands' place. You can send the return codes with the default parameter result-attribute. In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following message is possible:

See also:

Calling Web Services (Page 531)Receiving and Processing Attachments (Page 540)


-32320 The project was not found.

99


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Renaming Entries in the Object Cache ('set-id')

The Cache DynaMent in "set-id" mode lets you rename entries in the object cache. This is particularly useful when names have been defined externally and are not suitable to be used on the Web site. For example, it is useful for attachments that were loaded into the object cache using a Web service, or when uploading a multipart request.

You reference the cache entry using the <rde-rd:entry> child element. You enter the renamed entry in the <rde-rd:new-entry> child element.

Syntax

<rde-dm:cache mode ="set-id" cache ="object"

replace ="[true|false]" >

<rde-rd:entry type ="[content|name|entry-id]" content ="{content}" project ="{project}" name ="{name}" entry-id ="{complete key}" />

<rde-rd:new-entry

type ="[content|name|entry-id]" content ="{content}" project ="{project}" name ="{name}"

entry-id ="{complete key}" />

</rde-dm:cache>




Simple Call

<rde-dm:cache mode="set-id" cache="object" > <rde-rd:entry type="name" name="forum.[#request:lsforum.storageProject#lsfcontent#].list"/>

<rde-rd:new-entry type="name" name="forum2.[#request:lsforum.storageProject#lsfcontent#].list"/>

</rde-dm:cache>

The cache entry is given a new name in the object cache.

100


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Cache DynaMent, here: "set-id".

cache Name of the cache to be used in the DynaMent. Currently, only the "object" value is used for the object cache in "set-id" mode.

replace (optional) Determines whether to replace an entry with the same name in the object cache with the new entry, or to abort the process:

"true": An entry with the same name will be replaced.

"false": An entry with the same name will not be replaced.

Value if nothing is specified: "true"

cachingtime (optional) Maximum amount of time in minutes that the content that the running request is processing remains in the cache. With the specific value "-1", the cachingtime parameter is not interpreted. Value if nothing is specified: "0"

Child Elements

The Cache DynaMent has the child elements called <rde-rd:entry> and <rde-rd:new-entry>. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:entry> The child element references a cache entry that is to be renamed.






content (only for use with type="content") Name of content that is referenced. In particular, this can be temporary content in the object cache that, for instance, was loaded using the Repository, Reporting, or Reference DynaMent. You can also specify a project name, separating it with a colon (project name:content name). Note: If no project with the specified name exists, the entire entry is interpreted as the content name. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy.

101


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

The path components are separated by slashes (example: demo:modules/news/news.xml). You need to specify a project because this information is part of the key used to store content in the object cache.


name (only for use with type="name") Name given to the object that was put in the cache using the Open API.


<rde-rd:new-entry> The child element defines the new name of the renamed cache entry. The parameters are identical to the <rde-rd:entry> child element. Note: When the new entry is referenced with the type="content", the value of the cache entry is also renamed if it involves a content item.

Result

The cache entry of the <rde-rd:entry> child element is renamed in the object cache as specified in the <rde-rd:new-entry> child element. In persistent repositories, the content name is not changed.

Error Handling

The Cache DynaMent's information, warning, and error messages begin with 32 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following message is possible:

See also:



32275 The cache entry already exists. Cache ID has not been renamed.

102


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Adding Cache Dependencies ('add-dependency')

Function

With the Cache DynaMent in "add-dependency" mode, you can add dependencies of a cache entry to the list of dependencies in the cache. The cache entry itself is addressed in the DynaMent via the <rde-rd:entry> child element. You address the list of dependencies via the <rde-rd:dependency> child element.

Two usages are possible:

Entering a dependency for the currently processed content in the component cache.

Entering an additional dependency for an existing cache entry in the component cache or the search result cache or the object cache.

Dependencies are used to find cache entries easily and mark them as invalid after changes have been made affecting these cache entries that have been using properties of the changed objects. RedDot LiveServer itself enters a sufficient number of dependencies to ensure efficient use of the caches when delivering pages dynamically. Adding further dependencies can be useful depending on the project, for example in the following cases:

Java codes in Iolets or in events use information that change frequently.

Search results or pages with external content (RDB DynaMent) are changed by actions on the web site.

Additional dependencies are marked with a name of your choice that is also used for the invalidation. Use self-explaining prefixes and names.

Syntax

<rde-dm:cache mode ="add-dependency" cache ="[component|searchresult|object]" >

<rde-rd:entry

type ="[content|name|entry-id]" content ="{content}" project ="{project}" name ="{name}" entry-id ="{complete key}" />

<rde-rd:dependency>


</rde-dm:cache>

103


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Parameters

mode Mode of the Cache DynaMent, here "add-dependency".

cache (optional) Name of the cache to be used in the DynaMent. Possible values:

"component": Component cache

"searchresult": Search result cache

"object": Object cache

Value if nothing is specified: "component"

Child Elements

The Cache DynaMent has the child elements called <rde-rd:entry> and <rde-rd:dependency>. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:entry> The child element references a cache entry for which one or more dependencies are to be entered. This child element is not necessary for cache="component". This case uses the dependency for the entry of the component cache that is created after processing the current request.






content (only for use with type="content") Name of content that is referenced. In particular, this can be temporary content in the object cache that, for instance, was loaded using the Repository, Reporting, or Reference DynaMent. You can also specify a project name, separating it with a colon (project name:content name). Note: If no project with the specified name exists, the

104


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

entire entry is interpreted as the content name. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).




<rde-rd:dependency> Child element indicating a dependency. The name of the dependency can be used in the Cache DynaMent with mode="notify" for invalidation. You can specify more than one child element. For each child element, there can be one dependency. The parameters are identical to the <rde-rd:entry> child element.

Result

For the entry specified, dependencies in the specified cache are entered.

Error Handling




105


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Using "add-dependency" and "notify"

Content a: Dependencies are added to the search result cache and to the component cache. The <rde-rd:entry> child element can be omitted in the second Cache DynaMent mode="add-dependency" because the currently processed content is to be addressed.

<rde-dm:target tag="product-list" cache-id-attribute="request:targetCacheId"/> <rde-dm:cache mode="add-dependency" cache="searchresult"> <rde-rd:entry type="entry-id" entry-id="[#request:targetCacheId#]"/>

<rde-rd:dependency type="name" name="x-myname-x"/> <rde-rd:dependency type="content" project="html-demo" content="cache-

dep.xml"/>

</rde-dm:cache>

<rde-dm:cache mode="add-dependency" cache="component" report-tag="rep"> <rde-rd:dependency type="name" name="x-myname-x"/> <rde-rd:dependency type="content" project="html-demo" content="cache-

dep.xml"/>

</rde-dm:cache>

Content b: The Cache DynaMent in "notify" mode deletes the cache entries in the search result cache and in the component cache.

<rde-dm:cache mode="notify"> <rde-rd:entry> type="name" name="x-myname-x" />

</rde-dm:cache>

106


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Removing Entries from the Cache ('notify')

Function

With the Cache DynaMent in "notify" mode, the cache is notified that your entry has changed. It marks all related cache entries as invalid. You address the cache entry using the <rde-rd:entry> child element.

Syntax

<rde-dm:cache mode ="notify"

priority ="[synchronous|queue]" > <rde-rd:entry


</rde-dm:cache>




Simple Call

<rde-dm:cache mode="notify"> <rde-rd:entry type="name" name="forum.[#request:lsforum.storageProject#lsfcontent#].list"/>

</rde-dm:cache>

The cache entry is marked as changed. The dependent cache entries are marked as invalid and removed from the cache.

Parameters

mode Mode of the Cache DynaMent, here "notify".

priority (optional)

"synchronous": The notification is sent immediately.

"queue": The notification is sent to a queue.

Value if nothing is specified: "synchronous"

107


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Child Elements

The Cache DynaMent has a child element called <rde-rd:entry>. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:entry> The child element references a cache entry for which an internal notification job is to be created to mark dependent cache entries as invalid.


"content": References individual or multiple cache entries that are assigned to a content item by specifying the content. It uses the content and project parameters. The content item and all of the cache entries depending on it are marked as invalid.

"name": References a cache entry of an object that was added to the cache under a name in the Open API. It uses the name parameter. All cache entries that were declared dependent on this name by mode="add-dependency" are marked as invalid.

"entry-id": References a cache entry using its direct key. It uses the entry-id parameter. The cache entry and all cache entries that were declared dependent on it by mode="add-dependency" are marked as invalid.


content (only for use with type="content") Name of content that is referenced. In particular, this can be temporary content in the object cache that, for instance, was loaded using the Repository, Reporting, or Reference DynaMent. You can also specify a project name, separating it with a colon (project name:content name). Note: If no project with the specified name exists, the entire entry is interpreted as the content name. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).




108


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

The entry specified is marked as changed. The dependent cache entries are marked as invalid and removed from the cache.

Error Handling


Example: Using "add-dependency" and "notify"

Content a: Dependencies are added to the search result cache and to the component cache. The <rde-rd:entry> child element can be omitted in the second Cache DynaMent mode="add-dependency" because the currently processed content is to be addressed.

<rde-dm:target tag="product-list" cache-id-attribute="request:targetCacheId"/> <rde-dm:cache mode="add-dependency" cache="searchresult"> <rde-rd:entry type="entry-id" entry-id="[#request:targetCacheId#]"/>

<rde-rd:dependency type="name" name="x-myname-x"/> <rde-rd:dependency type="content" project="html-demo" content="cache-

dep.xml"/>

</rde-dm:cache>

<rde-dm:cache mode="add-dependency" cache="component" report-tag="rep"> <rde-rd:dependency type="name" name="x-myname-x"/> <rde-rd:dependency type="content" project="html-demo" content="cache-

dep.xml"/>

</rde-dm:cache>

Content b: The Cache DynaMent in "notify" mode deletes the cache entries in the search result cache and in the component cache.

<rde-dm:cache mode="notify"> <rde-rd:entry> type="name" name="x-myname-x" />

</rde-dm:cache>



109

DynaMent ReferencesContent DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Content DynaMent

You use the Content DynaMent to import content to the LiveServer Repository during runtime, or to delete content.


Importing content to the LiveServer Repository and adding metadata to it (mode="import")

Adding the results of validation services (such as Web Compliance Manager) to the processed content (mode="validate")

Deleting content (mode="delete")

Deleting one language variant of a content item (mode="remove-data")

Marking content for the cache as changed, thus clearing it from the cache (mode="notify-cache"). Note: This mode is deprecated and should no longer be used. Instead, use the "notify" mode of the Cache DynaMent.



Content DynaMent

CPS DynaMent

Message DynaMent

User DynaMent


Importing Content ('import')

Purpose

With the Content DynaMent in "import" mode, you import individual content items based on an import job to the LiveServer Repository during runtime. This allows you, for instance, to add metadata to content items created by external users via a form, and include them in the LiveServer Repository.

Note: External content may include DynaMents. Using DynaMent security rules, you can prevent these DynaMents from being executed. You can set a security rule for each content group; it therefore makes sense to import content items organized into specific content groups.

110


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

The Content DynaMent can be used with child elements in "import" mode. The <rde-rd:content> child element contains the content data for import for ref-type="embedded". The content of this element will be processed before it is inserted. You can also use the <rde-rd:import> child element to add metadata to a content item.

Syntax

<rde-dm:content mode ="import" content ="{project:content name}" project ="{project}" type ="[html|xml|xsl|blob|script]" locale ="{locale string}" ref-type ="[embedded|file|named]" ref ="{reference name}" synchronized ="[no|yes]" retries ="{number of retries}" timeout ="{timeout for synchronize}" importtask ="{importtask name}"

importdef ="{importdefinition name}"

encoding ="{encoding}" group ="{content-group}" archive ="[true|false]" release ="[false|true]" overwrite ="[false|true]" overwrite-group ="[false|true]" fulltext-search ="[false|true]" delete-after-import ="[false|true]"

ignore-metadata ="[false|true]" >

<rde-rd:import> ...metadata...

</rde-rd:import>

<rde-rd:content mode ="[set|add|insert|remove]" xpath-expr ="{xpath expression}"> ...content...

</rde-rd:content>

</rde-dm:content>




111


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:content mode="import" content="html-demo:index.html" ref-type="file"

ref="C:\projects\de\261.htm" importtask="importtask" />

Based on the settings of the first import definition to be found belonging to the specified import job, the content specified in the parameter ref will be imported into the "html-demo" project and given the name "index.html".

Parameters

mode Mode of the Content DynaMent, here "import".

content The name of the LiveServer repository content you want to import. You can also specify a project name, separating it with a colon (project name:content name). If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

project (optional) Name of the project where the content should be imported. If nothing is specified: Project name specified in the content parameter. If no project is specified there, the project where the Content DynaMent is located is used.

type (optional) Type of the content to import. Will not be evaluated if the existing content has been replaced or if an import definition was specified in the importdef parameter. Value if nothing is specified: "html"

locale (optional) Language to create this content item. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. If nothing is specified: Default project language.

ref-type (optional) Determines which content data is imported.

"embedded": The content data specified in the value of the child element <rde-rd:content> will be passed on. The child element will be processed prior to import. This lets you import content from attribute values, or include DynaMents in the content. Any DynaMents you want to include in the content must not be processed before. You need the parameter value process-mode="ignore" to achieve this. If the <rde-rd:content> child element does not exist, only metadata from the <rde-rd:import> child element is transferred.

"file": The file located in the absolute path specified in the ref parameter is transferred. If a relative path is specified, this is interpreted relative to RedDot LiveServer's Web application directory (.../cps/WEB-INF/).

"named": The content data specified in the ref parameter is transferred. This is limited to the content data for the language of the current session. The content must be stored in the object cache under the name specified in ref for the current project. If the content cannot be found in the object cache, an error message is returned. In this case, nothing is transferred - not even the metadata from the <rde-rd:import> child element.

Value if nothing is specified: "embedded"

112


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

ref (optional) Required entry only for:

ref-type="file": URI for the import Specifies either an absolute path and file name on RedDot LiveServer where the file for import is located or a relative path starting with the Web application path .../cps/WEB-INF/. If the specified file is not available, nothing is transferred - not even the metadata from the <rde-rd:import> child element. If no value is specified, ref-type="embedded" is used instead of "file".

ref-type="named": Name of the content item from which will be imported. This is limited to the content data for the language of the current session. The content must be stored in the object cache under the name specified for the current project. If the content cannot be found in the object cache, an error message is returned. In this case, nothing is transferred - not even the metadata from the <rde-rd:import> child element.

synchronized (optional) Specifies when a content item for import is blocked for further access while it is being accessed.

"no": The content is blocked during writing.

"yes": The content is blocked for further access during reading.


retries (optional) Only for synchronized="yes": Number of attempts to get access to a content item that is blocked during reading. If nothing is specified: RedDot LiveServer default setting.

timeout (optional) Only for synchronized="yes": Time in milliseconds between individual attempts to get access to a content item that is blocked during reading. If nothing is specified: RedDot LiveServer default setting.

importtask Name of an import job of a specific project in which it is to be imported. The import job serves as a connector for the Content DynaMent. Here the individual content item information will be evaluated during import only if it is applicable for the Content DynaMent.

importdef (optional) Name of an import definition of the project in which it is to be imported. The import definition serves as an additional connector configuration element for the Content DynaMent. Here the individual content item information will be evaluated during import only if it is applicable for the Content DynaMent.

If the import definition is not specified, the first definition found in the import job whose values for locale and type correspond to those specified in the Content DynaMent will be used. If the mode and xpath-expr parameters are used in child element <rde-rd:content>, the first definition with content type XML is used.

Some of the import definition settings can be replaced by the following Content DynaMent parameters. If nothing is specified, the settings of the import definition will be applied:

encoding (optional) Denotes the encoding that will be used for the content to be imported (for example, ISO-8859-1). Ignored if reftype="embedded".

113


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

group (optional) Value of the path name of the content group into which the content will be imported, within the content group hierarchy. The path components are separated by slashes (example: demo/countries/countriesxml). If the group is not in the specified project, the group will be created and the content assigned. If the content should not be assigned to a group, enter the following value: "rdeNoGroup".

archive (optional) Determines whether or not existing content will be archived prior to importing and replacement by new version. The archiving feature must be activated and an archive depth must be specified. Possible values: "true"/"false".

release (optional) Determines whether or not to release newly imported content immediately. Possible values: "true"/"false".

overwrite (optional) Determines whether or not new content may replace existing content. Possible values: "true"/"false".

overwrite-group (optional) Determines whether or not the group assignment of existing content can be overwritten. Possible values: "true"/"false".

fulltext-search (optional) Determines whether the search engine will index the content. Possible values: "true"/"false".

delete-after-import (optional) Determines whether the file to import is deleted after import. Only relevant for ref-type="file" and "named" relevant. Possible values: "true"/"false".

ignore-metadata (optional) Determines whether Import DynaMents are removed from a content item and content meta data (constraints, attributes) are not imported. Possible values: "true"/"false".

Child Elements

There are two child elements in "import" mode. Child element <rde-rd:import> can be used once within a Content DynaMent, while child element <rde-rd:content> can be used several times. DynaMents within values of a child element are processed. Inline notation is only supported in XPath expressions specified in parameter xpath-expr.

<rde-rd:import> (optional) This child element contains the metadata that will be added to the content. The content of this element will be processed before it is inserted. The syntax is the same as for the Import DynaMent. See the description there.

<rde-rd:content> (optional) Only for ref-type="embedded": The child element contains the content data to be imported. The content of this element will be processed before it is inserted. If multiple <rde-rd:content> child elements exist, they are processed in sequence. If the child element does not exist, only the metadata from the <rde-rd:import> child element is imported. The child element can contain Import DynaMents, for example, to assign attributes to RedDot

114


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

LiveServer content from outside. This method cannot be used to reference external content. An Import DynaMent used within this child element must be written with namespace "rde-rd"; otherwise it would be executed already when the content is read with the Content DynaMent (see the example below).

mode (optional) Only used together with parameter xpath-expr: Determines how the content specified in child element <rde-rd:content> is inserted in existing XML content.

"set": The child nodes of the node determined from parameter xpath-expr are removed and replaced by the content. If a determined node is an attribute (/path/@id), the value attribute is used to set the attribute value. Only existing attributes are changed.

"add": The determined node is added to the content item as a child node. If the determined node is an attribute, the attribute and value attributes are used to add a new attribute or set a new value for the existing attribute.

"insert": The content is inserted as a child node before the determined node.

"remove": The determined nodes are deleted. If a determined node is an attribute, the following applies: If the attribute attribute has a value, only that attribute is deleted.

If nothing is specified: The existing content is replaced completely.

xpath-expr (optional) Only used together with parameter mode: XPath expression to determine the node to address. Inline notation is not supported.

Notes

By using DynaMent security rules, you can prevent the execution of any DynaMents that are part of the content to be imported.

Result

The specified content will be imported to the LiveServer repository with the metadata specified in the child element <rde-rd:import>.

115


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The Content DynaMent's information, warning, and error messages begin with 26 in the thousands' place. You can send the return codes with the default parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:

For more information about import jobs and import definitions, see the Projects/Contents documentation.

For more information about the Import DynaMent, see the separate section.


See also:

Importing/Deleting Metadata (Page 141)Using the Results (Page 19)XPath Statements in Parameters (Page 26)

For more information about DynaMent security rules, see the Projects/Contents documentation.



-26501 No import job found

-26502 No import definition found

-26503 Incorrect locale specified

-26504 General error

-26507 The XPath expression is missing or invalid

-26508 The mode="set" and "add" are only available for xml content

-26509 Synchronization failed (softlock not granted)

116


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Using ref-type="embedded" and specifying metadata for the <rde-rd:import> child element:

<rde-dm:content mode="import" project="html-demo" content="dynamentImport" ref-type="embedded" importtask="importtask" type="html" locale="en" group="rdeNoGroup"> <rde-rd:import> <constraints mode="set"> <constraint attribute="profile.level" description="en profile level greater than 2" mode="condition" op="gt" value="0"> (a gt b) or ([#request:attr#gg#].trim() lt d) </constraint> </constraints> <keywords> attribute1: value1, attribute1: value 2, attribute 2: value 3, attribute3.subattribute3: value 4, </keywords> </rde-rd:import> <rde-rd:content> <![CDATA[ This is a test in CDATA. ]]> <rde-dm:attribute mode="read" attribute="address.street"/> This is only a test. </rde-rd:content>

</rde-dm:content>

When the DynaMent is called, the information specified in the <rde-rd:content> child element is imported to the project "html-demo" as a content item called "dynamentImport". The content is not assigned to any group. The import will only run if an import job "importtask" with at least one import definition using the content type "html" and the language "en" is available in the project. The information contained in the <rde-rd:import> child element is used to assign constraints and attributes to the content item.

117


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Using Import DynaMents with the namespace "rde-rd" in the <rde-rd:content> child element:

<rde-dm:content mode="import" project="demo" content="test" ref-type="embedded" importtask="importUpload" importdef="importUpload"> <rde-rd:import> <keywords mode="set">content11:upload22</keywords> </rde-rd:import> <rde-rd:content> <rde-rd:import-list> <rde-rd:import> <rde-rd:reference content-type="xml" type="internal"> import1.htm </rde-rd:reference> <rde-rd:reference content-type="xml" type="internal"> import2.htm </rde-rd:reference> <keywords mode="set">type:111</keywords> </rde-rd:import> <rde-rd:import> <rde-rd:reference content-type="xml" type="internal"> import3.htm </rde-rd:reference> <rde-rd:reference content-type="xml" type="internal"> import4.htm </rde-rd:reference> <keywords mode="set">type:222</keywords> </rde-rd:import> </rde-rd:import-list> </rde-rd:content>

</rde-dm:content>

118


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Use with mode and xpath-expr in the <rde-rd:content> child element to edit existing XML content:

XML content before:

<faq> <question> <author id="34567">xxx</author> <text>How does it work?</text> </question>

</faq>

Content DynaMent

<rde-dm:content mode="import" content="[#request:cguid#]" project="featuredemo" ref-type="embedded" importtask="import" importdef="importFAQ"> <rde-rd:content mode="add|set|remove" xpath-expr="//faq/question"> <answer> <author>author name</author> <text> This is just a text</text> </answer> </rde-rd:content>

</rde-dm:content>

XML content after:

mode="add"

<faq> <question> <author>xxx</author> <text>How does it work?</text> <answer> <author>author name</author> <text> This is just a text</text> </answer> </question>

</faq>

mode="set"

<faq> <question> <answer> <author>author name</author> <text> This is just a text</text> </answer> </question>

</faq>

mode="remove"

<faq>

</faq>

119


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Recording Check Results ('validate')

The Content DynaMent in "validate" mode lets you add the results of validation services (such as Web Compliance Manager) to the processed content. The validation services are addressed through one or more connectors.

The Content DynaMent can be used with child elements in "validate" mode. The optional child element <rde-rd:xpath-expressions> contains XPath expressions to select the data to be checked. The <rde-rd:content> child element contains the content data to be checked for ref-type="embedded".

Syntax

<rde-dm:content mode ="validate"

validation-service ="{connector;connector;...}" ref-type ="[embedded|file|named|

content|attribute]" ref ="{reference name}" content ="{project:content name}"

project ="{project}" locale ="[{locale string}|all]"

locale-policy ="[any|none|default]" type ="{text|xml]"

source ="[request|user|session]" encoding ="{encoding}"

validation-result-attribute = "{attribute name} >

<rde-rd:xpath-expressions> <rde-rd:xpath-expr>...</rde-rd:xpath-expr> ...

</rde-rd:xpath-expressions>

<rde-rd:content> ...data...

</rde-rd:content>

</rde-dm:content>


tag ="[{tagname}|notag]"



120


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:content mode="validate" validation-service="test"

ref-type="content" content="html-demo:index.htm" locale="en" />

The English-language content data of content item index.htm from project html-demo is checked using the specified validation service. The resulting XML contains the check result (for instance, "ACCEPTED") as well as the entire XML coding created by the specified validation service.

Parameters

mode Mode of the Content DynaMent, here "validate".

validation-service Name of the validation service connector assigned in RedDot LiveServer. Several connectors can be specified, separated by semicolons.

ref-type Determines which content data is checked.

"content": Content item in RedDot LiveServer The content item is determined from the following parameters: project (optional), content, and locale (optional). The non-processed content is checked – that is, DynaMents contained in the content item have not run yet. If an event definition with type Content event - on load is assigned to the content item, however, it has already been applied when the check runs.

"named": Content item from the object cache The content data specified in the ref parameter is checked. The content must be stored in the object cache under the name specified for the current project. If the content cannot be found in the object cache, an error message is returned. The key for the object cache is specified using the project (optional) and content parameters, or, if the content parameter is not specified, is taken directly from the ref parameter.

"embedded": The content data specified in the value of the child element <rde-rd:content>. XPath expressions are only evaluated if type="xml".

"attribute": Value of an attribute The attribute is specified in parameter ref. You can also specify the optional source parameter; the default is "request". XPath expressions are only evaluated if type="xml".

"file": File or URL The file located in the absolute path specified in the ref parameter is checked. If a relative path is specified, this is interpreted relative to RedDot LiveServer's Web application directory (.../cps/WEB-INF/). You can also specify a protocol (such as http://). XPath expressions are only evaluated if type="xml".


ref-type="file": URI of the file to be checked. Specifies a URL or absolute path and file name in RedDot LiveServer where the file to be checked is located. Alternatively, you can also specify a relative path, starting with the Web application path .../cps/WEB-INF/.

121


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

ref-type="named": Name of the content item whose data are to be checked. Note that only the content data for the language of the current session is checked, however. The content must be stored in the object cache under the name specified for the current project. If the content cannot be found in the object cache, an error message is returned.

ref-type="attribute": Attribute name of the attribute to be checked.

content (optional; only for use with ref-type="[content|named]") The name of the LiveServer repository content you want to check. You can also specify a project name, separating it with a colon (project name:content name). If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

project (optional; only for use with ref-type="[content|named]") Name of the project containing the content to be checked. If nothing is specified: Project name specified in the content parameter. If no project is specified there, the project where the Content DynaMent is located is used.

locale (optional) Language of the content data to be checked. This parameter is not required, but it is recommended.

"{locale}": RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US.

"all": All languages. This value is only possible for ref-type="[content|named]")

If nothing is specified: Current locale of the request or the language determined by the locale-policy for use in delivery.

locale-policy (optional; only for use with ref-type="[content|named]") Locale policy to access content data: If a content item has no data for the language variant determined by the locale parameter, the data for a different language variant is read. Possible settings:

"none": If content data is not available in the language you require, no data from any other language is read.

"default": If content data is not available in the language you require, the data for the project default language specified in the project settings is read. If no data is available there either, the default language specified in the system configuration (key: reddot.locale.default) is read. If no data is available in this language, nothing is read.

"any": If no content data is available in the language you require, the data for the project default language is read. If no data is available there either, the default language specified in the system configuration (key: reddot.locale.default) is read. If no data is available in that language, the system searches for and reads the first available content data in one of the languages, following the order of languages specified in the project settings.

Value if nothing is specified: "any"

type (optional; only for ref-type="[embedded|attribute|file]") Indicates the content type of the specified content item.

"text": General text (HTML).

"xml": XML. XPath expressions are only evaluated for this type.

122


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Value if nothing is specified: "text"

locale-policy (optional; only for ref-type="attribute") Origin of the attribute to be checked. The following options are available:




Value if nothing is specified: "request"

encoding (optional; only for ref-type="file") Denotes the encoding that will be used for the content to be checked (for example, ISO-8859-1).

If nothing is specified: Default encoding of RedDot LiveServer

Child Elements

There are two child elements in "validate" mode. Child element <rde-rd:xpath-expressions> can be used once within a Content DynaMent, but can contain several <rde-rd:xpath-expr> elements. The <rde-rd:content> child element can be used multiple times. DynaMents within values of child elements are not processed. Inline notation is not supported.

<rde-rd:xpath-expressions> (optional) The individual child elements contain the XPath expressions for selecting the data to be checked.

<rde-rd:xpath-expr> (optional) XPath expression to determine the elements, text, or CDATA nodes to address. When elements are used, the contents of all text and CDATA nodes that are child nodes of the found elements are used as inputs for the validation service.

<rde-rd:content> (optional) Only for ref-type="embedded": This child element contains the content data to be checked. If multiple <rde-rd:content> child elements exist, they are processed in sequence.

Result

The resulting XML contains the full result of the check:

ACCEPTED: The check was carried out. The result fulfills the check criteria of the specified rule.

REJECTED: The check was carried out. The result does not fulfill the check criteria of the specified rule.

CONDITION_FAILURE: The preliminary check failed, so the check was not performed.

NOT_CHECKED: The check was not carried out (completely).

This result is also written to the specified validation-result-attribute (if any; parameter optional). If "all" is specified for the locale parameter for ref-type="content, named", the result in the return attribute is multivalued. The individual values are name/value pairs with format {locale}="{result}", for example, de="REJECTED" or en="ACCEPTED".

123


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

In the default settings, the resulting XML also contains the entire XML coding created by the specified validation service as configured.

Error Handling

The Content DynaMent's information, warning, and error messages begin with 26 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:

For more information about validation service connectors, see the Connectors documentation.



-26510 Invalid type specification

-26511 No "rde-rd:content" element found

-26512 Invalid XML

-26513 Invalid source for attribute

-26514 Attribute not found

-26515 Invalid URL in "ref" parameter

-26516 Content cannot be loaded

-26517 Validation service connector not found

124


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: XPath Expressions

<root> <rde-dm:content mode="validate" ref-type="content" content="html-demo:content01.xml" validation-service="test" locale="de" > <rde-rd:xpath-expressions> <rde-rd:xpath-expr> /root-elem/entry </rde-rd:xpath-expr> </rde-rd:xpath-expressions> </rde-dm:content>

</root>

content01.xml:

<root-elem> <entry> <![CDATA[ <html> <body> <p>Hello World!</p> </body> </html> ]]> </entry>

</root-elem>

Therefore, the entry for the validation service is the HTML snippet in the CDATA section of content01.xml in the above example.

125


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Deleting Content ('delete')

Purpose

With the Content DynaMent in "delete" mode, you can delete content from the LiveServer Repository, including all related objects such as attributes, language variants, constraints, and the archive. You can restrict deletion to a specific content version.

Syntax

<rde-dm:content mode ="delete" content ="{project:content name}"

project ="{project}" version ="[final|draft|{version}]"

/>




Simple Call

<rde-dm:content mode="delete" content="html-demo:news.htm" />

Parameters

mode Mode of the Content DynaMent, here "delete".

content Name of the content item that will be deleted from the LiveServer Repository. You can also specify a project name, separating it with a colon (project name:content name). If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

project (optional) Name of the project from which the content will be deleted. If nothing is specified: Project name specified in the content parameter. If no project is specified there, the project where the Content DynaMent is located is used.

126


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

version (optional) Version of the content item to delete. The following values are possible:

"final": The current content item with status Released.

"draft": The current content item with status Draft.

"{version}": Explicit value for a specific version of the content item. You can use the MetaData DynaMent (mode="list-versions") to determine the version numbers of a content item. The version numbers also appear in the administration UI in RedDot LiveServer, in the Versioning area of the Edit Content dialog window.

If nothing is specified: The content is deleted completely. If the specified version does not exist, nothing is deleted and an error message appears.

Result

The content item is permanently deleted in all language variants. If a version is specified, only that version of the content is deleted.

Error Handling


Removing Data ('remove-data')

Purpose

You use the Content DynaMent in "remove-data" mode to delete the specified language variant of a content item from the LiveServer Repository. If no language is specified, the data for all languages is deleted. The metadata, such as constraints and attributes, is not deleted.

Syntax

<rde-dm:content mode ="remove-data" content ="{project:content name}" project ="{project}" locale ="{locale string}"

archive ="[true|false]" />



-26321 The specified version was not found.

127


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Simple Call

<rde-dm:content mode="remove-data" content="html-demo:news.htm" />

Parameters

mode Mode of the Content DynaMent, here "remove-data".

content Name of the content item whose data will be deleted from the LiveServer Repository. You can also specify a project name, separating it with a colon (project name:content name). If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

project (optional) Name of the project from which the content data will be deleted. If nothing is specified: Project name specified in the content parameter. If no project is specified there, the project where the Content DynaMent is located is used.

locale (optional) Language of data to delete. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. If nothing is specified: Data is deleted for all languages.

archive (optional) Determines whether or not a new version of the content item is created when the DynaMent is executed. Prerequisites: the archiving feature must be activated and an archive depth must be specified. Possible values:

"true": Default setting. If the archive is active, a new version of the content item is generated.

"false": No new version of the content item is generated, even if the archive is active.

Value if nothing is specified: "true".

Result

The data for the content item specified are deleted in the language variant specified or in all language variants. The content item, the language variants, and all metadata remain intact.

128


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling


Removing Content from the Cache ('notify-cache')

Function

With the Content DynaMent in "notify-cache" mode, the cache is notified that certain content items you have specified have changed. It marks all related cache entries as invalid.

Note: This mode is deprecated and should no longer be used. Instead, use the "notify" mode of the Cache DynaMent.

See also:

Cache DynaMent (Page 97)Removing Entries from the Cache ('notify') (Page 107)

Syntax

<rde-dm:content mode ="notify-cache" content ="{project:content name}"

project ="{project name}" queue ="[no|yes]" attachment ="{attachment name}"

/>




Simple Call

<rde-dm:content mode="notify-cache" content="html-demo:news.htm" />



-26503 Incorrect locale specified


129


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Content DynaMent, here "notify-cache".

content (optional, alternative for parameter attachment) Name of the content item that will be deleted from the cache. You can also specify a project name, separating it with a colon (project name:content name). If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

project (optional) Name of the project containing the content. If nothing is specified: Project name specified in the content parameter. If no project is specified there, the project where the Content DynaMent is located is used.

queue (optional)

"no": The notification is sent immediately.

"yes": The notification is sent to a queue.


attachment (optional, alternative for parameter content) Name of the attachment that will be deleted from the object cache.

Result

The content item specified is marked as changed. All related cache entries are marked as invalid and removed from the cache.

Error Handling

The Content DynaMent's information, warning, and error messages begin with 26 in the thousands' place. You can send the return codes with the default parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following message is possible:



130

DynaMent ReferencesCPS DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

CPS DynaMent

The CPS DynaMent provides access to various system functions in RedDot LiveServer.


Generate unique system-wide IDs (mode="id")



Content DynaMent

CPS DynaMent

Message DynaMent

User DynaMent


Creating Unique IDs Within a Number Range ('id')

Purpose

The CPS DynaMent in "id" mode lets you create IDs that are unique within a number range.

You can use these IDs, for example, for registration processes that utilize e-mail confirmations to verify a mail account's validity with the generated ID.

Syntax

<rde-dm:cps mode ="id" name ="{name}" type ="[sequence|guid]"

op ="[next|get|set]" value ="{value}" project ="[{projectname}|cps]"

id-attribute = "{source:attributename}"

/>

131


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


tag ="[{tagname}|notag]" roles ="{userrole1;userrole2}" result-attribute ="{attributename}" report-tag ="{tagname}" rde-id ="{rde-id}" process-mode ="[standard|standard-recursive|


The standard parameter cachingtime cannot be used. This DynaMent sets the value of the caching time for the respective content to "0".

Simple Call

<rde-dm:cps mode="id" />

Generates a unique ID within a number range. An XML element <rde-rd:id-cps-guid> that encloses the ID is returned as the result. If no other parameters are specified, the ID is increased by "1". The result in this instance is: <rde-rd:id-cps-guid>1</rde-rd:id-cps-guid>

Parameters

mode Mode of the CPS DynaMent, here "id".

name (optional) Name of the number range. Value if nothing is specified: "cps-guid"

type (optional) Type of ID. The following options are available:

"sequence": Integer from a known number sequence in a number range.

"guid": Random, unique string; in addition to the name of the number range, the IP of the current server, the system time, and a random number are used to generate the GUID.

Value if nothing is specified: "sequence"

op (optional) Only for type="sequence": Method used to influence the ID. The following options are available:

"next": Increases the value of an ID (in the increment defined in value).

"get": Reads the value of an ID.

"set": Sets the value from the value parameter as the ID value.

Value if nothing is specified: "next"

value (optional) Only for type="sequence": Value that is to be used for the operation (op). The specified value is used in the LiveServer Repository as the starting value for other queries and is not generated.

132


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Value if nothing is specified: Depends on the value of parameter op: If op="next": "1" For op="set": "0" For op="get": The value parameter is ignored.

project (optional) Name of a project in which the IDs are valid. When you import and export projects, the current counter readings are imported and exported as well. The following options are available:

"{projectname}": Explicit specification of a project in which the IDs are valid.

"cps": The IDs are not project-specific. They are valid globally for content in the LiveServer Repository.

Value if nothing is specified: Name of the project containing the content.

id-attribute (optional) Specifies the origin (source) and name of an attribute where the generated ID will be written. The ID can be read from this attribute for further use later. Example: "session:guid". The default value for the source is "request" and can be omitted.

If nothing is specified: The generated ID is merely inserted as an XML element.

tag (optional) This is the tag name of the XML element that displays the result of the DynaMent.


"notag": The result is shown without the enclosing XML element.

Value if nothing is specified: "rde-rd:id-{numberrangename}"

Notes

RedDot LiveServer internally uses several number ranges with type="sequence", whose number range names all start with "rde". Do not use these reserved number range names in your DynaMents.

Result

The result is inserted as an XML element with the specified tag name.

Error Handling

The CPS DynaMent's information, warning, and error messages begin with 24 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:



133


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: type="guid"

<rde-dm:cps mode="id" type="guid" name="test"/>

Result:

<rde-rd:id-test> test-ffffffffc0a80251-f81bd0d867-6c9151080809e2ea

</rde-rd:id-test>

Examples: type="sequence"

<rde-dm:cps mode="id" type="sequence" name="test"/>

<rde-dm:cps mode="id" type="sequence" name="test" value="10"/>

Result:

<rde-rd:id-test>1</rde-rd:id-test>

<rde-rd:id-test>11</rde-rd:id-test>

Example: Using the id-attribute Parameter

Generating an ID:

<rde-dm:cps mode="id" name="atguid" type="guid" id-attribute="request:atguid"

/>

Reading an ID to compose a new content name:

<rde-dm:attribute attribute="atguidname" mode="write" source="request" value="[#request:atguid#].concat('.html')"

/>

134

DynaMent ReferencesImage DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Image DynaMent

The Image DynaMent is used to incorporate image files (with or without image attributes) in the delivered page. It is replaced at runtime by an image path. When you use an Image DynaMent, you can transmit any number of image attributes (width, height) to it. The Image DynaMent is used XSL style sheets, in combination with a Reference DynaMent, which is inserted in the corresponding XML document.


Integrate an image using the Image DynaMent

Use child elements to pass any number of image attributes to the image

Assign a link to an image

Inserting Images

Purpose

You use the Image DynaMent to insert an image file. The complete path is generated from the name of the blob and the project name and inserted in the HTML source code.

In order to insert an image with attributes, enter the image attributes as child elements of the Image DynaMent. The Image DynaMent is inserted in the XSL document. A Reference DynaMent is used to specify a link to the image in the corresponding XML document. You can use the Image DynaMent either with or without child elements.

Syntax

<rde-dm:image method ="html" tag ="{tagname}" > <attribute name>{value}</attribute name> ...

</rde-dm:image>




135


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

method Output method, here "html"

tag (optional) Tag name of the resulting XML element that displays the results of the DynaMent. If no value is specified: "image"

Child elements

The Image DynaMent has additional, optional child elements. DynaMents within values of child elements are processed. Inline notation is not supported, however.

<attribute name> (optional) Image attribute (example: width, height, border, align). You can enter as many attributes as you wish.

Error Handling

The Image DynaMent's information, warning, and error messages begin with 13 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".

The "content" variable in the Reference DynaMent is the name of the image file assigned to it during the blob import and not the file name itself.

136


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Image DynaMent without image attributes in combination with a Reference DynaMent:

Entry in the XML file:

<rde-dm:reference project="demo" content="banner_magazine_jpg"

tag="banner" text="ad banner"/>

Entry in the XSL file:

<rde-dm:image method="html" tag="banner" />

Intermediate result in HTML:

<img src="/{$rdePrefix}/xbcr/{$rdeSessionID}/master/

banner_magazine_jpg" />

Result in HTML:

<img scr="/imenu/xbcr/SID-3F57FBCE-56ADD8BF/master/banner_magazine_jpg"

alt="ad banner">

Image DynaMent with image attributes in combination with a Reference DynaMent:


<rde-dm:reference project="demo" content="banner_magazine_jpg"

tag="banner" text="ad banner"/>


<rde-dm:image method="html" tag="banner" >

<width>50</width>

<height>20</height> <border>0</border>

<align>middle</align>

</rde-dm:image>

Intermediate result in HTML:

<img src="/{$rdePrefix}/xbcr/{$rdeSessionID}/master/

banner_magazine_jpg" width=50 height=20 border=0 align="middle"/>

Result in HTML:

<img scr="/imenu/xbcr/SID-3F57FBCE-56ADD8BF/master/banner_magazine_jpg"

alt="ad banner" width=50 height=20 border=0 align="middle">

137


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Assigning Links to Images

Purpose

To assign a link to an image, you can combine the Image DynaMent with the Link DynaMent. The Image DynaMent is inserted in the XSL document together with the Link DynaMent. A Reference DynaMent is used to specify a link in the corresponding XML document. You can use the Image DynaMent either with or without child elements.

Syntax

<rde-dm:link tag ="link"

method ="html" >

<rde-dm:image method ="html" tag ="{tagname}" > <attribute name>{value}</attribute name> ...

</rde-dm:image>

</rde-dm:link>




Parameters

method Output method, here "html"

tag (optional) Tag name of the resulting XML element that displays the results of the DynaMent. If no value is specified: "image"

Child elements

The Image DynaMent has additional, optional child elements. DynaMents within values of child elements are processed. Inline notation is not supported, however.

<attribute name> (optional) Image attribute (example: width, height, border, align). You can enter as many attributes as you wish.

138


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The Image DynaMent's information, warning, and error messages begin with 13 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".

Image DynaMent in combination with Link and Reference DynaMents:


<news> <rde-dm:reference tag="link" project="demo" content="magazine" text="Magazine"/> <rde-dm:reference tag="image" project="demo" content="plane_jpg" text="plane"/>

</news>


<rde-dm:link tag="link" method="html"> <rde-dm:image tag="image" method="html" border="1"> <width>50</width> <height>20</height> <align>middle</align> </rde-dm:image>

</rde-dm:link>

139

DynaMent ReferencesImport DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Import DynaMent

The Import DynaMent differs from the other DynaMents in that it is executed when importing content to the LiveServer Repository, not when processing content. It is, however, addressed using the same syntax as other DynaMents and is therefore called the Import DynaMent.

The Import DynaMent is used to import the metadata of content items. When a content item is imported to RedDot LiveServer, this metadata is saved as content attributes and constraints. You can use this function, for example, to import categories and keywords from RedDot CMS. These are then used in the RedDot LiveServer as content attributes when a content item is imported.

The Import DynaMent is also used to import metadata via reference lists separately, for content that has already been imported or is due to be imported. This function is of particular use when importing binary content such as documents or images, which can also be enriched with metadata in this way.

You can also use the Import DynaMent to import and evaluate reference lists for content or content data that you wish to delete from the LiveServer Repository. This helps avoid inconsistencies between the Repository and another system, such as a content management system.

You can also use the Import DynaMent to define tags and assign them to content items and content snippets. You use the two child elements <rde-rd:tag> and <rde-rd:tag-assignment> to do this. You can use these elements for Import DynaMents with a content item, for reference lists (<rde-dm:reference>), and within Content DynaMents.

See also:

Importing/Deleting Metadata (Page 141)Importing Reference Lists for Metadata (Page 150)Importing Reference Lists for Content or Content Data to Be Deleted (Page 154)Defining and Assigning Tags (Page 155)

For more information about importing content with the Content DynaMent, see the separate section of the RedDot DynaMents documentation.


Importing Content ('import') (Page 110)

140


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Importing/Deleting Metadata

Purpose

The Import DynaMent is used to import the metadata of content items. In the RedDot LiveServer, this metadata is saved as content attributes and constraints for a content item. You can, for instance, use it to import categories and keywords from RedDot CMS. These are then used in the RedDot LiveServer as content attributes during import.

Syntax

<rde-dm:import> <keywords mode ="[set|add|add-list| delete|deleteall]" locale-policy ="[none|default|any]" keyword-separator ="," name-value-separator =":" hierarchy-separator ="." value-delimiters ="{value_delimiters}" resolve-entities ="[no|yes]" set-readonly ="[false|true]" set-password ="[false|true]" set-nonpersistent ="[false|true]" > attribute1:value1, attribute2:value2,... </keywords> <constraints mode ="[set|deleteall]" resolve-entities ="[no|yes]" > <constraint mode ="expression" description ="{description text}" > {constraint expression} </constraint> <constraint mode ="[condition|write]" attribute ={attributename} op ="{operator of Attribute DynaMent in condition or write mode}" value ="{value}" description ="{description text}" > </constraint> </constraints> <properties> <rde-rd:fulltextsearch> [{true}|{false}] </rde-rd:fulltextsearch> <rde-rd:validfrom format="{dateformat}"> {date} </rde-rd:validfrom> <rde-rd:validto format="{dateformat}"> {date} </rde-rd:validto> ...

141


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

</properties> <reference> ...

</reference>

<rde-rd:tag> ...

</rde-rd:tag>

<rde-rd:tag-assignment> ...

</rde-rd:tag-assignment>

</rde-dm:import>

Parameters/Child Elements

To import metadata of the current content item, the Import DynaMent has the optional child elements <keywords>, <constraints>, and <properties>.

To import metadata for referenced content, the <reference> child element is also required. To find out about how this element is used, see the section Importing the Reference List for Metadata.

Two other child elements, <rde-rd:tag> and <rde-rd:tag-assignment>, are needed to define and assign tags. For information on how to use them, see the section Defining and Assigning Tags.

<keywords> (optional) Specifies content attributes and values for a current content item. You can specify multiple <keywords> elements. You need to specify separators between each content attribute and its values (name-value-separator parameter). When specifying multiple attributes, you need to specify separators between the attribute-value pairs (keyword-separator parameter; example of default setting for separators: attribute1: value1, attribute2: value2). To create attributes without values, you can leave out the values. You do have to include the separators (example: attribute1:, attribute2:).

mode (optional) The way in which the attributes of a <keywords> element are to be handled. Value if nothing is specified: "set"

"set": Sets an attribute value according to the setting in the locale-policy parameter. The first time a value for the relevant attribute is set for the <keywords> element, existing attribute values are deleted in accordance with the setting in locale-policy. When multiple values are set for an attribute within the same <keywords> element, all values are added.

"add": Adds an attribute value according to the settings in the locale-policy parameter, if the value does not already exist.

"add-list": Adds an attribute value according to the settings in the locale-policy parameter, even if the value already exists.

"delete": Deletes the attribute values of the content attributes specified according to the setting of the locale-policy parameter. Attributes that have no attribute values and no child attribute values after deletion are deleted permanently.

142


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Note: When specifying multiple attributes, you also need to specify separators between attributes and values (name-value-separator parameter) and between attribute value pairs (keyword-separator parameter). Do not specify the values themselves (example of default setting for separators: attribute1:, attribute2:).

"deleteall": Deletes all the values of all attributes for a content item in accordance with the setting in the locale-policy parameter except the attributes specified. Attributes that have no attribute values and no child attribute values after deletion are deleted permanently. Note: When specifying multiple attributes, you also need to specify separators between attributes and values (name-value-separator parameter) and between attribute value pairs (keyword-separator parameter). Do not specify the values themselves (example of default setting for separators: attribute1:, attribute2:).

locale-policy (optional) Rule on language usage to be applied to entries in the <keywords> element. Value if nothing is specified: "default"

"none": Attribute values are only written in the current language. This is set using the "Language" drop-down list during import.

"default": Attribute values are only written in the default language for the project into which you are importing. If there is no default language, the current language is used.

"any": Attribute values are written in all languages of the project into which you are importing.

keyword-separator (optional) Separator between multiple attribute-value pairs (for example: profile:3, category:5). Make sure you only use this character as a separator and not in attribute names or values. You can only specify one character. Value if nothing is specified: "," (comma). Note: An attribute can take several different values. Multivalue attributes are also implemented in the form of multiple attribute-value pairs (for example, profile level:1, profile level:5) and not by character-delimited values. level:1, level:5), not by character-delimited values.

name-value-separator (optional) Separator between attribute and assigned value (for example, level:3). You can only specify one character. Value if nothing is specified: ":" (colon).

hierarchy-separator (optional) Separator between attributes for attribute path information in the attribute hierarchy (for example: profile.level:7). The attribute after the separator is a child attribute of the first attribute. Separators that occur within the value of an attribute are not recognized as separators; they are taken as part of the value. You can only specify one character. Value if nothing is specified: "." (period). Categories in RedDot CMS that are to be passed to RedDot LiveServer must only contain this separator if they are intended to achieve a hierarchical structure in RedDot LiveServer.

value-delimiters (optional) Text block separators for enclosing attribute values. These make it possible for you to use a variety of characters in values, for example, even those defined as separators.

143


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

The specification of one or more text block separators for attribute values. Enter the characters one right after the other (without spaces or separators). Each character you enter is interpreted as a text block separator. If the first character of an attribute value is one of the characters specified as a text block separator, it will be treated as the opening separator for this value and thus must also close the value. If nothing is specified: No text block separator is used. Note: If you want to use double quotation marks (") and backslashes (\) as text delimiters, you have to model them as an escape sequence — that is, with a leading backslash (example: value-delimiters="\"").

resolve-entities (optional) Specifies whether entities in attribute names or values are converted to their corresponding Unicode characters (for example: ä -> displays as ä). Value if nothing is specified: "no"

"yes": All entities are resolved according to the included DTD definition file (at <RedDot Web application path>/WEB-INF/var/xml/doctype.txt). This setting is helpful, for example, if an external system delivers HTML code with entities that are to be used as attribute values in Unicode in RedDot LiveServer.

"no": Entities are not resolved.

set-readonly (optional) Determines whether an attribute can be edited. Each attribute within the <keywords> element is given the property specified here during import:

"false": Default setting. Attribute values can be written. The attribute itself can be edited or deleted.

"true": Attribute values can neither be written in the dialogs for editing nor using the Attribute DynaMent. The attribute itself cannot be edited or deleted. This setting is equivalent to selecting the Read only check box in the dialogs for editing attributes.


set-password (optional) Defines how attribute values are displayed. Each attribute within the <keywords> element is given the property specified here during import:

"false": Default setting. All characters of attribute values are displayed unencrypted.

"true": All characters of attribute values are displayed as the placeholder "*****". This applies to the display of values in the GUI, in log files, and in projects. Even after processing by an Attribute DynaMent (such as reading), placeholders are shown for these attribute values. This setting is equivalent to selecting the Display value as asterisks check box in the dialogs for editing attributes.


set-nonpersistent (optional) Defines whether changes to an attribute are saved. Each attribute within the <keywords> element is given the property specified here during import:

144


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"false": Default setting. Changes to the attribute are saved to the LiveServer Repository or a directory service.

"true": The attribute can be edited, but the changes are not written to the LiveServer Repository or a directory service. This setting is equivalent to selecting the Do not store value check box in the dialogs for editing attributes.


Note: An entry in the <keywords> element with default settings corresponds to the return value from the RedDot CMS Info element Page: Categories and Keywords that uses the comma as a separator. It inserts the categories and keywords assigned to the current content.

<constraints> (optional) Contains a list of content constraints for individual elements <constraint>; specifies content constraints for the current content item.

mode (optional) Mode for all content constraints. Value if nothing is specified: "set"

"set": Sets the specified content constraints in accordance with the remaining child elements and parameters.

"deleteall": Deletes all content constraints for the content items specified. Note: With mode="deleteall", additional child elements are neither necessary nor useful.

resolve-entities (optional) See above for details: parameter resolve-entities under <keywords>.

<constraint> (optional) Specifies a single content constraint for the current content item.

mode Mode for this content constraint, constraint type:

"expression": With this constraint type, a logical expression that connects multiple attribute constraints can be evaluated. Content is only delivered if the expression as a whole is met. This function is equivalent to the <rde-dm:constraint> child element of the Attribute DynaMent in "condition" mode. The only difference is: You cannot use "XPath" or "context" as source.

"condition": With this constraint type, a constraint for a user attribute is evaluated. The content is only delivered if the constraint is met for the user of the requesting session. This function is equivalent to an Attribute DynaMent in "condition" mode for source="user".

"write": Strictly speaking, this constraint type is an event and cannot prevent delivery of content. Rather, at each delivery, a user attribute for the user of the requesting session is written. This function is equivalent to an Attribute DynaMent in "write" mode for source="user".

attribute (only for mode="condition" and "write"): Full attribute path of a user attribute (example: "profile.level").

145


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

For mode="condition": User attribute for whose value or list of values this constraint is to be evaluated.

For mode="write": User attribute for which a value is to be written.

op (only for mode="condition" and "write"): Operator. The way in which the specified user attribute is to be handled.

For mode="condition": It is possible to use all operators that are valid for the Attribute DynaMent in "condition" mode.

For mode="write": It is possible to use all operators that are valid for the Attribute DynaMent in "write" mode.

value (only for mode="condition" and "write"): Value that is to be used for the operation.

For mode="condition": Value or value list that the value/value list of a user attribute is to be compared with. Multiple values are separated by semicolons.

For mode="write": Value to be written. You can only specify one value.

description (optional) Description text for a content constraint.

{constraint expression} only for mode="expression": Placeholder for an expression that can consist of several constraints, linked by logical operators (AND, OR, NOT) and parentheses. If the whole expression is met, the relevant content item is delivered. The syntax must be the same as that used in the <rde-dm:constraint> child element of the Attribute DynaMent in "condition" mode. See the description there.

<properties> (optional) Specifies additional properties of the content for import in separate child elements. The tag names of these child elements must begin with namespace identifier "rde-rd:". The subsequent tag name is then the name of the content property whose value you want to set. The name of a content property can be any name for which a setter method with exactly one primitive parameter is documented in the CoaContent class of the open API. The prefix, "set", is omitted, and the subsequent name is converted to lower-case. Example: Method: setFullTextSearch(boolean) Tag name: rde-rd:fulltextsearch

Examples (for more information, also see the example below):

<rde-rd:validfrom> (optional) Specifies the date and time from which the content is valid (default format: yyyy.mm.dd hh:mm:ss). If nothing is specified: The content is valid immediately and until rde-rd:validto.

format (optional) Specifying a date format. The date is evaluated according to the java.text.SimpleDateFormat documentation. Value if nothing is specified: yyyy.mm.dd hh:mm:ss. You do not need to specify seconds. If the values specified are incorrect, the content item is not imported.

146


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-rd:validto> (optional) Specifies the date and time up to which the content is valid (default format: yyyy.mm.dd hh:mm:ss). If nothing is specified: The content is valid from rde-rd:validfrom and indefinitely. If no values are specified for rde-rd:validfrom or rde-rd:validto: The content is valid immediately and indefinitely.

format (optional) Specifying a date format. The date is evaluated according to the java.text.SimpleDateFormat documentation. Value if nothing is specified: yyyy.mm.dd hh:mm:ss. You do not need to specify seconds. If the values specified are incorrect, the content item is not imported.

<reference> (optional) Optional child element to import metadata for reference content. For more information about this child element and its parameters, see the section Importing Metadata Reference Lists.

<rde-rd:tag> and <rde-rd:tag-assignment> (optional) Optional child elements to define and assign tags. For more information about these child elements and their parameters, see the section Defining and Assigning Tags.

Notes

An Import DynaMent is also executed if it is placed within an HTML comment.

Result

When a content item is imported, the metadata specified are also imported and assigned to the content item as attributes and constraints. Note: If the content constraints or content attributes specified are invalid, the content import is aborted and an error message is returned.

147


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Use of the Import DynaMent to pass content attributes and constraints to the current content. The Import Dynament can be located anywhere within the content:

<rde-dm:import> <keywords> attribute1: value1, attribute1: value 2, attribute 2: value 3, attribute3.subattribute3: value 4,

</keywords>

<constraints> <constraint mode="condition" attribute="profile.level" op="gt" value="2" description="profile.level greater than 2"

/>

<constraint mode="write" attribute="profile.track.filename.html" op="increase" value="1" description="increase by one for profile.track.filename.html"> </constraint>

</constraints>

</rde-dm:import>

As a result, the specified content attributes and constraints are assigned to the current content item when it is imported to RedDot LiveServer. A content item is assigned three content attributes, of which the first has two values and the third has two hierarchy levels. Two content constraints are also assigned to the content, the first in "condition" mode and the second in "write" mode.

Example: Child element <properties>, different properties and date formats:

<rde-dm:import> <properties>

<rde-rd:fulltextsearch>true</rde-rd:fulltextsearch> <rde-rd:validfrom> 2008.01.22 12:00:00 </rde-rd:validfrom> <rde-rd:validto format="yyyy-MM-dd HH-mm"> 2008-01-23 12-00 </rde-rd:validto>

</properties> </rde-dm:import>

This is a test

148


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

For more information about constraints and attributes, see the Projects/Contents documentation.

See also:

Checking Constraints for Attributes ('condition') (Page 61)Writing Attributes ('write') (Page 49)

149


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Importing Reference Lists for Metadata

Purpose

The Import DynaMent is also used to import metadata via reference lists separately for content that has already been imported or is due to be imported.

When importing content to the LiveServer Repository, you cannot directly assign separate metadata (for example, content attributes and constraints) to every content item. This applies particularly to binary content (content type BLOB). If you want to assign metadata to this content as well, you have to import the metadata separately. You do this by importing XML files that use an Import DynaMent to make reference lists available that contain metadata for content to be imported or that has already been imported. These XML files are imported like normal content and are evaluated by RedDot LiveServer during import. The file name can be assigned freely.

Using multiple Import DynaMents, you can assign different metadata to different content items within one file. <rde-dm:reference> child elements with the references are inserted in a <rde-dm:import> element. The <keyword>, <constraints>, and <properties> child elements specify the metadata for all referenced content items within an <rde-dm:import> element.

Syntax

<rde-dm:import> <rde-dm:reference type ="[internal|external]" locale ="{locale string}" content-type ="[blob|XML|XSL|HTML|script]" group ="{contentgroup}" exclusive ="[yes|no]" release ="[true|false]" > {content} </rde-dm:reference> <keywords ... </keywords> <constraints ... </constraints> <properties> ... </properties> <rde-rd:tag> ... </rde-rd:tag>

<rde-rd:tag-assignment> ... </rde-rd:tag-assignment>

</rde-dm:import>

150


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


<rde-dm:reference> Each instance indicates a reference to a content item. There can be multiple child elements.

type Type of reference:

"internal": Default setting; the referenced content must already be located in the LiveServer Repository. When the Import DynaMent is called, additional metadata is imported, which you specify in the <keywords>, <constraints>, and <properties> child elements. The Import DynaMent has no effect on content items that are not present in the repository. The relevant <rde-dm:import> sections of the XML file are written to a log file. The file is called rde-import-<import_date>-<name_of_import_job>-<name_of_import_definition>.xml in directory <RedDot Web application path>/WEB-INF/var/log/. This allows entries to be used again for a subsequent import process.

"external": Either the referenced content item is not yet contained in the LiveServer Repository, or the content is to be overwritten by a referenced content item. The referenced content is imported with the metadata you have specified in the <keywords>, <constraints>, and <properties> child elements. If a referenced content item is already in the LiveServer Repository, it is overwritten during import. The system searches for the file with the name specified in the <reference> element of the reference file, either in the root directory of the import job or in the subdirectory of the import definition. The reference file and the referenced content must be located in the same directory when they are imported. If a referenced file is available, a content item of the type specified in the import job (usually BLOB) is created and filled with content from the file. If a content item is not found in this directory, this is written to a log file - as it is for type="internal". This allows entries to be used again for a subsequent import process.

locale (optional) Selecting a content language that the metadata should be assigned to. For other language variants of the content, no metadata is imported. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. Value if nothing is specified: All languages of the content item.

content-type (optional) The content type of the referenced content. All RedDot LiveServer content types are permitted here: "BLOB", "XML", "XSL", "HTML", and "Script". If nothing is specified: A content type is selected according to the file name extension. If the file name extension for a content item cannot be assigned, the default setting "BLOB" applies.

group (optional) The name of a content group that is assigned to the content item to be imported. If names of content and content groups are not unique project-wide: Value of the path name of the content group within the content group hierarchy. The path components are separated by slashes (example: demo/countries/countriesxml). If nothing is specified: The content item is assigned the same group as the content item containing the Import DynaMent.

151


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

exclusive (optional) Determines whether only referenced content is imported (default setting) or whether the import also includes the content item containing the Import DynaMent. Value if nothing is specified: "yes"

"yes": Only referenced content is imported. The content item containing the Import DynaMent is not imported.

"no": The content item itself is imported before any referenced content. The Import DynaMent is removed from the content.

release (optional) Determines whether the referenced contents are released during import and overwrites the setting of the import definition (Import in released status check box). If nothing is specified, the setting of the import definition is applied.

"true": The referenced contents are imported with Released status. Note: If existing content is to be released, the Replace existing content check box in the import definition must be selected.

"false": The referenced contents are imported with Draft status. This only applies if the content has also been changed, however.

{content} Placeholder for the name of the referenced content. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

<keywords>, <constraints>, and <properties> (optional) The values specified for <keywords>, <constraints>, and <properties> always apply to all content items referenced within an <rde-dm:import> section. For more information about these two child elements and their parameters, see the section Importing Metadata.

<rde-rd:tag> and <rde-rd:tag-assignment> (optional) Optional child elements to define and assign tags. For more information about these child elements and their parameters, see the section Defining and Assigning Tags.

Notes

You can define the import of an XML file with reference lists for metadata via the import definition of an import job. Import the reference file itself as content type "XML", since it would not be evaluated as content type "BLOB". The settings for import of the reference file let you determine the settings for the referenced content (for example, whether imported content has Draft or Released status or whether the local files are deleted following a successful import).

Result

The reference file is read on the basis of an import job and is evaluated according to the defined elements. The metadata specified are imported to the LiveServer Repository and assigned to the referenced content as attributes and constraints. The reference file itself is not imported unless the exclusive="no" parameter is set in at least one <rde-dm:reference> element.

152


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

See also:

Importing Reference Lists for Content or Content Data to Be Deleted (Page 154)Importing/Deleting Metadata (Page 141)Defining and Assigning Tags (Page 155)

Reference to Internal Contents Imported with a Prefix

If you import content with the setting Use subdirectory name as prefix for content name or you specify a Prefix for content names, the file name of the content is changed. You can only assign metadata to this content correctly at a later point if you use the same settings for referenced content items in the import job for the reference list. Otherwise content names cannot be found and the metadata cannot be assigned.

Example: File with Multiple Import DynaMents

<rde-dm:import> <rde-dm:reference type="internal" content-type="" group="" exclusive="no">test.gif</rde-dm:reference> <keywords mode="set" locale-policy="none" keyword-separator=";" name-value-separator="=" hierarchy-separator="." resolve-entities="yes">

Author=author1;Language=en-US </keywords>

</rde-dm:import>

<rde-dm:import> <keywords mode="set" locale-policy="none" keyword-separator=";" name-value-separator="=" hierarchy-separator="." resolve-entities="yes">

RDChangeAuthor=author2;Language=en-US </keywords> <constraints mode="set" resolve-entities="yes">

<constraint mode="expression" description=""> </constraint>

</constraints>

</rde-dm:import>

153


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Importing Reference Lists for Content or Content Data to Be Deleted

Purpose

You can use the Import DynaMent to import and evaluate reference lists for content or content data of one language that you wish to delete from the LiveServer Repository.

You frequently import content from an upstream system, such as a content management system, to the LiveServer Repository. When content is deleted in the upstream system, you also need to delete it in the LiveServer Repository to avoid inconsistencies. You can do this by importing lists of the names of the deleted content to the LiveServer Repository.

This is done by importing XML files that use an Import DynaMent to supply reference lists of the content or content data to be deleted. These XML files for deleting content are imported in the same way as normal content and are evaluated during import to the RedDot LiveServer. The file name can be assigned freely.

Syntax

<rde-dm:import> <rde-dm:reference type ="delete" locale ="{locale string}" > {content}

</rde-dm:reference> ...

</rde-dm:import>


<rde-dm:reference> Each instance indicates a reference to a content item. There can be multiple child elements.

type Type of referencing, here "delete" Determines that the content item whose name is specified in the value for the element is to be deleted from the LiveServer Repository.

locale (optional) Selects the language whose content data is to be deleted. The content data of other language variants of the content are not deleted. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. If no value is specified: All content in all language variants

{content} Placeholder for the name of the referenced content. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

154


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Notes

You can define the import of an XML file with the reference list via the import definition of an import job. Import the reference file itself as content type "XML", since it would not be evaluated as content type "BLOB". The settings for importing a reference file also determine the settings of the referenced content (for example, whether the files are also to be deleted locally).

Results

The specified content items or content data of a language are deleted from the LiveServer Repository when the reference file is imported. The reference file itself is also deleted after import, both from the LiveServer Repository and locally.

If the content items in the reference list are not in the LiveServer Repository, the Import DynaMent for these items has no effect. The relevant <rde-dm:import> sections of the XML file are written to a log file. The file is called rde-import-<import_date>-<name_of_import_job>-<name_of_import_definition>.xml in directory <RedDot Web application path>/WEB-INF/var/log/.

See also:

Importing Reference Lists for Metadata (Page 150)Importing/Deleting Metadata (Page 141)Defining and Assigning Tags (Page 155)

Deleting Content Imported Including a Prefix

If you import content with the setting Use subdirectory name as prefix for content name or you specify a Prefix for content names the file name of the content is changed. You can subsequently delete this content correctly only if you use the same settings in the import job for the content to be deleted. Otherwise content names cannot be found and the content cannot be assigned.

Defining and Assigning Tags

When you import content with the Import DynaMent, you can both define tags and assign tags to content items and content snippets.

The Import DynaMent has two child elements, <rde-rd:tag> and <rde-rd:tag-assignment>. You can use these elements for Import DynaMents with a content item, for reference lists (<rde-dm:reference>), and within Content DynaMents. You can specify multiple child elements to enable complex combinations of deleting, adding, and setting tags.

155


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:import>

...

<rde-rd:tag> <name>{tagname}</name> <type>{community|editorial}</type> <storage-project>{project name}</storage-project>

<author>{username}</author> <description>{description}</description>

<weight>{weight}</weight> <rubrics> <rubric>{category name}</rubric> ...

</rubrics>

<rde-rd:tag>

<rde-rd:tag-assignment mode ="[add|set|delete| delete-all|delete-types]" delete-types ="[community|editorial]" configuration-project="..." tagging-configuration="..." > <rde-rd:targets> <rde-rd:target> <type>[content|content-snippet|{type name}]</type> <project>{project}</project> <content>{content}</content> <guid>{guid}</guid> <variant>{variant}</variant> <locale>{locale}</locale> <owner>{content; content;...}</owner> </rde-rd:target> ... </rde-rd:targets> <rde-rd:tags> <rde-rd:tag-name>{tagname}</rde-rd:tag-name> ...

</rde-rd:tags>

</rde-rd:tag-assigment>

...

</rde-dm:import>

Child Element Parameters

<rde-rd:tag> Child element for defining tags.

<name> Tag name.

<type> Tag type. Possible values:

"community": Default type. Is also assigned when end users assign tags.

"editorial": Tags created by an editor or administrator.

156


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<storage-project> Name of the project where the tags are saved.

<author> (optional) User name of tag creator.

<description> (optional) Description of the tag.

<weight> (optional) Integer that defines the tag weight for voting.

<rubrics> (optional) List of tag categories in single <rubric> elements.

<rubric> (optional) Name of an individual tag category.

<rde-rd:tag-assignment> Child element for assigning tags to the specified target objects in the specified tagging/voting configuration.

mode Operator for tag assignment. Possible values:

"add": The specified tags are added to the specified target objects if they have not been assigned yet.

"set": The specified tags are always assigned to all specified target objects. Any existing tag assignments are overwritten.

"delete": The assignments of the specified tags to the specified target objects are deleted.

"delete-all": The assignments of all tags to the specified target objects are deleted.

"delete-types": The assignments of tags that have one of the types specified in the delete-types parameter are deleted.

delete-types (optional; only for mode="delete-types") Type of tags whose assignments you want to delete. Possible values:



configuration-project Project name of the tagging/voting configuration.

tagging-configuration Name of the tagging/voting configuration. If nothing is specified: The first tagging/voting configuration of the project.

<rde-rd:targets> (optional) List of target objects that are assigned tags, in individual <rde-rd:target> elements.

If nothing is specified: The tags with type="content" are assigned to the content item and language variant to which the surrounding Import DynaMent refers. If an <rde-dm:reference> element is specified in the surrounding Import DynaMent, the content

157


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

item specified there is the reference content. If multiple <rde-dm:reference> elements are used, the specified tag assignments are executed for all reference content items for which no separate target objects are specified.

<rde-rd:target> Single target object that is assigned tags.

<type> Type of target object. Possible values:

"content": Content item in RedDot LiveServer. The additional parameters project, content, and locale (or variant) are evaluated for this type.

"content-snippet": Snippets from content in RedDot LiveServer. They can include pages from RedDot CMS, for example, that are composed when publishing a Web site. A snippet can be used in multiple content items in RedDot LiveServer. The additional parameters project, guid, content, and locale (or variant) are evaluated for this type.

"{type name}": User-defined type name. The additional parameters project, guid, variant, and owner are evaluated for this type.


<project> Project in RedDot LiveServer that contains the target object.

<content> Only used for type="content" and type="content-snippet". Content item in RedDot LiveServer as a target object.

<guid> (not evaluated for type="content") GUID of the target object.

<variant> (optional) Variant within the target object. For target objects types "content" and "content-snippet": Language variant to which the assigned tag refers. The locale parameter can be also be used alternatively for these two types.

<locale> (optional) Only used for type="content" and type="content-snippet". Language variant to which the assigned tag refers.

<owner> (optional, not evaluated for type="content") Content item or semicolon-separated list of content items in RedDot LiveServer in the project specified in the project parameter. If you use this element, the defined tag assignment is deleted from the database automatically when the last of the specified content items is deleted (relational integrity).

<rde-rd:tags> List of tags that are assigned to target objects in individual <rde-rd:tag> elements.

<rde-rd:tag-name> Single tag assigned to the target objects.

More information about the Import and Content DynaMents is available in the separate sections.

For more information about assigning tags with the Tagging DynaMent, see the separate sections.

158


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


Importing Reference Lists for Metadata (Page 150)Importing/Deleting Metadata (Page 141)Importing Content ('import') (Page 110)Tagging DynaMent (Page 407)Assigning Tags ('assignTags') (Page 420)

Example: Creating and Assigning Tags

<rde-dm:import> <rde-rd:tag> <name>sports</name> <type>community</type> <storage-project>demo</storage-project> </rde-rd:tag> <rde-rd:tag> <name>news</name> <type>editorial</type> <storage-project>demo</storage-project> </rde-rd:tag> <rde-rd:tag-assignment mode="add" configuration-project="demo" tagging-configuration="demo-tagging"> <rde-rd:targets> <rde-rd:target> <project>demo</project> <type>content</content> <content>index.html</content> <locale>en</locale> </rde-rd:target> </rde-rd:targets> <rde-rd:tags> <rde-rd:tag-name>sports</rde-rd:tag-name> <rde-rd:tag-name>news</rde-rd:tag-name>

</rde-rd:tags> </rde-rd:tag-assignment>

</rde-dm:import> In this example, two tags are created first using <rde-rd:tag> child elements. The <rde-rd:tag-assignment> child element is then used to assign tags. The tags specified in the <rde-rd:tags> element are assigned to the content item specified in the <rde-rd:targets> element as the target object.

159

DynaMent ReferencesInclude DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Include DynaMent

The Include DynaMent includes additional content items at runtime. In addition to internal contents, external pages can also be used such as JSP or PHP pages. Session and user information for external pages can be transmitted in both directions via this DynaMent.


Integrating internal and external content using the Include DynaMent (mode="include|text")

Including Weblet module placeholders (mode="include")

Including specific versions of a content item (mode="include-version")

Including the difference between different content items or content versions (mode="diff").

Integrating Internal or External Content

Purpose

You can use the Include DynaMent to insert both internal content from the LiveServer Repository and external content into a requested content item. This allows you, for example, to call external pages such as JSP or PHP pages, depending on the current RedDot LiveServer session. The Include DynaMent is replaced by the content it references, for example, HTML or XML, at runtime. You can also use the <rde-rd:import> child element to add metadata to an external content item. The optional child element <rde-rd:http-headers> lets you add header fields to the Include DynaMent request for external content.

Content items with constraints are not integrated until the constraints are met for the user of the requesting session.

You can use an Include DynaMent to insert a special Weblet module placeholder in a Weblet result, instead of inserting external content. To find out how, read the separate section.

See also:

Including Weblet Module Placeholders (Page 177)

160


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:include mode ="[include|text]" content ="{content}" depth ="[0|1|...n]" validfrom ="{yyyy.mm.dd hh:mm:ss}" validto ="{yyyy.mm.dd hh:mm:ss}" locale ="{locale string}" locale-policy ="[none|default|any]" onerrorscript ="{projectname:contentname}" prerequestscript ="{projectname:contentname}"

postrequestscript ="{projectname:contentname}" script-requestparams ="[none|readonly|readwrite]"

contenttype ="[text/xml|...]" method ="[GET|POST|MULITPART]"

buffer-stream ="[discard|keep]" appserver ="[yes|no]"

timeout ="{timeout in seconds}" track-mode ="[none|name|structure|

attributes|{track-mode}]" encoding-flags ="[subtype_declaration_use|

subtype_declaration_force| subtype_declaration_none|

UTF-8_guess|XML_default_UTF-8| force_encoding_type_xml| force_encoding_type_html]"

include-mode ="[{include-mode},{tagname};]" context-tags ="[{tagname},{context-mode};]" context-mode ="[mixed|cdata|xml|none]"

attributepath ="{content attribute list}" metainfo ="[rdeallmetainfo|{header field};*]" project ="{project name}"

cache-id ="{cache-id}" size-max ="{size in KB}" size-swap ="{size in KB}"

contentinclude-attribute ="{attribute name}" stylesheet ="{stylesheetname}"

class ="{classname}" content-fixed ="[no|yes]" content-qualifier ="{qualifier}" > <rde-rd:import>

...metadata... </rde-rd:import> <rde-rd:http-headers>

<rde-rd:http-header name="{headerfield}"> {value}

</rde-rd:http-header> </rde-rd:http-headers>

</rde-dm:include>

161


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Simple Call

<rde-dm:include content="text.html"/>

Parameters

mode (optional) Include DynaMent mode for the internal processing of content, dependent on the content type.

"include": Default setting

"text": Additional mode for all content types. Every processed content item is saved as simple text, without additional internal administration structures, encapsulated in a CDATA section, and inserted. This encapsulation provides for XML-compliant presentation. This mode is needed, for example, to integrate content in an e-mail (Message DynaMent).

If nothing is specified: "include" The system automatically selects the appropriate mode for the content type:

XML content is saved without changes ("xml" mode).

HTML content is enclosed with an <rde-html> root element ("html" mode).

Script content is assigned root element <SCRIPT language="javascript"> and is saved in a CDATA section with HTML/XML comments, as is expected in an HTML document ("javascript" mode).

content Name of the inserted content. For internal content: The syntax is "projectname:contentname". If the project is not specified, then the current project is accessed. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml). For external content: No project is specified and the name of the content item begins with http://, https://, or file://. The request uses the specified URL. Note: You can only insert content items with content type XSL into XSL content. This rule speeds up the change notification in the rendering engine pool.

depth (optional) To avoid endless loops in the Include DynaMent's result, the depth parameter limits the number of nested executions of Include DynaMents. If the limit specified in depth is reached,

162


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

the corresponding DynaMent is no longer executed. This limit also applies to nested identical PSX modules. Value if nothing is specified: "10"

validfrom (optional) Specifies the date and time from which the Include DynaMent is valid (format: yyyy.mm.dd hh:mm:ss). You do not need to specify seconds. If the values specified are incorrect, the content item is not inserted. If nothing is specified: The Include DynaMent is valid immediately and until validto.

validto (optional) Specifies the date and time up to which the Include DynaMent is valid (format: yyyy.mm.dd hh:mm:ss). You do not need to specify seconds. If the values specified are incorrect, the content item is not inserted. If nothing is specified: The Include is valid without limitation from validfrom. If no values are specified for validfrom or validto: The Include DynaMent is valid immediately and without limitation.

locale (optional) Language of content inserted. Use the RFC 4646 language codes, for example de or en-US. You can enter several locales separated by semicolons ";". The locale parameter affects both the respective content attribute and the display of content data of the selected content. For internal content: When you specify multiple locales, the system searches for the languages in the order specified and uses the first language found. If there is no content data in the RedDot LiveServer Repository for any of the languages specified, a fallback language is determined in accordance with the Locale Policy. This is usually the default project language. For external content: The locales specified are written to the Accept-Language header field; this is interpreted depending on the external server.

Value if nothing is specified: User language of the requesting session.

locale-policy (optional) Used only for internal content: Locale policy to access content data and attribute values: If a content item or attribute has no value for the language variant determined by the locale parameter, the value for a different variant is read. Possible settings:

"none": If a value is not available in the language you require, no values are read in any other language.

"default": If a value is not available in the language you require, the value for the project default language specified in the project settings is read. If no value is available there either, the value for the default language specified in the system configuration (key: reddot.locale.default) is read. If no value is available in this language, nothing is read.

"any": If a value is not available in the language you require, the value for the project default language is read. If no value is available there either, the value for the default language specified in the system configuration (key: reddot.locale.default) is read. If no value is available in that language, the system searches for and reads the first available value in one of the languages, following the order of languages specified in the project settings.

If nothing is specified: "none"

163


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

onerrorscript (optional) Internal script that is executed if an error occurs when requesting a content item. It may, for example, supply a default content item. The syntax is "projectname:contentname". If the project is not specified, then the current project is accessed. Only internal scripts are supported. When the script is run, the values of the default variables content and type are not supplied (see also Script DynaMent). The name of the content is supplied in the contentid variable instead. A valid XML document is expected as the result in the result variable.

prerequestscript (optional) Used only for external content: Internal script with which you can control the external request. The syntax is "projectname:contentname". If the project is not specified, then the current project is accessed. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml). Only internal scripts are supported. Before the request is sent, you can

Insert headers [variable header with type hash table, for example, header.put(key,value)] or

Change the URL (variable url) or

Change the content type (contenttype variable) or

Change the method (method variable, for example, POST, GET).

When the script is run, the values of the default variables content and type are not supplied (see also Script DynaMent). Instead, the values of the variables url, method, header and contenttype are supplied. There is no further processing of the result in the result variable.

postrequestscript (optional) Internal script that is run after the request and before delivery in order to manipulate the content. The syntax is "projectname:contentname". If the project is not specified, then the current project is accessed. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml). Only internal scripts are supported. The content is supplied in the string variable content. The manipulated content is expected in the result variable (see also Script DynaMent).

script-requestparams (optional) Controls access to request parameters in Python scripts: In previous versions, request parameters had been provided as a variable in Python script. This function is deprecated and should no longer be used. Instead use the following method for accessing the request parameters:

An object of the type de.reddot.api.web.WebletRequest that has been generated new for the Python script, is provided in the webletRequest variable, which only serves as a container for the request parameters. You can access the request parameters with the methods of this class described in the API documentation. These settings are available:

"none": No object is passed on to the script. Request parameters can be neither read nor written.

164


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"readonly": The object is passed on to the script. Request parameters can be read.

"readwrite": The object is passed on to the script. Request parameters can be read and written.

Value if nothing is specified: "none"

contenttype (optional) Used only for external content: Information pertaining to content type, which influences further processing of the returned external content. The content type is specified similar to the content type header of an HTTP/1.1. It consists of a MIME type and optional parameters, which are separated by semicolons. It is also possible to enter just a segment of the string as value. Here is a typical example:

contenttype="text/html; charset=UTF-8"

The specification of a contenttype has the following effects:

Rejection of returned external content If the contenttype parameter is specified and the returned external content also includes a content type header field, the content will be accepted only if the parameter value appears in the value of the content type header field as a string. Spaces, case sensitivity, and charset information are not considered during this check. In this way, you can be sure that the external content type that you receive meets your expectations — and does not contain, for example, an image instead of HTML content.

Specification of the charset used to transform the received external byte flow into a string. The charset parameter of the content type header field, which is sent along with the content, is used to transform the byte flow into a string. Many Internet applications do not send such charset information or it is often incomplete. The HTTP/1.1 standard specifies that in such cases the charset=ISO-8859-1 should be used. If this standard is not appropriate for use (which is possible) and special characters cannot be displayed correctly, you can specify an optional charset by entering it as a charset=.... value in the contenttype parameter. Be sure that your Java Runtime Environment has the same charset available.

165


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Specification of the internal content type in RedDot LiveServer for the returned external content Even the internal content type of the received external content is determined by the accompanying content type header field. Where this is not possible, the value of the contenttype parameter is used. The following rules regulate which MIME types are recognized as which internal content types:

method (optional) Used only for external content: Method for transmitting request parameters.

"GET": defined in the HTTP protocol. The Request parameters are transmitted in the query string as part of the URL.

"POST": defined in the HTTP protocol. The Request parameters are not transmitted as part of the URL but as part of the message. The amount of data permitted is much larger than for "GET".

"MULTIPART": This method is used to forward multipart requests that were originally sent to the RedDot LiveServer to an external URL via the Include DynaMent. HTTP requests use the "POST" method. Observe the following notes on method="MULTIPART":

External content included by this Include DynaMent will not be processed by the RedDot LiveServer's processor, that is, DynaMents within the content will not be executed.

A multipart request is usually read only once in RedDot LiveServer, and is then no longer available. To use a multipart request several times, you can temporarily save it using the buffer-stream="keep" parameter.

RedDot LiveServer provides the form values as request attributes using the Attribute DynaMent until the file is detected in the multipart request.

method="MULTIPART" can only be executed on RedDot LiveServer's application server component if this component runs on the same Java virtual machine as the RedDot LiveServer Web server component. Otherwise use appserver="no" to specify execution of the DynaMent on the Web server component.

Value if nothing is specified: "GET"

MIME types Content type

"*/xml", "*+xml" or "*/rss*" XML

"text/xsl" XSL

"*/html" or "*/xhtml" HTML

"javascript". Content is entered using: <script language="javascript">

</script>

Script

The internal content type for each additional MIME type is read from the mimetype.txt file (located in the <RedDot Web application path>/ WEB-INF/etc directory), which contains a wide range of mappings. If a MIME type is not listed in the file, you can add it.

166


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

buffer-stream (optional) Used only with method="MULTIPART": Specification of whether the multipart request should be temporarily saved for use after its initial call.

"discard": The multipart request is discarded after processing and cannot be read later.

"keep": The multipart request is temporarily saved and can be read later. This can take up a lot of memory, particularly if a multipart request involves very large files; only use this setting when required.

Value if nothing is specified: "discard"

appserver (optional) Configuration of DynaMent processing on the Web server or application server.

"yes": Even DynaMents that access external URLs will be executed in the usual order on the application server, as far as this is possible.

"no": DynaMents that access external URLs will be executed subsequently on the Web server. This means that it is practically impossible to react to errors or content resulting from executing these DynaMents. Notes: You use this option with the method="MULTIPART" parameter if the application and Web server components are not running on the same Java Virtual Machine. Otherwise, you should only use this setting in those rare cases where you have an existing project in which you want to wait until a process completes before running a DynaMent.

Value if nothing is specified: The value entered in the system configuration for the reddot.idea.appserver.callurls key (default value is "yes").

timeout (optional) Used only for external content: Interval in seconds after which the connection to an external server is terminated. If the server does not deliver the called content within this period, an error message is displayed.

If nothing is specified: The global setting from the system configuration is used (key: reddot.xmaps.content.request.timeout). If no timeout value is defined in the system configuration either, the connection to an external server is terminated globally after a maximum of ten minutes.

track-mode (optional) Used only in combination with a reporting connector, for which you need the appropriate license. This parameter is interpreted only if the content with the Include DynaMent is located in a project that has at least one Reporting connector assigned. Determines whether information about the added content is recorded, and what information. You can enter several parameters separated by semicolons ";". The following values are possible:

"none": No information about the added content is recorded. Note: If this value forms part of a value list, the other values are ignored.

"name": For internal content, the name of the added content item is recorded for external content, the complete URL.

"structure": Only for internal content: the name, content group, and project of the added content item are recorded.

167


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"attributes": Only for internal content: Content attributes are recorded according to the settings in the Reporting connector (requires the Tracking and Reporting Connector – Personalization license). The preset content attribute rdeReporting.contentCategory is recorded even if you only have a Tracking and Reporting Connector - Standard license.

"{track-mode}": Explicit specification of a value you wish to use for the evaluation. For example, this allows you to assign a content category to all content that is integrated via an Include DynaMent, irrespective of the content item you are actually integrating (like "news" or "teaser"). You can specify only one value.

Value if nothing is specified: "none"

Note: Recording data using the track-mode parameter increases the runtime. We therefore recommend you only record information you wish to use.

encoding-flags (optional) Defines encoding rules for different MIME types, particularly for HTML and XML content (also see the information below). You can enter several parameters separated by semicolons ";". The following values are possible:

"subtype_declaration_use": Evaluates the MIME subtype to determine the encoding (if it has not been determined yet). If possible, the encoding information is determined from the content itself.

"subtype_declaration_force": Evaluates the MIME subtype to determine the encoding, even if it has been determined already. If possible, the encoding information is determined from the content itself and overwrites the previously determined encoding.

"subtype_declaration_none": Does not evaluate the MIME subtype to determine the encoding.

"UTF-8_guess": Only for XML content: If no encoding has been determined yet, UTF-8 is used when UTF-8 byte sequences are detected in the data stream. Note: This option requires additional parsing of the data stream and generates an additional load on the system. Therefore, you should only use it if it is absolutely necessary.

"XML_default_UTF-8": Only for XML content: In accordance with W3C XML specifications, the default value, UTF-8, is used if no other encoding can be determined.

"force_encoding_type_xml": Content type XML is used to determine the encoding.

"force_encoding_type_html": Content type HTML is used to determine the encoding.

Value if nothing is specified: "subtype_declaration_none; XML-default_UTF-8"

include-mode (optional) Selects which information about the content is added to the DynaMent result. The following values are possible:

"content-info": Some basic information about the content in each XML element, such as, name, locale, type, released, guid, group, description, and last-updated.

"content-reference": Minimal information for rendering a reference to the applicable content in each of its XML elements: name, type, MIME type.

"content-identifier": Name of the content in the XML element name.

168


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"context-tags": The tags selected in the context-tags parameter from the content itself.

"content": Only for content types XML, HTML, and XSL: The actual content data for the respective language.

You can specify one or more values separated by semicolons as the include-mode parameter. For each include-mode, a tag name can be defined for the result element that takes this information. The tag name is added to the include-mode separated by a comma. Note that the tag value is not evaluated for include-mode="content", however; the tag name of the result element is controlled with the tag parameter in this case. The following is an example of the correct syntax: "content-info,info;content"

Every requested information item increases the runtime if the result is not already available in the cache. Therefore, we recommend using the include-mode parameter for information that needs to be evaluated or presented to the user. Value if nothing is specified for content type XML, HTML, XSL: "content" Value if nothing is specified for content type BLOB, SCRIPT: "content-info,notag"

context-tags (optional) Determines which tags should be added to the result of the Target DynaMent and how. A single tag name, or multiple tag names separated by semicolons, which are transferred from each content item found to the resulting XML of the DynaMent. Notes: To be able to use context tags, you have to select at least the context-tags mode in the include-mode parameter (default setting). A separate context-mode can be specified for each individual tag name, if a value other than that of the global context-mode parameter is required. If you specify "none", then an individual context mode must be specified for each tag so that the tag will appear in the result. Supported syntax: "tagname1,context-mode1;tagname2;tagname3,context-mode3" Only the content of the first content tag is returned with the specified name. If the tag includes child elements, they will be returned as well. You can use this function, for example, to add content information or information on displaying individual content items to the resulting XML and present it to the user. Value if nothing is specified: "title,[specification from context-mode]" Value if no value is specified for the context mode parameter: "title,mixed"

context-mode (optional) The way in which the content of the context-tags parameter is integrated in the result XML of the DynaMent. You can specify the context-mode parameter either globally or separately for each individual tag name of context-tags.

"mixed": Any angle brackets of tags contained in the content are replaced with their XML entities (<, >).

"cdata": The content is encapsulated in CDATA sections. This mode ensures that the resulting XML is well-formed even if the contents are not.

"none": The context-tags will not be included in the result.

"xml": The text from the content item is added to the resulting XML without any replacement or verification. XML conformity cannot be guaranteed. Rather, the XML result will only be delivered if the transmitted section is XML-compliant. Note: Using the "xml" mode is not recommended for new projects. It is mainly intended to ensure downward compatibility with existing projects.

Value if nothing is specified: "mixed"

169


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

attributepath (optional) List of one or more content attribute path names, starting at which all content attributes for each content item are delivered in an XML structure in the results. The path components of a path name are separated by periods. More than one path names in the list are separated by semicolons (;). ".": All the content attributes belonging to the content item are returned in the result.

metainfo (optional) Used only for external binary content: Determines which of the header fields are included in the DynaMent result as metadata. Header fields are not case sensitive.

"rdeallmetainfo": Returns the values of all header fields of a content item

"{header field}": Returns the values for the specified header fields. You can specify one or more header fields separated by semicolons.

To be able to include metadata, you need to specify the mode "metainfo" in the include-mode parameter. If nothing is specified: No metadata is returned.

project (optional) Used only for external binary content. Only used when entering the cache-id parameter: Project name to which the read content in the object cache is assigned. If nothing is specified: The active project is used.

cache-id (optional) Used only for external binary content: Creates a cache entry (scope="request") in the object cache. Specify a content name. This will be the last element of the content key used to store the read content (as RedDot LiveServer content) in the object cache. The content item contains the content data in the default language of the project to which the content is assigned. The cache-id is used as name for the content in RedDot LiveServer. The data specified in content-info is created as attributes, and child elements are created from the specified rdeContentInclude.contentInfo attribute. The data specified in metainfo is saved as a string in the rdeContentInclude.rdeMetainfo attribute. The root attribute name rdeContentInclude can be overwritten using the contentinclude-attribute parameter.

If nothing is specified: No cache entries are created.

size-max (optional) Used only for external binary content. Only used when entering the cache-id parameter: Maximum file size in KB. If the value is zero or no value is specified: there is no maximum file size.

size-swap (optional) Used only for external binary content: File size in KB. Any data exceeding this size is swapped out by the cache entry. If the value is zero or no value is specified: No data is swapped out.

contentinclude-attribute (optional) Used only for external binary content: Name of the content attribute that accepts attributes rdeContentinfo and rdeMetainfo as child elements (see cache-id). Value if nothing is specified: "rdeContentInclude"

170


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. The previous root element is replaced by the tag name.


"notag": The result is shown without the enclosing XML element. This means the root element of the content to be integrated is omitted. This tag is useful because a content item can only have one document root element, whereas sometimes you may need several root elements. Example: Combination of a number of associated templates to form a content module.

If nothing is specified: "{Root-Element}"; in case of external, binary content: rde-rd:contentinclude-result

cachingtime (optional) Interval in minutes that represents the longest time that content remains in the component cache. With the specific value "-1", the cachingtime parameter is not interpreted. Only for external content: Value if nothing is specified: "0"

Parameters for PSX Modules

PSX modules represent an independent combination of XML content and an XSL style sheet and can be rendered separately. PSX modules are embedded into a content item as a reference and are created and added separately with their own caching behavior when the content is requested.

stylesheet (PSX module) Only for use with internal content as a PSX module. Specification of an XSL style sheet as part of the placeholder that is replaced with the rendered results from stylesheet/content. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (e.g.: modules/news/news.xml). In contrast to including a simple Include DynaMent, in which specifying the content parameter is sufficient, the inclusion of a PSX module specifies an XSL style sheet in the stylesheet parameter. This style sheet contains all the XSL templates required to render the content in the target format. A separate caching time is specified for this module in the cachingtime parameter.

class (PSX module) (optional) Only for use with internal content as a PSX module: For further definition of the placeholder.

content-fixed (PSX module) (optional) Only for use with internal content as a PSX module: For handling XML content during rendering. The following values are possible:

"no": Default setting. The XML content is calculated anew during each query and prepared for rendering.

"yes": The XML content is loaded to the rendering engine integrated with the XSL. The name of the XML content is added to the entry of this content-fixed rendering engine in the rendering engine pool. The content is appended to the engine's dependency list. As a result, the XML content does not have to be calculated anew during each query and prepared for rendering. The dependency of XSL parameters must be generated explicitly in the content that is bound to the XSL engine, for example, by using an Attribute

171


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

DynaMent in "read" mode to read an attribute. You should not transfer this dependency to the content-fixed XSL engine, however, as this creates unnecessary variants. Therefore, if you use this setting, you also have to use the runtime="content" parameter in the Attribute DynaMent. When you use this parameter, the dependency is recorded in the dependency list, but not transferred to the content-fixed XSL engine.

content-qualifier (PSX module) (optional) Only for use with internal content as a PSX module: This is an additional user-defined parameter to improve the performance of the component cache. It is used to separate different variants of a cache entry into different entries. Inline notation is supported. The inline expression becomes part of the PSX placeholder. Interpretation does not start before processing and replacing the placeholder (see example below). Note: When calling a page from the component cache, RedDot LiveServer first executes all the writing attribute accesses that occurred during the initial processing. Then the placeholders are replaced. This means that several placeholders with the same inline expression in the content-qualifier parameter lead to the same replacement even when the parameters of the inline expression were changed in the meantime. Therefore, in inline notations in content-qualifier, you should only use parameters that were given and are not changed (Request parameters) or use parameters that are set up once and then not changed.

Child Elements

There are two optional child elements for external content: Child element <rde-rd:import> can be used to assign metadata to content. Child element <rde-rd:http-header> can be used to assign header fields to the request of the Include DynaMent.

<rde-rd:import> (optional) Used only for external content: This child element contains the metadata that will be added to the content (also see example below). The content of this element will be processed before it is inserted. The syntax is the same as for the Import DynaMent. See the description there.

<rde-rd:http-headers> (optional) Used only for external content: Contains one header field for each individual child element which is added to the request of the Include DynaMent.

<rde-rd:http-header> Contains the information for a single header field.

name Name of the header field that is added to the request of the Include DynaMent. If nothing is specified, the corresponding child element is not evaluated.

{value} Value of the header field that is added to the request of the Include DynaMent.

Result

The Include DynaMent is replaced in RedDot LiveServer at runtime by the inserted content that it references.

172


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The information, warning, and error messages for the Include DynaMent begin with 7 in the thousands' place. You can send the return codes with the standard parameter result-attribute. In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:



-7501 The content item was not found.

-7502 The content could not be included (incorrect content type, for example).

-7503 The URL to be included was not specified.

-7504 The content type is not XSL. XSL content items may only contain content of type XSL.

-7511 The script contains an error or could not be found.

-7512 The OnError script was not found or encountered an error.

-7901 A timeout occurred while retrieving external content.

7201 The maximum processing depth was reached

7202 The document is no longer valid (according to the validfrom and validto parameters).

7203 Successful, but no content.

7204 Content constraint was not met, content not included.

7205 The content item was not found in the repository.

7206 Cannot process requested content.

7601 The PreRequest script was not found or encountered an error.

173


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

MIME Types and Content Types

The range of available and registered MIME types and subtypes is extremely broad. RedDot LiveServer uses the following rules to assign content type HTML or XML:

Content type XML:

text/xml

/rss

MIME type contains +xml

Content type HTML:

text/html

MIME contains xhtml, but no +xml

Example: Inserting Internal Content

<rde-dm:include content="demo:footnote-2"/>

In the result, the Include DynaMent is replaced by the content item footnote-2 from the demo project. If this content item is not available, then the Include DynaMent is unsuccessful and nothing is inserted.

Example: Inserting Content via a URL

<rde-dm:include content="http://localhost:8080/cps/rde/xchg/html-demo/

337.xml" contenttype="text/xml; charset=ISO-8859-1"/>

In the result, the Include DynaMent is replaced by the content item 337.xml from the html-demo project. If this content item is not available, then the Include DynaMent is unsuccessful and nothing is inserted.

174


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Examples: Effect of parameters mode="text" and tag="notag" based on example HTML content

Original HTML content content.html: <b>Hi<rde-dm:attribute mode="read" attribute="name" />!</b><br>This is

a test.

a) Include DynaMent with parameter mode="text": <rde-dm:include content="content.html" mode="text" /> Example result: <rde-html>

<![CDATA[Hi Peter!</b><br>This is a test.]]>

</rde-html>

b) Include DynaMent with parameter mode="text" and tag="notag": <rde-dm:include content="content.html" mode="text" tag="notag" /> Example result:

<![CDATA[Hi Peter!</b><br>This is a test.]]>

c) Include DynaMent in standard mode (without parameters): <rde-dm:include content="content.html" /> Example result: <rde-html>

<rde-html-section> <![CDATA[Hi Peter!</b><br>This is a test.]]>

</rde-html-section>

</rde-html>

Example: PSX Module

In contrast to a simple Include DynaMent, in which specifying the content parameter is sufficient, an Include of a PSX module specifies an XSL style sheet in the stylesheet parameter. This style sheet contains all the XSL templates required to render the content in the target format. A separate caching time is specified for this module in the cachingtime parameter.

<rde-dm:include content="trails:news-list.xml" stylesheet="hs-newslist.xsl"

cachingtime="60"/>

175


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: PSX Module with content-qualifier Parameter

Include DynaMent with PSX module:

<rde-dm:include content="abc.xml" stylesheet="def.xsl" content-

qualifier="[#request:pageId#]"/>

Resulting placeholder in the xchg/<project>/def.xsl/abc.xml/?locale=de content in the component cache:

#RDE-PSX:<project>/def.xsl/abc.xml//$$parameter:??content-

qualifier=[#request:pageId#]/#/?locale=de

When the content from the cache is called, the placeholder is replaced and the inline notation which is contained in the placeholder is executed. This results in a separate cache entry for the placeholder like this (example when calling xchg/<project>/def.xsl/abc.xml?pageId=100):

#RDE-PSX:<project>/def.xsl/abc.xml//$$parameter:??content-qualifier=100/#/?locale=de

Example: Using the <rde-rd:import> Child Element

<node> <rde-dm:include cache-id="image1" cachingtime="60" content="http://localhost:8080/cps/rde/xbcr/demo/101b.jpg" contenttype="image/jpeg"> <rde-rd:import>

<keywords> attribute1: value1, attribute1: value 2, attribute 2: value 3,

attribute3.subattribute3: value 4, </keywords>

<constraints> <constraint attribute="profile.level"

description="profile.level greater than 2" mode="condition" op="gt" value="2" />

<constraint attribute="profile.track.filename.html" description="increase by one for profile.track.filename.html" mode="write" op="increase" value="1" />

</constraints> <properties>

<rde-rd:group>group1</rde-rd:group> </properties>

</rde-rd:import> </rde-dm:include>

</node>

In the example, the <keywords> element is used to assign attributes to the content item, while <constraints> is used to assign constraints. The <properties> element assigns the content item to a content group.

176


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

For more information about the Script DynaMent, Message DynaMent, and Reference DynaMent, see the separate sections.

See also:

Calling Scripts (Page 402)Sending E-Mail (Page 235)Processing Multipart Requests ('read-multipart') (Page 310)

Including Weblet Module Placeholders

Purpose

Using the Include DynaMent, you can insert Weblet module placeholders in your content. Weblet module placeholders provide a direct means of calling the handleRequest(...) method of a Weblet, and also makes it possible to insert content in a page. Pages in the cache can undergo high-performance enhancement with external application data using Weblet modules.

A Weblet module placeholder is evaluated as any other placeholder if a page has already been processed and rendered by the Exchange Weblet, or read from the component cache. In other words, immediately prior to delivery. If you enter the alias name of a Weblet in the weblet="{weblet-alias}" parameter, a Weblet module placeholder will be inserted as DynaMent result instead of content. You can enter other Name=value pairs in the content="{query-string}" parameter. The first character of the content parameter must not be a question mark. The Name=value pairs must be separated by question marks.

The Weblet itself is a Java class that extends the de.reddot.api.web.weblet.WebletAdapter class of Open API, and must be entered in the system configuration.

The Include DynaMent inserts Weblet Module placeholders as follows: The placeholder is written to the resulting XML, similar to a PSX module. The default tag is rde-web.

<rde-web> #RDE-WEB:{weblet-alias}/$$parameter:??{query-string}/#

</rde-web>

Syntax

<rde-dm:include content="{parameter1=value1?

parameter2=value2...}" weblet="{weblet alias}"

/>




177


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:include weblet="mediator" content="baseURL=www.reddot.com/" tag="notag"

/>

Weblet module placeholder in result XML: #RDE-WEB:mediator/$$parameter:??baseURL=www.reddot.com//#

Parameters

content (optional) Request parameters can be specified. They should be separated from each other by question marks. The first character may not be a question mark. If nothing is specified: No parameters.

weblet Alias name of a Weblet. You can use this parameter to insert a special Weblet module placeholder as the Weblet result in the result XML. A special Weblet has been created by RedDot for this purpose with the name "mediator", with which external content can be included. You can also use your own Weblets and include their results. If a Weblet specified here does not exist, an error message appears.

tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. The previous root element is replaced by the tag name.


"notag": The result is shown without the enclosing XML element. This means the root element of the content to be integrated is omitted. This tag is useful because a content item can only have one DocumentRoot element, whereas you sometimes need to include several roots. Example: Combination of a number of associated templates to form a content module.

If nothing is specified: "rde-web"

cachingtime (optional) Interval in minutes that represents the longest time that content remains in the component cache. With the specific value "-1" the cachingtime parameter is not interpreted. Value if nothing is specified: "0"

Result

The Include DynaMent is replaced in RedDot LiveServer at runtime by the Weblet module placeholder that it referenced.

A Weblet module placeholder is evaluated as any other placeholder if a page has already been processed and rendered by the Exchange Weblet, or read from the component cache. In other words, immediately prior to delivery. The Weblet's handleRequest() method is itself called automatically by RedDot LiveServer via the WebletAdapter.callWeblet(...) method. See the Open API documentation for details.

178


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

The placeholder is then replaced by the string set in the Weblet via method WebletResponse.setWebModuleResultString(java.lang.String result).

Error Handling

The information, warning, and error messages for the Include DynaMent begin with 7 in the thousands' place. You can send the return codes with the default parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the "RedDot DynaMents" chapter.


Predefined Placeholders (Page 561)Syntax of Preassigned Placeholders (Page 564)

Calling Your Own Weblets via the Parameter "weblet":

When writing your own Weblets, which are called using the "weblet" parameter, you need to be aware of the following information:

The Weblet being used cannot write itself in the HttpServletResponse (e.g., via WebletResponse.printString() ).

The string that is to be inserted must be specified via the WebletResponse.setWebModuleResultString().

The string replaces the placeholder, i.e., "RDE-WEB:{weblet-alias}$$parameter:??{query-string}/# ". No other replacement or rendering takes place.

The Weblet called as Weblet module is responsible for error handling.

179


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Including Content Versions ('include-version')

Purpose

You can use the Include DynaMent in "include-version" mode to access a specific version of a content item in the LiveServer Repository and include this version.

Content versions with constraints are not integrated unless the constraints are met for the user of the requesting session.

Syntax

<rde-dm:include mode ="include-version" content ="{projectname:contentname}"

project ="{projectname}" locale ="{locale string}"

locale-policy ="[none|default|any]" version ="[final|draft|{version}]"

include-mode ="[{include-mode},{tagname};]" context-tags ="[{tagname},{context-mode};]" context-mode ="[mixed|cdata|xml|none]" attributepath ="{content attribute list}"

/>




Simple Call

<rde-dm:include mode="include-version" content="text.html" version="draft" />

Parameters

mode Mode of the Include DynaMent, here "include-version".

content Name of the content being inserted from the LiveServer Repository. The syntax is "projectname:contentname". If the project is not specified, the project specified in the project parameter is used. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

project (optional) Name of the project containing the content. Only evaluated if the content parameter does not contain a project name. If nothing is specified: The active project is used.

180


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

locale (optional) Language of content inserted. The locale parameter affects both the respective content attribute and the display of content data of the selected content. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. You can enter several locales separated by semicolons ";". The system thus searches for the languages in the order specified and uses the first language found. If there is no content data in the RedDot LiveServer Repository for any of the languages specified, a fallback language is determined in accordance with the Locale Policy. This is usually the default project language.

Value if nothing is specified: User language of the requesting session.

locale-policy (optional) Locale policy to access content data and attributes: If a content item has no value for the language variant determined by the locale parameter, the value for a different variant is read. Possible settings:





version (optional) Version of the content item to include. The following values are possible:




Value if nothing is specified: For delivery: "final"; for preview (RedDot LiveServer/RedDot CMS): "draft".




181


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



"content": Only for content types XML, HTML, and XSL: The actual content data for the respective language.

You can specify one or more values separated by semicolons as the include-mode parameter. For each include-mode, a tag name can be defined for the result element that takes this information. The tag name is added to the include-mode separated by a comma. Note that the tag value is not evaluated for include-mode="content", however; the tag name of the result element is controlled with the tag parameter in this case. The following is an example of the correct syntax: "content-info,info;content"

Every requested information item increases the runtime if the result is not already available in the cache. Therefore, we recommend using the include-mode parameter for information that needs to be evaluated or presented to the user. Value if nothing is specified for content type XML, HTML, XSL: "content" Value if nothing is specified for content type BLOB, SCRIPT: "content-info,notag"

context-tags (optional) Determines which tags should be added to the result of the Target DynaMent and how. A single tag name, or multiple tag names separated by semicolons, which are transferred from each content item found to the resulting XML of the DynaMent. Notes: To be able to use context tags, you have to select at least the context-tags mode in the include-mode parameter (default setting). A separate context-mode can be specified for each individual tag name, if a value other than that of the global context-mode parameter is required. If you specify "none", then an individual context mode must be specified for each tag so that the tag will appear in the result. Supported syntax: "tagname1,context-mode1;tagname2;tagname3,context-mode3" Only the content of the first content tag is returned with the specified name. If the tag includes child elements, they will be returned as well. You can use this function, for example, to add content information or information on displaying individual content items to the resulting XML and present it to the user. Value if nothing is specified: "title,[specification from context-mode]" Value if no value is specified for the context mode parameter: "title,mixed"






182


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



Result

The Include DynaMent is replaced on the RedDot LiveServer at runtime by the included content version that it references. If the specified version does not exist or the content constraints are not met, nothing is included and an error message appears.

Error Handling

The information, warning, and error messages for the Include DynaMent begin with 7 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:



-7321 The specified version was not found.

183


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Including Difference Between Content Items ('diff')

Purpose

You can use the Include DynaMent in "diff" mode to display the differences between two specified content items or content versions from the LiveServer Repository.

Content items with constraints are not integrated until the constraints are met for the user of the requesting session. The constraints of the current content item are evaluated.

Syntax

<rde-dm:include mode ="diff"

pretty-print ="[no|yes]" content1 ="{projectname:contentname}"

project1 ="{projectname}"

locale1 ="{locale string}" version1 ="[final|draft|{version}]"

content2 ="{projectname:contentname}"

project2 ="{projectname}" locale2 ="{locale string}"

version2 ="[final|draft|{version}]"

/>




Simple Call

<rde-dm:include mode="diff" content1="text.html" locale1="de"

version1="final" content2="text.html" locale2="de" version2="draft"/>

Parameters

mode Mode of the Include DynaMent, here "diff".

pretty-print (optional) For XML and XSL content only: Determines the formatting of the content before it is compared. The following values are possible:

"no": The content is not formatted (default setting).

"yes": The content is formatted with automatic indents and breaks. Different line breaks between elements do not create as many unnecessary differences. The text is not changed during formatting.

184


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


content1 Name of a content item from the LiveServer Repository that you want to compare with another content item. The syntax is "projectname:contentname". If the project is not specified, the project specified in the project parameter is used. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

project1 (optional) Name of the project containing the content. Only evaluated if the content parameter does not contain a project name. If no value is specified: The active project is used.

locale1 Language of the project data used for the comparison. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. You can enter several locales separated by semicolons ";". The system thus searches for the languages in the order specified and uses the first language found.

version1 Version of the content item to be used. The following values are possible:




content2 See content1.

project2 (optional) See project1.

locale2 See locale1.

version2 See version1.

185


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

An XML structure is returned that represents the differences between the specified content items, along with additional information, in each line. The basic framework of the XML structure looks like this:

<diff> <version1>

<project>demo</project> <name>index.htm</name> <version>1</version> <locale>en</locale> <changedby>admin</changedby> <changedat>YYYYMMDD hh:mm:ss</changedat>

</version1> <version2>

<project>demo</project> <name>index.htm</name> <version>1</version> <locale>en</locale> <changedby>admin</changedby> <changedat>YYYYMMDD hh:mm:ss</changedat>

</version2> <items>

<lines> <line><![CDATA[ ... ]]></line> <line type="changed">

<version1><![CDATA[ ... ]]></version1> <version2><![CDATA[ ... ]]></version2>

</line> <line type="deleted"><![CDATA[ ... ]]></line> <line type="added"><![CDATA[ ... ]]></line>

<line><![CDATA[ ... ]]></line> </lines>

</items>

</diff>

186


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error handling

The information, warning, and error messages for the Include DynaMent begin with 7 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:



-7520 The specified version of the content item, project1:content1:version1, was not found.

-7521 The specified version of the content item, project2:content2:version2, was not found.

-7523 The version information is missing in parameter version1.

-7524 The version information is missing in parameter version2.

-7525 The locale information is missing in parameter locale1.

-7526 The locale information is missing in parameter locale2.

187

DynaMent ReferencesIolet DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Iolet DynaMent

The Iolet DynaMent is only available with the appropriate license, which enables the Open API and the Iolet DynaMent.

It is used to insert dynamic components into RedDot LiveServer content, using business logic implemented in Java. The Iolet DynaMent is used to call Iolets. At runtime, it is replaced by the result of the called Iolet. As a result, you can use the Iolet DynaMent to call your own, customer-specific modules, with which you can integrate your own applications. For more detailed information on this subject, refer to the Open API documentation for RedDot LiveServer. The following sections describe the basic operating mode of the Iolet DynaMent.


Call an Iolet

Use child elements to transfer additional parameters to the Iolet

Calling Iolets

Purpose

The Iolet DynaMent is used to insert dynamic components into RedDot LiveServer content. It calls Iolets and thus permits the integration of customer-specific modules and applications. Please read the Open API documentation for information on how to program Iolets using Java.

The Iolet DynaMent can pass additional parameters and their values to the Iolet by inserting them as child elements in the DynaMent. You can thus include additional DynaMents in an Iolet DynaMent. These DynaMents are processed before the Iolet call, and the returned result may in turn affect the Iolet parameters. You can use the Iolet DynaMent with or without child elements.

In addition to string values, you can also use the <rde-rd:parameters> child element to pass XML nodes on to the Iolet. This allows you, for example, to pass the results of already processed DynaMents on as parameters.

188


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:iolet name ="{iolet alias}"

method ="{method name}" action ="{action}" subject ="{subject}" response-prefix="{prefix}"

value ="{value}" > <parameter name-1>{value 1}</parameter name-1> <parameter name-1>{value 2}</parameter name-1>

... <parameter name-n>{value n}</parameter name-n>

... <rde-rd:parameters>

<rde-rd:parameter name ="{parameter name}"

type ="[string|xml]" reference="[current|{rde-id}]" >

{value} </rde-rd:parameter>

</rde-rd:parameters>

</rde-dm:iolet>


tag ="[notag|{tagname}]" cachingtime ="{cachingtime in minutes}" roles ="{userrole1;userrole2}" result-attribute ="{attributename}" report-tag ="{tagname}" rde-id ="{rde-id}" process-mode ="[standard|standard-recursive|


Simple Call

<rde-dm:iolet name="userinfoiolet" method="GetUserInfo">

</rde-dm:iolet>

The GetUserInfo method of the userinfoiolet Iolet is called.

Parameters

name Name of the Iolet alias. Iolet names are not case sensitive.

method (optional) Name of a service method of the Iolet (without the do prefix). If the method parameter is specified, the alternative parameters action and subject are ignored. The do prefix in the code indicates the Iolet methods that can be called with an Iolet request.

action Deprecated, please do not use. Action to be executed by the Iolet When used together with the subject parameter, it indicates the first part of the method name to call. It is only evaluated if the method parameter is not specified.

189


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

subject Deprecated; please do not use. Indicates the object of the action (method name). When used together with the action parameter, it indicates the second part of the method name to call. It is only evaluated if the method parameter is not specified.

response-prefix (optional) Provides access to the response parameters in an Iolet DynaMent. If response-prefix is specified, all of the Iolet Response parameters set by the setParameter method will be written to source="request". The parameter names will be prefixed by the values specified in response-prefix. If the value of a parameter is not a string, the return value will use the toString() method. Existing values with the same name will be replaced. Afterwards, the parameter values can be accessed by using the Attribute DynaMent with source="request" in "read" mode, for example.

value (optional) Parameter passed to the Iolet. Only a single fixed parameter can be passed here (for example, no dynamic page IDs). Use child elements if you want to pass multiple parameters (see below).

cachingtime (optional) Interval in minutes that represents the longest time that content remains in the component cache. With the specific value "-1", the cachingtime parameter is not interpreted. Value if nothing is specified: "0"


"{tagname}": Explicit specification of tag name. If the result is an XML tree, the previous root element is replaced by the tag name.

"notag": The result is shown without the enclosing XML element. If the result is an XML tree, the root element for the content to be included is therefore omitted. This is useful to get valid XML code, if the content is inserted in an XML content item that already has a root element.

Value if nothing is specified:

If the result is a string: "notag":

If the result is an XML tree: "{Root-Element}"

Child Elements

The Iolet DynaMent has additional, optional child elements for passing parameters to the Iolet. DynaMents within child elements are processed; inline notation is supported. The child elements can be used as alternatives or concurrently; in the latter case, the child element, <rde-rd:parameters>, is evaluated last.

<parameter name> (optional) Any number of additional parameters, whose names and string values are passed to the Iolet when the Iolet DynaMent is called. One parameter name may take several values. When it is called, all parameters that are at that time in source="request" are automatically passed to the Iolet. The parameter values are overwritten by the parameters specified in the Iolet DynaMent. The Iolet requests multivalued attributes using the IoletRequest.getParameter( String name ) method, which returns a string array.

190


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

All child elements of each parameter are processed and the text values of all child elements are passed to the Iolet. You can select the parameter names as required. Make sure that you do not use any predefined parameter or variable names, as these may be overwritten.

<rde-rd:parameters> (optional) Child element that can be used to pass string values of parameters, as well as XML nodes, on to the Iolet. You can specify multiple <rde-dm:parameter> elements.

<rde-rd:parameter> Child element indicating a parameter.

name Name of the parameter.

type (optional) Type of the parameter. The following values are possible:

"string": All text elements from {value} are used and passed on as string values. Inline notation is supported.

"xml": An object is passed on as an XML node (org.w3d.dom.Node).

Value if nothing is specified: "string"

reference (optional; only for use with type="xml") Reference to an object to be passed on:

"current": The XML tree that is currently being processed. A document is transferred (org.w3c.dom.Document).

"{rde-id}": Value of the standard parameter rde-id of the previously processed DynaMent whose result was already processed and is to be transferred as a parameter. A node list is transferred (org.w3c.dom.Nodelist).

If nothing is specified: The range within the <rde-rd:parameters> element is passed on.

Result

The output from the Iolet and its formatting are defined in the code of the Iolet itself and are not evident from the call. An XML tree or a string is returned as the result.

191


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The Iolet DynaMent's information, warning, and error messages begin with 10 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following return codes are possible:

Example: Multiple Child Elements

<rde-dm:iolet name="userinfodemoiolet" method="GetUserInfo"

value="1234">

<myparam1>value 1</myparam1>

<myparam2>value 2</myparam2>

...

</rde-dm:iolet>

Result:...

Example: Integrated Attribute DynaMent:

<rde-dm:iolet name="test" method="starttest"> <parameter1>abc</parameter1> <rde-dm:attribute mode="read" attribute="country" tag="parameter2"/>

</rde-dm:iolet>

Result:...


-10501 The Iolet generated an error message.

-10511 Return value of the Iolet is not XML.

-10599 The necessary license is missing.

10101 Attribute name missing.

10102 Attribute reference: Unknown rde-id

10103 Attribute type: Unknown type (allowed types: blank, "string", "xml")

10104 Parameters cannot be overwritten.

192


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Parameter response-prefix

<rde-dm:iolet name="{ioletname}" method="{method}" response-prefix="irp"/> <rde-dm:attribute mode="read" attribute="irpkey1" source="request"/> <rde-dm:attribute mode="read" attribute="irpkey2"

source="request"/>

All of the Iolet Response parameters set by the setParameter method will be written to source="request". The parameter names will be prefixed by the values specified in response-prefix. The Attribute DynaMent is used in "read" mode to read the parameter values.

Example: Child Element <rde-rd:parameters>

<rde-dm:attribute mode='read' source='session' attribute='attr' op='xml' rde-id='ptest' process-mode='execute'/> <rde-dm:attribute mode='read' source='session' attribute='attr'

op='xml' rde-id='ptest'/>

<rde-dm:iolet name='echoiolet' method='RequestParameter' report-tag='report'>

<rde-rd:parameters> <rde-rd:parameter name='empty'> </rde-rd:parameter> <rde-rd:parameter name='ws'>  </rde-rd:parameter> <rde-rd:parameter name='text'> text </rde-rd:parameter> <rde-rd:parameter name='nodetext' >

<node>Node</node> </rde-rd:parameter> <rde-rd:parameter name='node' type='xml'>

<node>Node</node> </rde-rd:parameter> <rde-rd:parameter name='reference' type='xml' reference='ptest'> </rde-rd:parameter> <rde-rd:parameter name='current' type='xml' reference='current'>

</rde-rd:parameter> </rde-rd:parameters>

</rde-dm:iolet>

In the above example, two Attribute DynaMents are run with the same value for rde-id. After processing, the result of the Attribute DynaMent with process-mode="execute" can only be accessed with parameter rde-id.

When passing parameters, note that the text of parameters name="empty" and name="ws" can be blank. Texts that consist only of spaces can be passed on as blank texts.

193


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Leading and trailing spaces can be retained (name="text" parameter) if type="string". Parameter name="nodetext" is a blank string (the text contained in element <rde-rd:parameter> is a blank string). If parameter name="node", a node list from an element is passed on. If formatted XML is used (line breaks, indents), the spaces can also be included in the node list. If parameter name="reference", a node list from two identical elements is passed on. If parameter name="current", the document is passed on.

The uncertainties associated with spaces are due to different DOM implementations. Parsers can omit spaces (between two elements), but do not always do so.

Various values can be accessed on the Iolet side:

Document document=(Document)req.getParameter("current"); // Document

NodeList nodeList=(NodeList)req.getParameter("node"); // NodeList -> List of nodes NodeList nodeList=(NodeList)req.getParameter("reference"); // NodeList

-> List of nodes

194

DynaMent ReferencesLink DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Link DynaMent

The Link DynaMent is used to generate a link (with or without parameters). It is replaced at runtime by an XSL style sheet specification for the creation of a link to a content item. The Link DynaMent is used in XSL style sheets, in combination with a Reference or Wrapper DynaMent, and is inserted in the corresponding XML document.


Generate simple links without parameters

Generate links with additional parameters and combine the Link DynaMent with other DynaMents

Generating Simple Links

Purpose

You can use the Link DynaMent without parameters to generate a link. In this case, a number of variables are used in XSL.

Syntax

<rde-dm:link tag ="{tagname}"

/>




Parameter

tag (optional) This is the tag name of the resulting XML element that displays the results of the DynaMent. If no value is specified: no tag is used.

195


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Notes

Result

The path call of the XSL-formatted XML file is composed from the variables in HTML:

If content items and content groups are not unique project-wide:

<a href="Prefix/Weblet_Alias/Session_ID/Project_name/XSL_style_sheet/-/

XML_content">

If content items and content groups are unique project-wide:

<a href="Prefix/Weblet_Alias/Session_ID/Project_Name/XSL_style_sheet/

XML_content">

Error Handling

The information, warning, and error messages for the Link DynaMent begin with 12 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, see the "Error Handling" section in the chapter "About RedDot DynaMents".

Only one link is generated for each Link DynaMent. Therefore, if you need multiple links, insert the required number of Link DynaMents.

Variable Meaning

$rdePrefix Path of the Web server

$rdeWeblet Name of the called Weblet

$rdeSessionID ID of the active session

@rde-rd:project Name of the active project

$rdeXslID ID of the current style sheet

@rde-rd:xslXmlSeparator

Separator between style sheet and content

@rde-rd:content Name of the current content

196


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-dm:link />

Result in the style sheet:

<xsl:element name="a"> <xsl:attribute name="href"> / <xsl:value-of select="$rdePrefix"/> / <xsl:value-of select="$rdeWeblet"/> / <xsl:value-of select="$rdeSessionID"/> / <xsl:value-of select="@rde-rd:project"/> / <xsl:value-of select="$rdeXslID"/> <xsl:value-of select="@rde-rd:xslXmlSeparator"/> / <xsl:value-of select="@rde-rd:content"/> </xsl:attribute>

</xsl:element>

Result in the HTML page, for example:

<a href="/cps/rde/imenue/SID-3F57FBCE-D08FE2E2/doc/rootstyle/index>

197


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Generating Links with Parameters

Purpose

You can use a Link DynaMent with parameters and combine it with other DynaMents to publish a link.

Syntax

<rde-dm:link project ="{projectname}" tag ="{"tagname}" prefix ="{prefix} method ="{method name}" xsl ="{xsl contentname}" xml ="{xml contentname}"

wrapper ="{wrapper}"

/>




Parameters

project Name of the project to which the content belongs.

tag (optional) This is the tag name of the resulting XML element that displays the results of the DynaMent. If no value is specified: no tag is used.

prefix (optional) Allows an absolute link to be specified instead of the usual relative link. This absolute link can be specified either as a fixed string or with a reference to a key in the system configuration. In the latter case, the key used is preceded by a $. You can use prefix, for example, to explicitly request an https protocol.

method (optional) Valid file format (example: "html", "wml"). If no value is specified: "html"

xsl Name of the style sheet (example: "hs").

xml Name of the content.

198


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

wrapper (optional) References the content in which the Wrapper DynaMent is called (example: newswrapper.xml).

Error Handling

The information, warning, and error messages for the Link DynaMent begin with 12 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:

Only one link is generated for each Link DynaMent. Therefore, if you need multiple links, insert the required number of Link DynaMents.

<rde-dm:link method="html" project="doc" xsl="nav_left"

xml="navigation" />

Result in the XSL style sheet:

<xsl:element name="a"> <xsl:attribute name="href"> / <xsl:value-of select="$rdePrefix"/> / <xsl:value-of select="$rdeWeblet"/> / <xsl:value-of select="$rdeSessionID"/> / <xsl:value-of select="doc"/> / <xsl:value-of select="nav_left"/> / <xsl:value-of select="navigation"/> </xsl:attribute>

</xsl:element>

Result in the HTML page:

<a href="cps/rde/imenue/SID-3F57FBCE-C8C2BC1/doc/nav_left/navigation>



199


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Link DynaMent with wrapper call:

<rde-dm:link method="html" wrapper="magazinewrapper"> <br/>

</rde-dm:link>

Link DynaMent in combination with Reference DynaMent:

XML for the navigation list

<rde-dm:container type="reference" id="navigation" tag="navigation"> <rde-dm:reference project="demo" content="news" tag="item" text="News"/> <rde-dm:reference project="demo" content="development" tag="item" text="Development"/> <rde-dm:reference project="demo" content="documentation" tag="item" text="Documentation"/> <rde-dm:reference project="demo" content="support" tag="item" text="Support"/>

</rde-dm:container>

XSL for the navigation list

<xsl:template match="navigation"> <xsl:for-each select="navigation/item"> <TR> <TD class="navigation"> <rde-dm:link method="html"> <xsl:value-of select="."/> </rde-dm:link> </TD> </TR> </xsl:for-each>

</xsl:template>

Result in the content's XML:

<navigation rde-rd:container="navigation" rde-rd:project="demo" rde-rd:content="container" rde-rd:reddot="yes"> <item>News</item>

<item>Development</item>

Result in the HTML page:

<a href="cps/rde/xwm/SID-3F57FBCE-CB6C8584/demo/rootstyle/news>News</a> <a href="cps/rde/xwm/SID-3F57FBCE-CB6C8584/demo/rootstyle/

development>Development</a>

200


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Using the prefix attribute:

prefix as fixed string:

<rde-dm:link method="html" prefix="https://111.111.111.1"> Link 1

</rde-dm:link>

prefix as call of an entry:

<rde-dm:link method="html" prefix="$reddot.idea.test.prefix"> Link 2

</rde-dm:link>

201

DynaMent ReferencesLink-Param DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Link-Param DynaMent

The Link-Param DynaMent is used to pass parameters with a link call. The Link-Param-DynaMent can only be used together with a Link-DynaMent.


Use the Link-Param DynaMent to pass additional parameters for a link.

Passing Other Link Parameters

Purpose

The Link-Param DynaMent is used to set additional parameters of a link. These parameters can be passed to the following destinations:

XSL style sheets, for example, as return address parameters

Iolet-DynaMents, for example for business logic

The Link-Param DynaMent can only be used together with a Link DynaMent and extends its functionality. One typical use of the Link-Param DynaMent is to provide a "Back" button.

Syntax

<rde-dm:link-param name ="{name}" value ="{value}"

/>

The standard parameters cannot be used.

Parameters

name Name of an extended link.

value Parameter that can also be addressed dynamically (example: "{$ioeXmlID}" for the page ID of the page from which the Link DynaMent is called).

202


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"Back" button:

<rde-dm:link method="html"> <br/> <rde-dm:link-param name="Back" value="{$rdeXmlID}"/>Back

</rde-dm:link>

A link is built into HTML page A to HTML page B is via the XSL document. A link to the page ID that constitutes the source of the link is built into HTML page B. The text of the link is "Back".

Result in the generated source code:

Next (with news wrapper):

<a href="/rde/xchg/SID-3F57FB42-4C115587/tesths/hs/news_2/

newswrapper?back=news"> Next...

Back:

<a href="/rde/xchg/SID-3F57FB42-4C115587/tesths/hs/news"> Back ...

Link with different destinations:

<rde-dm:link method="html" xml="text12"> <br/> <rde-dm:link-param name="output" value="blue"/>Here blue on white... <rde-dm:link-param name="output" value="green"/>Here green on white..

<rde-dm:link-param name="output" value="red"/>Here red on white..

</rde-dm:link>

A link is built into HTML page A via the XSL document. The formatting of the content on the following page is generated differently depending on the parameter. To achieve this, for example, an XSL if request may be built into the XSL of the following page and used to control the appearance. In this case, for instance, the text color is varied under certain conditions.

203


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Multiple link with different destinations:

<rde-dm:link method="html" xml="text12"> <br/> <rde-dm:link-param name="output" value="blue"/>Here blue on white...

</rde-dm:link>

<rde-dm:link method="html" xml="text12"> <br/> <rde-dm:link-param name="output" value="green"/>Here green on white..

</rde-dm:link>

Two links to different HTML pages B and C are built into HTML page A via the XSL document. The result is that the content of "text12.xml" is displayed differently depending on the "value" of the Link-Param DynaMent. In this case, the text color is varied.

For more information on the Link DynaMent, see the following sections:

Generating Simple Links (Page 195)Generating Links with Parameters (Page 198)

204

DynaMent ReferencesLivelink DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Livelink DynaMent

The Livelink DynaMent lets you access specific objects in Open Text Livelink Enterprise Server through a repository connector.

Repository DynaMent, Livelink DynaMent, or Open API? You use the Repository DynaMent to work with documents and folders. Aside from accessing documents and folders, you can also use the Repository DynaMent to access other types of objects in Open Text Livelink. As with other objects, the Repository DynaMent also gives access to general information, such as properties, categories, and children.

The Livelink DynaMent also provides functions for special types of objects in the Livelink system, particularly for the following object types in the current version:

Discussion Livelink discussions contain topics and replies to these topics that users start in Livelink and can use to collaborate. Discussions can be assigned to other Livelink objects, in line with the overall Livelink concept.

Topic Livelink discussions can be divided into topics. In turn, users can enter replies to these topics.

Reply A Livelink reply is always assigned to a Livelink topic, and represents a user's contribution to a discussion. A reply typically consists of text. It may also contain attachments.

You can use the Open API to implement access to other object types such as poll or workflow, as well as other requirements that exceed the possibilities of the DynaMents. Functions for accessing other object types with the Livelink DynaMent, such as poll and workflow, are currently under development.

Web Components: Livelink DM and Livelink Discussion RedDot Solutions offers preconfigured Web Components that use the Repository and Livelink DynaMents. You can integrate these components directly in your own projects. As a result, you can integrate the sophisticated document management and collaboration functions available on an existing Livelink Enterprise Server.

Note: Object IDs of Livelink objects When you use the Repository and Livelink DynaMents, you often need the object ID of a Livelink object as an input parameter - for example, to read the object. The IDs are displayed in the user interface of Open Text Livelink, for instance, in the context menu with the Properties/General function, in the Nickname field. Alternatively, you can use the automatically generated ID or a custom name.


Read specific objects from Open Text Livelink (mode="read")

Create specific objects in Open Text Livelink (mode="create")

Delete specific objects in Open Text Livelink (mode="delete")

Determine navigation information for specific objects in Open Text Livelink (mode="navigate")

Use predefined searches (mode="xmlsearch")

205


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

More information about connectors for repositories and accessing Livelink objects with the Open API is available in the Connectors documentation.

For information about the Repository DynaMent, see the separate section.

See also:

Repository DynaMent (Page 341)

206


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Objects from Open Text Livelink ('read')

Purpose

The Livelink DynaMent in "read" mode lets you read specific objects from Open Text Livelink. You have the following options:

Read type-specific information for objects with type discussion, topic, and reply.

Optional filters to restrict display, for example, to unread objects or date ranges.

Provide navigation information to other objects, such as the next reply for the same topic.

Note: You can also use the Repository DynaMent to access objects in Open Text Livelink; the Livelink DynaMent contains additional functions for specific types of objects.

Syntax

<rde-dm:livelink mode ="read" connector ="{connector name}" item ="{object id}" item-type ="{object type}" include-mode ="[{include-mode},{tagname};]" metainfo ="[rdeallmetainfo|{property}]" child-depth ="{depth level}"

maxhits ="{number}" context-mode ="[mixed|cdata|controlled]"

dateformat-in ="{dateformat}"

dateformat-out ="{dateformat}" item-tag ="[item|{tagname}]"

encoding ="{encoding}" >

<rde-rd:param> <periodFrom>[{period name}|{date}]</periodFrom> <filter>[all|topics-only|unread-only]</filter> <mark-as-read>[no|yes]</mark-as-read>

</rde-rd:param>

</rde-dm:livelink>




207


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:livelink mode ="read" connector ="Livelink" item ="[#request:item#]" include-mode ="[#request:include-mode#]" child-depth ="[#request:child-depth#0#]"

/>

The above call reads a discussion object using the repository connector. The object ID must be specified in the item request attribute. The result is an XML object that contains various information about the object and the hierarchy of the assigned topics and their replies, depending on which of the include-mode and child-depth request attributes are selected.

Parameters

mode Mode of the Livelink DynaMent, here "read".

connector Name of the repository connector to be used, as defined in RedDot LiveServer. The connector has to use a bridge for Open Text Livelink.

item Unique string to identify an item in the repository; in this case, the object ID from Open Text Livelink. Livelink nicknames are supported.

item-type (optional) Plain text name of the expected Livelink object type of the object to read, whose object ID is specified in the item parameter. The system checks whether the object to read matches the specified type. If not, an error code is generated and the object is not read. The following values are possible:

"discussion": Livelink discussion

"topic": Livelink topic from a discussion

"reply": Livelink reply to a topic

If nothing is specified: Empty string. The object type is not checked.

include-mode (optional) Selects which information about the objects that have been found is added to the DynaMent result. The following values are possible:

"content-info": Some basic information about the object in each XML element; this includes

project: The calling project

content-id: The object ID of the read object

parent-id: The object ID of the parent object of the read object

object-type: Internal Livelink number of the type of read object

object-class: Fully qualified path name of the class of the read object

locale: Short name to indicate the (possibly requested) content language of the read object

208


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

type: Type name of the object, as can also be used as a value for the item-type parameter.

description: Content of a property of the read object

last-updated: Time stamp of the last change to the read object

"metainfo": The metadata selected in the metainfo parameter, which is maintained as properties in the repository.

"child-hierarchy": Adds information about the child objects of the read object to the hierarchy modeled in Livelink in the XML result. Example: Topics and replies as child objects of a discussion. The Livelink hierarchy is modeled as a hierarchy of child elements in the XML result (also see the Results section below). Direct child objects are grouped by object type; the names of the object types are used as tag names of the child elements in the result. The individual Livelink objects in the hierarchy are displayed with the information that is usually required for such hierarchies. In particular, the object ID, which you can use to retrieve additional information about an object, is included in the result. You can specify the maximum number of hierarchy levels to add in the child-depths parameter. To minimize load and maximize performance, you should limit the hierarchy levels and objects to what you really need in the project.

"child-list": Adds information about the child objects of the read object to the hierarchy modeled in Livelink in the XML result. Like child-hierarchy, but the child objects are displayed in a list - that is, at the same element level in the XML object.

"attachments": Adds information about attachments that are assigned to the objects in Livelink to the XML result. These objects are displayed in the XML result. Replies can have attachments, for example.

"navigation": Adds information about objects that are linked with the viewed object in Livelink to the XML result. For example, object IDs are determined for the following objects (if any) for topics and replies: firstTopic, previousTopic, currentTopic, lastTopic, previousUnread, previous, next, nextUnread. These object IDs make it possible to display navigation links to the corresponding objects.

"userinfo": Records the name and ID of the current Livelink session user in the result XML.

You can specify one or more values separated by semicolons as the include-mode parameter. For each include-mode, a tag name can be defined for the result element that takes this information. The tag name is added to the include-mode separated by a comma. The following is an example of the correct syntax: "content-info,info;content,result"

Every include-mode selected increases the runtime if the result is not already available in the cache. Therefore, we recommend using the include-mode parameter for information that needs to be evaluated or presented to the user. Value if nothing is specified: Empty string.

metainfo (optional) Determines which of the properties administered in the repository are included in the DynaMent result as metadata. The type of metadata available depends on the configuration of the repository being used. You can combine the following options separated by a semicolon:

"rdeallmetainfo": Returns all content properties accessible for which the specific name is not required.

209


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

".*": Returns all standard properties.

"{category}.*": Returns all properties for the specified category.

"{property}": Returns the values for the standard properties specified. You can specify one or several property names separated by semicolons.

"{category}.{property}": Returns the values for the specified properties connected to categories. You can specify one or several property names separated by semicolons.

To be able to return metadata, you need to specify the mode "metainfo" in the include-mode parameter. If nothing is specified: No metadata is returned.

child-depth (optional) Maximum depth for object hierarchy information added to the DynaMent result, for example, using include-mode="child-hierarchy". No further levels are used to determine the DynaMent result (to evaluate filter criteria, for example). Value if nothing is specified: "10"

maxhits (optional) Maximum number of object hierarchy information added to the DynaMent result, for example, using include-mode="child-hierarchy". No further objects are used to determine the DynaMent result (to evaluate filter criteria, for example). Value if nothing is specified: "50"

context-mode (optional) Method used to add content items to the elements of the XML result.



"controlled": The content items are added directly to the XML result if they are well-formed. If they are not well-formed, they are enclosed in CDATA sections.


dateformat-in (optional) Determines the date format to use for dates delivered to the external repository. The syntax is based on that used for standard Java class java.text.SimpleDateFormat (example: yyyy-MM-dd'T'HH:mm).

dateformat-out (optional) Defines the date format to use for formatting dates in the DynaMent result. The syntax is based on that used for standard Java class java.text.SimpleDateFormat (example: yyyy-MM-dd'T'HH:mm).

item-tag (optional) This is the tag name of the XML element that displays the result of read object.



Value if nothing is specified: "rde-rd:result-item".

210


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

encoding (optional) Specifies the encoding to be used when content from the repository is converted to strings. You can use all encodings supported by JVM, for example, UTF-8. Value if nothing is specified: "ISO-8859-1"

Child Elements

"read" mode has a child element called <rde-rd:param>.

<rde-rd:param> (optional) You can use the <rde-rd:param> child element to specify additional parameters. The values of these parameters are specified within further child elements. Whenever possible, the names of these parameters are based on the corresponding names in the Livelink interface. Several of these parameters are only used to read certain types of Livelink objects.

The default values used if no information is provided are always listed as the first item in the lists of possible values.

Possible parameters:

<periodFrom>{value}<periodFrom> Filter criterion for adding dependent objects to the XML result (for example, in include-mode="child-hierarchy") according to their creation time. The following values are possible:

no-time-limit: No restrictions caused by this filter criterion.

yesterday: To be added, objects must have been created on the query date or one day earlier.

a-week-ago: To be added, objects must have been created within a week of the query date.

two-weeks-ago: To be added, objects must have been created within two weeks of the query date.

three-weeks-ago: To be added, objects must have been created within three weeks of the query date.

a-month-ago: To be added, objects must have been created within a month of the query date.

three-months-ago: To be added, objects must have been created within three months of the query date.

six-months-ago: To be added, objects must have been created within six months of the query date.

a-year-ago: To be added, objects must have been created within a year of the query date.

Date value (following the pattern in the dateformat-in parameter): Objects must have been created on the specified date/time or later.

<filter>{value}</filter> Filter criterion for adding dependent objects to the XML result (for example, in include-mode="child-hierarchy"). The following values are possible:

all: No restrictions caused by this filter criterion.

211


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

topics-only: Only dependent objects with type topic are added.

unread-only: Only objects that have not yet been read by the user configured in the connector are added.

<mark-as-read> Determines whether the object read with the Livelink DynaMent is marked as read in Livelink. The following values are possible:

no: The object is not marked as read

yes: The object is marked as read.

Result

Information for the object is read from the specified repository and displayed in the XML result, dependent on the parameters. If the include-mode parameter is not specified, the result XML has the following structure:

<ll-read> <rde-rd:repository-result> <rde-rd:result-item> <Discussion hide="false"> <subject>myDiscussion</subject> <property name="llid" type="com.opentext.acs.livelink.lang.LivelinkId"> <value> <subproperty name="nodeId">2596215</subproperty> .... </value> </property> <property name="parentllid" type="com.opentext.acs.livelink.lang.LivelinkId"> <value> <subproperty name="nodeId">1864949</subproperty> .... </value> </property> <property name="creator" type="com.opentext.acs.livelink.admin.LivelinkUserImpl"> ... </property> <property name="created" type="java.util.Date"> ... </property> </Discussion> </rde-rd:result-item> </rde-rd:repository-result>

</ll-read>

As you can see, the read object is placed in an element whose tag name indicates the object type (in this case: Discussion). Specific properties of the object are placed in separate elements (such as subject). Further properties are placed in generic property name="..." elements, which can have generic child structures themselves. For example, you can read the object ID of the parent Livelink object in the following path: Discussion/property[name="parentllid"]/value/subproperty[name="nodeId"]. If you also specify "content-info" in the include-mode parameter, some of this information is returned in simplified form directly beneath the top result element, rde-rd:repository-result.

212


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

You control the addition of information concerning dependent elements, such as topics and replies, with the include-mode, child-depth, and maxhits parameters. Direct child objects are grouped by object type; the names of the object types - with an appended plural "s" - are used as tag names of the child elements in the result. The individual Livelink objects in the hierarchy are displayed with the information that is usually required for such hierarchies. In particular, the object ID, which you can use to retrieve additional information about an object, is included in the result. You can define the maximum number of hierarchy levels to add in the child-depths parameter, and limit the total number of analyzed objects with the maxhits parameter.

Example: Excerpt from result for topics in a discussion:

<Topics> <Topic hide="false"> <subject>First Posted Topic</subject> <comment>The first topic</comment> <order>1</order> <unread>false</unread> <property name="llid" type="com.opentext.acs.livelink.lang.LivelinkId"> ... </property> </Topic>

</Topics>

Additional values for the include-mode parameter, such as "navigation", add qualified links to other objects to the result. These links are placed as elements with tag name property, and the name attribute designates the type of link. Example of a link to the first topic (firstTopic) of a discussion:

<property name="firstTopic" type="com.opentext.acs.livelink.lang.LivelinkId"> <value> <subproperty name="nodeId">2399699</subproperty> <subproperty name="version">0</subproperty> ... </value>

</property>

Error Handling

The Livelink DynaMent's information, warning, and error messages begin with 31 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), other messages are possible. For more information, see the description of the Repository DynaMent for "read" and "list" modes, which are also applicable to the Livelink DynaMent.


-31100 Incorrect argument for a parameter

-31101 The active user does not have the rights to perform this action on the content item selected


-31501 Unknown error when using the bridge

-31510 Unable to load bridge support

213


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

-31511 Unable to find connector specified

-31512 Unable to access bridge

-31513 Unable to obtain list of available repositories

-31514 Unable to access repository

-31515 Unable to examine repository

-31516 Bridge support cannot be loaded due to missing license

-31521 The user cannot log on

-31522 The user cannot log off

-31523 No cleanup possible after the access


-31561 General error while accessing the repository item

-31580 Error while compiling a display element

-31581 Error while compiling a display element (content-info)

-31582 Error while compiling a display element (reference)

-31583 Error while compiling a display element (metainfo)

-31584 Error while compiling a display element (content)

-31585 Error while compiling a display element (identifier)

-31586 Error while creating the object to be cached

-31591 Error handling collaboration actions

31103 Incorrect argument for a parameter

31104 Unable to determine size of (native) content

31119 Problem determining the links



214


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Creating Objects in Open Text Livelink ('create')

Purpose

The Livelink DynaMent in "create" mode lets you create objects in Open Text Livelink. The object type of the Livelink object to create must be specified in the item-type parameter. The following object types are available:

Discussion

Topic

Reply

Note: You can also use the Repository DynaMent to create objects in Open Text Livelink; the Livelink DynaMent contains additional functions for specific types of objects.

Syntax

<rde-dm:livelink mode ="create" connector ="{connector name}" folder ="{object id}" item-name ="{object name}" item-type ="{object type name}" contentclass-name ="{contentclass name}" dateformat-in ="{dateformat}" ref-type ="[embedded|file|named]" ref ="{reference}" abort-events ="[error|warn|none|{warning-codes}| {error-codes}]" > <rde-rd:param> <comment>{comment}</comment> <attachments> <attachment llid ="{object id}" ref-type ="[embedded|file|named]" ref ="{reference}" content-name ="{content name}" encoding ="{encoding}" > <text>{text}</text> </attachment> </attachments> </rde-rd:param> <rde-rd:import> <keywords keyword-separator ="," name-value-separator =":" value-delimiters ="{delimiter}" resolve-entities ="[no|yes]" > attribute1:value1, attribute2:value2,value3, ... </keywords> </rde-rd:import>

</rde-dm:livelink>

215


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Simple Call

<rde-dm:livelink mode ="create" connector ="Livelink" folder ="2399922" item-name ="Sample Reply to Topic 2299922" item-type ="reply"

> <rde-rd:param>

<comment>Hi, this is the content of my sample reply</comment> </rde-rd:param>

</rde-dm:livelink>

This call adds a reply to the topic with object ID 2399922.

Parameters

mode Mode of the Livelink DynaMent, here "create".


folder Unique string to identify an item in the repository - in this case the object ID of the object that will be child of the object to create. Livelink nicknames are supported. Objects with certain types can only be assigned to folders with the appropriate object type in Open Text Livelink. The folder of a topic must be a discussion, for example, and the folder of a reply must be a topic or a reply.

item-name String used to identify the object in the display of the created object. This can be the name of a discussion, for example, or the subject of a topic or a reply.

item-type Plain text name of the Livelink object type of the object to create. If the object type does not match, an error code is generated and the object is not read. The following values are possible:


"topic": Livelink topic

"reply": Livelink reply

216


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

contentclass-name (optional) Object IDs of one or more Livelink categories to assign to the object to be created. You can enter multiple categories separated by commas or semicolons. Depending on the object type, you may have to specify a content class when you create objects. You can use child element rde-rd:import/keywords to set values for the attributes of these categories. It is especially useful to assign suitable categories for discussions.

dateformat-in (optional) Determines the date format to use for dates delivered to the external repository. The syntax is based on that used for standard Java class java.text.SimpleDateFormat (example: yyyy-MM-dd'T'HH:mm).

ref-type (optional) Determines which content data is transferred.

"embedded": The content data specified in the value of the child element rde-rd:param/comment will be passed on. The child element is processed prior to transfer. This means that you can transfer content from attribute values or include DynaMents in the content.

"file": The content of the file located in the absolute path specified in the ref parameter is transferred. If a relative path is specified, this is interpreted relative to RedDot LiveServer's Web application path (.../cps/WEB-INF/).

"named": Content data of the content specified in the ref parameter is transferred. However, only content data for the language of the current session is transferred. The content must be stored in the object cache under the name specified in ref for the current project. If the content cannot be found in the object cache, an error message is returned. Nothing is transferred in this case.



ref-type="file": URI for transfer. Specifies either an absolute path and file name on RedDot LiveServer where the file for transfer is located or a relative path starting with the Web application path .../cps/WEB-INF/. If the specified file does not exist, nothing is transferred. If no value is specified, ref-type="embedded" is used instead of "file".

ref-type="named": Name of the content item whose data is to be transferred. However, only content data for the language of the current session is transferred. The content must be stored in the object cache under the name specified for the current project. If the content cannot be found in the object cache, an error message is returned. Nothing is transferred in this case.

encoding (optional) Only for reftype="embedded" and "named". Encoding used to interpret the transferred content data.

Value if nothing is specified: "ISO-8859-1"

abort-events (optional) Defines the constraints for aborting this operation. You can specify a list of multiple alternative values separated by commas (example: "error,27107"). The following values are possible:

"error": The operation is aborted if any errors occur.

217


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"warn": The operation is aborted if any warning is issued.

"none": The operation is not aborted even if there are errors or warnings.

"{code}": Explicitly stated return codes for errors and warnings.

Value if nothing is specified: "error"

Child Elements

There are two child elements, <rde-rd:import> and <rde-rd:content> in "create" mode, each of which can be used once in a Livelink DynaMent. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:param> (optional) This child element contains the content data and attachments to be transferred. If the child element does not exist, only the metadata from the <rde-rd:import> child element is transferred.

<comment> (optional) Only for ref-type="embedded". Text content of the object to create, for example, the text of a reply.

<attachments> (optional) In one or more additional <attachment> child elements, you can specify the attachments that you want to add to the object to create. A separate child element is specified for each attachment; each element can have the following attributes:

llid (optional): Object ID of a Livelink object to add as an attachment. When it is used as an attachment, the object is copied and is therefore assigned a different object ID.

ref-type (optional): Determines which content data the attachment will contain. Options: see above. If embedded is specified, the content data is specified in the <text> child element.

ref (for ref-type="file" and "named"): Options: see above.

encoding (optional): Meaning: see above.

content-name (optional): String used to identify the object in the display of the created object.

<text> Only evaluated if ref-type="embedded": Text content of the attachment

<rde-rd:import> (optional) This child element contains the metadata to be passed, in this case: attributes and their values for categories. The categories themselves must already exist in Open Text Livelink and be assigned to the object to create using the contentclass-name parameter. Only metadata for which write access is enabled can be passed on.

<keywords> (optional) Specification of attributes and values for the object to create. You can only specify one <keywords> element. The attribute names are specified in the following format: {category_name}.{attribute_name} In this case, the category name is not the object ID, but rather the plain text name of the category in Open Text Livelink. You need to specify separators between each attribute and its value (name-value-

218


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

separator parameter). When specifying multiple attributes, you need to specify separators between the attribute-value pairs (keyword-separator parameter; example of default setting for separators: attribute1: value1, attribute2: value2). To create attributes without values, you can leave out the values. You do have to include the separators (example: attribute1:, attribute2:).

keyword-separator (optional) Separator between several attribute/value pairs (for example, profile.level:3, category1.name:5). Make sure you only use this character as a separator and not in attribute names or values. You can only specify one character. Value if nothing is specified: "," (comma). Note: An attribute can take several different values. Multivalue attributes are also implemented in the form of multiple attribute-value pairs (for example, profile level:1, profile level:5) and not by character-delimited values.

name-value-separator (optional) Separator between attribute and assigned value (for example, profile.level:3). You can only specify one character. Value if nothing is specified: ":" (colon).

value-delimiters (optional) Text block separators for enclosing attribute values. These make it possible for you to use a variety of characters in values, for example, even those defined as separators. The specification of one or more text block separators for attribute values. Enter the characters one right after the other (without spaces or separators). Each character you enter is interpreted as a text block separator. If the first character of an attribute value is one of the characters specified as a text block separator, it will be treated as the opening separator for this value and thus must also close the value. If nothing is specified: No text block separator is used. Note: If you want to use double quotation marks (") and backslashes (\) as text delimiters, you have to model them as an escape sequence — that is, with a leading backslash (example: value-delimiters="\"").

resolve-entities (optional) Specifies whether entities in attribute names or values are converted to their corresponding Unicode characters (for example: ä -> displays as ä).

"yes": All entities are resolved according to the included DTD definition file (at <RedDot Web application path>/WEB-INF/var/xml/doctype.txt). This setting is helpful, for example, if an external system delivers HTML code with entities that are to be used as attribute values in Unicode in RedDot LiveServer.



219


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

The transferred content is created with the specified metadata in the specified repository. The object ID of the new object is returned in child element <performed>. This object ID consists of multiple properties that are separated by number signs (#):

Version

Node ID; the actual object ID

System ID

These properties are added to separate child elements in the result:

<rde-rd:repository-result error="0"> <performed> <![CDATA[0#3409951#0#]]> </performed> <property name="llid" type="com.opentext.acs.livelink.lang.LivelinkId"> <value> <subproperty name="nodeId">2596215</subproperty> .... </value> </property>

</rde-rd:repository-result>

If any errors occur, the return code is recorded as the error attribute of the rde-rd:repository-result element. Errors in other child elements in the results are flagged at the detailed level.

Error Handling

The Livelink DynaMent's information, warning, and error messages begin with 31 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible. For more information, see the description of possible messages for the Repository DynaMent in "create" mode, which are also applicable to the Livelink DynaMent.



-31101 The active user does not have the rights to perform this action on the content item selected.









220


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8






-31531 General error while creating content

-31532 "Native" content must be provided

-31533 General error while setting the properties of a repository item









-31587 Error using RawContent



31108 The property specified in the import tag cannot be set, as it has not been defined

31109 The property specified in the import tag cannot be set, as it is read only

31110 The property specified in the import tag can possibly not be set (unable to determine type)

31116 The property specified in the import tag cannot be set because restrictions defined for the property are not fulfilled

31117 The specified content class was not found or could not be linked with the content/folder

31118 Problems occurred while creating an attachment



221


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Deleting Objects from Open Text Livelink ('delete')

Purpose

The Livelink DynaMent in "delete" mode lets you delete objects in Open Text Livelink. The object to delete must have one of the following object types:

Discussion

Topic

Reply

Note: You can also use the Repository DynaMent to delete objects in Open Text Livelink; the Livelink DynaMent contains additional functions for specific types of objects, for example, concurrent deletion of dependent objects.

Syntax

<rde-dm:livelink mode ="delete" connector ="{connector name}" item ="{object id}" item-type ="{object type name}"

/>




Parameters

mode Mode of the Livelink DynaMent, here "delete".


222


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

item Unique string to identify an item in the repository - in this case the object ID of the object to delete. Livelink nicknames are supported.

item-type (optional) Plain text name of the Livelink object type of the object to delete, whose Livelink ID is specified in the item parameter. The system checks whether the object to delete matches the specified type. If not, an error code is generated and the object is not deleted. The following values are possible:


"topic": Livelink topic

"reply": Livelink reply

If nothing is specified: Empty string. The object type is not checked.

Result

Provided the user has the necessary rights, the content item is deleted from the external repository. Dependent objects, such as directly assigned attachments, are deleted automatically.

Error Handling

The Livelink DynaMent's information, warning, and error messages begin with 31 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible. For more information, see the description of possible messages for the Repository DynaMent in "delete" mode, which are also applicable to the Livelink DynaMent.














223


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Determining Navigation Information for Objects ('navigate')

Purpose

The Livelink DynaMent in "navigate" mode lets you determine navigation information for objects from Open Text Livelink.

Syntax

<rde-dm:livelink mode ="navigate" connector ="{connector name}" item ="{object id}" include-mode ="{include-modes}"

/>




Parameters

mode Mode of the Livelink DynaMent, here "navigate".


item Unique string to identify an item in the repository - in this case the object ID of the object to read. Livelink nicknames are supported.




-31551 General error while deleting a repository item







224


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

include-mode One or more functional names that designate links to specific related objects to add to the result. You can enter multiple, semicolon-delimited values. Possible values:

"next"

"previous"

"firstTopic"

"previousTopic"

"nextTopic"

"lastTopic"

"nextUnread"

"previousUnread"

Not all values are useful for all object types. All the values are useful for topics and replies, for example, to display links to the respective objects. However, you should only specify the values that you actually use because the determination of the result can be extremely time-intensive and load-intensive if a large number of Livelink objects has to be located and checked. When "nextUnread" and "previousUnread" are used, for example, replies to the next or previous topics are also checked if the current topic does not have any unread objects.

Result

Each value added to the include-mode parameter generates a <property> element in the result, whose name attribute contains the value of the respective include-mode. Example of "previousTopic":

<rde-rd:repository-result> <property name="previousTopic" type="com.opentext.acs.livelink.lang.LivelinkId"> <value> <subproperty name="rendition" /> <subproperty name="nodeId">2399699</subproperty> <subproperty name="systemName" /> <subproperty name="volId">2596215</subproperty> <subproperty name="version">0</subproperty> </value> </property>

</rde-rd:repository-result>

The values of the <property> elements consist of additional child elements. In particular, you can read the object ID of the object you want to link to. To do so, use the following path: property[name="{include-mode}"]/value/subproperty[name="nodeId"]

225


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The Livelink DynaMent's information, warning, and error messages begin with 31 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible. For more information, see the description of the Repository DynaMent for "read" and "list" modes, which are also applicable to the Livelink DynaMent.





























226


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Using Prepared Searches ('xmlsearch')

Purpose

You can use the Livelink DynaMent in "xmlsearch" mode to run a prepared search defined in the repository connector for the contents of a Livelink repository. You can use prepared searches for the Open Text Livelink v9.x bridge in Version 9.7 of the Livelink Enterprise Server and later versions.

Syntax

<rde-dm:livelink mode ="xmlsearch" connector ="{connector name}" search-template ="{search name}" display-template ="{template name}"

search-id ="{search id}" project ="{project name}" dateformat-out ="{date format}" context-mode ="[mixed|cdata|controlled]" include-mode ="[{include-mode},{tagname};]" metainfo ="[rdeallmetainfo|{property}]" xmlfields ="[rdeallmetainfo|{property}]" size-max ="{size in KB}" size-swap ="{size in KB}" cache-id ="{cache id}" chunk ="{chunk number}" chunksize ="{number of records}" sortedby ="{property name}" sortorder ="[asc|ascending| desc|descending]" abort-events ="[error|warn|none|{warning-codes}| {error-codes}]"

access ="[all|session]" >

<rde-rd:parameters> <rde-rd:parameter name="param1">{text}</rde-rd:parameter> <rde-rd:parameter name="param2">{text}</rde-rd:parameter> ...

</rde-rd:parameters>




Parameters

mode Mode of the Livelink DynaMent, here "xmlsearch".

connector Name of the repository connector to be used, as defined in RedDot LiveServer.

227


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

search-template Name of a prepared search defined in the repository connector, based on a template or a query.

display-template (optional) Only used for searches with type Search Template: ID of a template used to display the search result. If nothing is specified: The default display template defined in the repository connector.

search-id (optional) ID of a template to use for the prepared search. Enables flexible referencing of searches defined in Livelink without having to define them in the repository connector. If nothing is specified: Template ID defined in the repository connector.

project (optional) Only used when entering the cache-id parameter: Project name to which the read content in the object cache is assigned. If nothing is specified: The project containing the DynaMent is used.


context-mode (optional) Method used to add content items to the elements of the XML result.



"controlled": The content items are added directly to the XML result if they are well-formed. If they are not well-formed, they are enclosed in CDATA sections.


include-mode (optional) Selects which information about the content that has been found is added to the DynaMent result. When you specify this parameter, you make object properties available that cannot be accessed with a simple prepared search: Livelink lets you define templates and queries that are executed using RedDot LiveServer; you can enrich the result set with additional attributes. The search operation has relatively poor performance in this case, because the objects have to be loaded from Livelink to evaluate the attributes that are not in the search engine index.

The following values are possible:

"xmlfields": Adds the fields from the display template or search object (template, query) in the resulting XML.

"content-listdisplay": Some basic information about the content in each XML element, such as:

content-id: Unique string to identify an entry in the external repository.

name: Name of the content in RedDot LiveServer. This value is only present when parameter cache-id was set

228


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

rde-rd:mime: MIME type of the content item in the external repository

description: The name of the content in the external repository.

content-bytesize: File size of the content item.

object-type: Object type from the external repository

object-class: Object class from the external repository

last-updated: Date of last change to content item

type: Content type in RedDot LiveServer that is mapped to a MIME type from the repository. Note: The mapping between MIME content types in a repository and RedDot LiveServer content types is defined in the <RedDot Web application path>/WEB-INF/etc/mimetype.txt file. You can add MIME types and map content types.

"content-info": More detailed information about the content item in additional XML elements such as: project, nickname, parent-id, locale.

"content-reference": Minimal information for rendering a reference to the applicable content in each of its XML elements, such as: content-id, name, description, content-bytesize, type, rde-rd:mime.

"content-identifier": Only name and ID of the content in each XML element: content-id, name, description.

"content": Only for content of the types XML, HTML, XSL, or SCRIPT: The actual content data for the respective language. For BLOB type content, only a minimum of information is specified.




Note: Every include-mode selected increases the runtime if the result is not already available in the cache. Therefore, we recommend using the include-mode parameter for information that needs to be evaluated or presented to the user. Value if nothing is specified: "xmlfields,notag"





229


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



To be able to include metadata, you need to specify the mode "metainfo" in the include-mode parameter. If nothing is specified: No metadata is returned.

xmlfields (optional) Selects which fields from the display template or search object (template, query) will be added to the search result. The following options are available: Determines which of the properties administered in the repository are included in the DynaMent result as metadata. The type of metadata available depends on the configuration of the repository being used. You can combine the following options separated by a semicolon:


"{property}": Returns the values for the properties specified. You can specify one or more property names separated by semicolons.

If nothing is specified: All fields are included.

size-max (optional) Only used when entering the cache-id parameter or if include-mode="content": Maximum file size in KB. If negative values are specified for the parameters size-max and size-swap, this forces caching and/or display of the native content for all repository objects. If the value is zero or no value is specified: there is no maximum file size.

size-swap (optional) File size in KB. Any data exceeding this size is swapped out by the cache entry. If negative values are specified for the parameters size-max and size-swap, this forces caching and/or display of the native content for all repository objects. If the value is zero or no value is specified: No data is swapped out.

cache-id (optional) Creates a cache entry (scope="request") in the object cache. Note: No communication takes place with the external repository when content is delivered from the cache, which means no information is written to the audit trail in the external repository either. Specify a content name. This will be the last element of the content key used to store the read content (as RedDot LiveServer content) in the object cache. The content item contains the content data in the default language of the project to which the content is assigned. For RedDot LiveServer content, only the master data that is available through the properties of the external repository, and which can be assigned, is set. The cache-id is used as the name; the description is passed. All data specified in content-info is created as child attributes of the predefined rdeRepository.rdeContentInfo attribute, which has the name of the repository connector as a value. The information requested with the metainfo parameter are stored as a string in the predefined attribute rdeRepository.rdeMetainfo. When the property type of the bridge is transmitted, it is entered as a value of the predefined rdePropertyType child attribute. The root attribute name rdeRepository can be overwritten using the repository-attribute parameter.

230


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Special syntax with namespaces: Where the value of the cache-id parameter starts with the predefined namespace rdeproperty, which is separated by a colon, special rules apply for identifying the cache-id to be used:

rdeproperty Reads the value for cache-id from the property specified for the read content after the namespace. If the value of this property cannot be determined or is blank, no cache entries are created.


chunk (optional) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. The resulting XML element of the Livelink DynaMent contains the parameters previouschunk, nextchunk, lastchunk, hits, chunk, and chunksize, which can be implemented using XSL scrolling functions. If nothing is specified: Values from the display template or the search object (template, query).

chunksize (optional) Maximum number of content items that may be included in the result of the Livelink DynaMent as defined by the chunksize parameter. If the number of items found is greater than chunksize, then the remaining items are displayed in the next chunk after sorting. Possible values: "1" to "500" If nothing is specified: Values from the display template or the search object (template, query).

sortedby (optional) Name of a property in the repository that will be used to sort the content alphanumerically in the result. You can only sort by fields that are marked as searchable. The fields are sorted independently of their types. If nothing is specified: The sequence of contents in the result corresponds to the score calculated internally by the repository. Notes: The sorting is alphabetical even for numeric values, which means 200 comes before 30.


"asc" or "ascending": Ascending


If nothing is specified: Values from the display template or the search object (template, query).






231


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


access (optional) Controls access to the cached content. Possible values:

"all": The content is visible for all sessions.

"session": The content is only visible for the session that placed it in the cache.

Value if nothing is specified: "all"

Child Elements

The Livelink DynaMent has optional child elements for searches with type Search Template, which can be used to specify parameters for the search. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:parameters> (optional) Parameters and their values are specified within this child element. You can specify multiple <rde-dm:parameter> elements.

<rde-rd:parameter> (optional) Child element indicating a parameter.

name Name of the parameter.

Result

The result in XML for a Livelink DynaMent is a list of the content items found. The content list is enclosed by an element that is specified in the tag parameter. Each individual content item is enclosed by the tag specified in the item-tag parameter. The individual content items found are placed consecutively in item-tag elements (default: "rde-rd-result-item"). In addition to the name, the resulting XML also contains additional information regarding the content, such as project, language, content type, and serial number.

Error Handling

The Livelink DynaMent's information, warning, and error messages begin with 31 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:







232


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

For more information about prepared searches and how they are defined in the repository connector, see the Connectors documentation.



















-31591 Error handling collaboration actions






233


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Search of the "Search Template" Type

<rde-dm:livelink mode="xmlsearch" connector="localLivelink" search-template="myTemplateAlias" display-template="mydisplayTemplateID" include-mode="xmlfields,xmlfields;content-info, content-tag;metainfo,metainfo" metainfo="categorie2.unlock4,cdata;sSCORE; llid,mixed;name,mixed;rdeallmetainfo,cdata" xmlfields="SCORE;OTName;OTLocation;rdeallmetainfo" chunk="2" chunksize="30" sortedby="OTName"

sortorder="asc" >

<rde-rd:parameters> <rde-rd:parameter name="foo">bar </rde-rd:parameter> <rde-rd:parameter name="foo2">bar2 </rde-rd:parameter> </rde-rd:parameters>

</rde-dm:livelink>

Notes: The values specified in the child elements can be referenced in the templates using inline notation [#param:foo#] for searches with type Search Template. The child elements are not evaluated for type Livelink Search Reference.

234

DynaMent ReferencesMessage DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Message DynaMent

The Message DynaMent makes it possible to send messages.


Send e-mail messages via an SMTP server



Content DynaMent

CPS DynaMent

Message DynaMent

User DynaMent


For more information about connectors for message services, see the Connectors documentation.

Sending E-Mail

Purpose

The Message DynaMent is used to send messages. In "smtp" mode, you can send e-mail messages over an SMTP service connector based on the simple mail transfer protocol.

Each Message DynaMent has one or more child elements named <rde-rd:email>, each of which indicates an e-mail message. Each of these child elements has the following child elements: <rde-rd:from>, <rde-rd:reply-to>, <rde-rd:recipients>, <rde-rd:subject>, and <rde-rd:body>. Each of these child elements must occur exactly once; the child elements <rde-rd:from> and <rde-rd:reply-to> are optional.

To send content as an attachment, use the optional <rde-rd:attachment> child element as a supplementary element of <rde-rd:email>.

All element values have to be well-formed, which means you should enclose them in CDATA sections. If you use special characters, particularly in child element <rde-rd:body>, use of CDATA sections is mandatory. DynaMents must be located outside of these CDATA sections or they will not be executed during processing.

235


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:message mode ="smtp" name ="{connector name}" send-type ="[queue|direct]"

appserver ="[yes|no]" >

<rde-rd:email> <rde-rd:from>email-address</rde-rd:from>

<rde-rd:reply-to>email-address</rde-rd:reply-to> <rde-rd:recipients>

<rde-rd:recipient type="to|cc|bcc">email-address </rde-rd:recipient> ...

</rde-rd:recipients> <rde-rd:subject>subject-text</rde-rd:subject> <rde-rd:body type="text/plain|text/html">body-text </rde-rd:body>

<rde-rd:attachment

type ="[embedded|content|named]" mime-type ="{mime type}" content-id ="{content-id}" content ="{contentname}" project ="{projectname}" ' locale ="{locale string}" encoding ="{encoding}" ref ="{reference}" > Content if type="embedded"...

</rde-rd:attachment> <rde-rd:attachment

... </rde-rd:attachment>

</rde-rd:email> <rde-rd:email>

... </rde-rd:email>

</rde-dm:message>




The default parameter cachingtime cannot be used. This DynaMent sets the value of the caching time for the respective content to "0."

Parameters

mode Mode of the Message DynaMent, here "smtp".

name Name of a connector to an SMTP service defined in RedDot LiveServer.

236


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

send-type (optional) How the e-mail messages should be sent. The following options are available:

"queue": The messages are placed in a queue and sent periodically (once a minute).

"direct": The messages are sent immediately.

If nothing is specified: The corresponding setting in the SMTP service connector determines the send type. Default setting: "queue".



"no": DynaMents that access external URLs will be executed subsequently on the Web server. This means that it is practically impossible to react to errors or content resulting from executing these DynaMents. Note: Only set this option in an existing project in those rare situations in which you actually want to have a DynaMent executed at the end of a process.


Child Elements

The Message DynaMent has a child element. DynaMents within values of a child element are processed. Inline notation is supported (see information below for restrictions).

<rde-rd:email> Child element, each of which indicates an e-mail message.

<rde-rd:from> (optional) Sender's e-mail address. If no address is specified here, the default sender address from the SMTP service connector is used. If no sender address is specified there either, the e-mail message is not sent.

<rde-rd:reply-to> (optional) One or more valid e-mail addresses as recipients of answers to the e-mail sent. Separate multiple addresses with commas.

<rde-rd:email> List of recipients of an e-mail, in individual elements of <rde-rd:recipient>.

<rde-rd:recipient> One or more e-mail addresses for one or more recipients. Separate multiple addresses with commas.

type (optional) Recipient type: "to", "cc", or "bcc". Value if nothing is specified: "to"

<rde-rd:subject> Subject line of the e-mail.

<rde-rd:body> Body of the e-mail message.

237


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

type (optional) MIME type specification for the body. Note: You have to supplement the specified value with the charset value ; charset={encoding} if the character set used is not ASCII (example: text/plain; charset=UTF-8).

"text/plain": Default setting. The text is sent to the recipient as pure text.

"text/html": The text is interpreted as an HTML page. Select this type if HTML text is used in the message.

Value if nothing is specified: "text/plain"

<rde-rd:attachment> (optional) One or more child elements, each of which can be used to create an attachment and pass it to the call.

type (optional) Determines what content will be used as the attachment. The following options are available:

"embedded": The content will be specified directly in the DynaMent call.

"content": The content originates from the LiveServer Repository. To identify the content item precisely, the following parameters are used: "content," "project," and "locale".

"named": The content specified in the value of the ref parameter will be sent as an attachment. The content is a temporary file that was, for example, received via a Web service.


mime-type (optional) The specification of a MIME type that is used by the recipient to process the file that was received.


If type="embedded": "text/plain"

If type="content" or "named": There is an attempt to extract the MIME type from the content. For HTML content: "text/html"; for XML/XSL content: "text/xml"; for Script: "text/plain". If the content type cannot be determined: "application/octet-stream".

content-id (optional) Specification of an ID for identifying the attachment, if the attachment is to be sent as a reference. If nothing is specified: The ID automatically generated by AXIS.

content Only required for use with type="content": Name of the content item to be sent. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

238


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

project (optional) Only for type="content": Name of the project from which the content originated. If nothing is specified: The name of the project in which the DynaMent is located.

locale (optional) Only for type="content": Language to be used. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. If nothing is specified: Language of the requesting user.

encoding (optional) Only for text type (XML, XSL, HTML, SCRIPT): Denotes the encoding that will be used for the content (for example, ISO-8859-1). If nothing is specified: Operating system-specific default value.

ref Only required for use with type="named": Content name of the content item to be sent. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

Notes

All element values within the Message DynaMent have to be well-formed, which means you should embed them in CDATA sections. If you use special characters, particularly in the child element <rde-rd:body>, embedding the content in CDATA sections is mandatory. DynaMents must be located outside of these CDATA sections or they will not be executed during processing.

239


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The Message DynaMent's information, warning, and error messages begin with 19 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible:

DynaMents within the Message DynaMent

Within the Message DynaMent, DynaMents can in turn be embedded in the child elements (for example, Include or Attribute DynaMent). If these DynaMents do not appear outside of CDATA sections, they are not processed. The result of an embedded DynaMent must constitute a text that corresponds to a well-formed XML element value. This means, for example, that the characters "<", ">", and "&" must not occur.

For Include DynaMents, it should also be noted that within a Message DynaMent only Include DynaMents with the parameters mode="text" and tag="notag" produce a valid result. These parameters ensure that the Include DynaMent delivers a well-formed XML element value.

For more information about the Include DynaMent, see the separate section.

See also:

Integrating Internal or External Content (Page 160)


-19321 The message could not be generated (required data missing?)

-19322 The message transfer service could not be found or generated for the specified mode (internal error)

-19501 The specified message service connector could not be found

-19502 Not all of the parameters required for the call have been specified

-19901 The message transfer master could not be found (fatal internal error)

19323 This encoding is not supported

19324 Preparation of attachment failed

19325 Error reading content:'<contentId>' project:'<projectId>' locale:'<locale>'

240


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Format of E-mail Addresses in the Message DynaMent

You can enter the e-mail addresses for sender and recipient in the following formats: [email protected] or "Name"<[email protected]>

The second format must be enclosed in CDATA sections and then looks like this: <![CDATA["Name"<[email protected]>]]> (also see the example below).

Multiple addresses from an address list can be specified separated with commas.

The schematic example presented below illustrates possible uses of a Message DynaMent.

Here, an e-mail is sent to a recipient with the aid of the Message DynaMent directly following retrieval of the relevant content, and a copy is sent to another recipient. The various valid formats for e-mail addresses are used here in exactly the same way as the inline notation, through which in this case the e-mail address is read from the current request.

An Attribute DynaMent and an Include DynaMent are used within the child element <rde-rd:body>, as well as simple text. The Attribute DynaMent reads the attribute "address.name" of the current user and inserts it in the e-mail. The Include DynaMent is used to insert the content of a file (newsletter.htm).

All the element values within the Message DynaMent have to be well-formed. For this purpose, some element values are embedded in CDATA sections. DynaMents must be located outside of these CDATA sections or they will not be executed during processing.

241


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<document> <rde-dm:message name="smtp-connector" mode="smtp"

send-type="direct"> <rde-rd:email> <rde-rd:from> <![CDATA["Company"<[email protected]>]]> </rde-rd:from> <rde-rd:reply-to> [email protected] </rde-rd:reply-to> <rde-rd:recipients> <rde-rd:recipient type="to"> [#request:mail_to#0#] </rde-rd:recipient> <rde-rd:recipient type="cc"> [email protected] </rde-rd:recipient> </rde-rd:recipients> <rde-rd:subject>Information for you! </rde-rd:subject> <rde-rd:body type="text/html"> <![CDATA[ Hi ]]> <rde-dm:attribute source="user" attribute="address.name" mode="read" tag="notag" /> <![CDATA[ <p>Here is our monthly newsletter for you:</p> <hr> ]]> <rde-dm:include content="newsletter.htm" mode="text" tag="notag" />

</rde-rd:body>

</rde-rd:email>

</rde-dm:message>

</document>

Schematic result:

Subject = Information for you! Body = Hi, Marc <p>Here is our monthly newsletter for you:</p> <hr> [newsletter-content]

242

DynaMent ReferencesMetaData DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

MetaData DynaMent

You can use the MetaData DynaMent to read metadata of content items. It provides information about content items in a LiveServer Repository.


Output the metadata on content items in a project (mode="list")

Use child element <attributes> to output individual user attributes (mode="list")

List versions of a specified content item (mode="list-versions").

Reading Metadata ('list')

Purpose

The MetaData DynaMent in "list" mode is replaced at runtime by a list of general metadata relating to the content of a project, such as author, creation time, or language, together with selected content attributes (for tracking purposes, for example). The data can be output to the screen or to a file (CSV, XML). In the case of large reports, it is advisable to send the output to a file to avoid excessive system load.

You can use the MetaData DynaMent either with or without child elements.

Syntax

<rde-dm:metadata mode ="list"

project ="{projectname}" content ="{contentname}" status ="[final|draft]" buffersize ="[1|2|4|8...]" chunk ="{chunk number}" chunksize ="{number of records}" path ="{attributename}" delim ="{separator}" resulttype ="[csv|xml]" filename ="{filename}" encoding ="{encoding}" locale ="{locale string}" depth ="[0|1|...n]"

item-tag ="[{tagname}|notag]" >

<attributes> <attribute>{content attribute}</attribute>

... </attributes>

/>

243


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Parameters

mode (optional) Mode of the MetaData DynaMent, here "list". Default setting; can be omitted.

project (optional) Name of the project whose content data is to be listed. If nothing is specified: Current project

content (optional) Name of the content whose metadata is to be listed. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml). If nothing is specified: The data for all content items in a project is listed.

status (optional) Status of the listed content.

"final": Only content items with status "Released" are listed.

"draft": Only content items with status "Draft" are listed.

Value if nothing is specified: "final"

buffersize (optional) Only used if no output file is specified in the filename parameter. Note: If the chunk and chunksize parameters are specified, this parameter is ignored. Limits the buffer size available for displaying contents. Examples: buffersize="1" equals 1 KB; buffersize="4" equals 4 KB. Based on the memory available, you should not set this value too high, because it might slow the system down. Value if nothing is specified: "32", for 32 KB.

chunk (optional, only effective when used together with chunksize) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. Value if nothing is specified: "-1"; chunking is not used.

chunksize (optional, only effective when used together with chunk) The chunksize parameter specifies the maximum number of content items in the result of the MetaData DynaMent. If the number of items found is greater than chunksize, then the remaining items are displayed in the next chunk after sorting. Value if nothing is specified: "-1"; chunking is not used.

244


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

path (optional) Optional attribute path in the content attribute hierarchy. Only attributes below the specified path are output (for example, profile). Note: Content attributes are only displayed if the depth parameter has at least the value "1".

delim (optional) Only for resulttype="csv": Delimiter between the individual columns. Value if nothing is specified: ";"

resulttype (optional) Specifies the type of output.

"csv": Output as CSV file.

"xml": Output as XML file.

Value if nothing is specified: "csv"

In XML files, the following characters are modified in attribute names: Space: Replaced with underscore. Digit as first character in attribute name: An "a" precedes the number.

filename (optional) Valid file name for data output to a file. If nothing is specified: Output not in a file.

encoding (optional, only if parameter filename is used) Specifies the encoding method used to write the data to the file (for example, ISO-8859-1 or UTF-8). If nothing is specified: Value of parameter reddot.encoding.default from the system configuration.

locale (optional) Language of the content data and attributes to be listed. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. If nothing is specified: Language of the current session.

depth (optional) Used to output content attributes. Depth up to which the content attributes will be displayed. If depth="0", no attributes are displayed. Value if nothing is specified: "10".

item-tag (optional) Only for resulttype="xml": Tag name of the XML element that surrounds each selected content item in the result.


"notag": Content in the result is not enclosed in XML elements.

Value if nothing is specified: "rde-idea:content-item"

tag (optional) Only for resulttype="xml": This is the tag name of the XML element that displays the result of the DynaMent.



245


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Value if nothing is specified: "rde-idea:content"


Child Elements

The MetaData DynaMent also has a child element called <attributes>. DynaMents within values of a child element are processed. Inline notation is not supported, however.

<attributes> (optional) In this child element, it is possible to specify attributes in an attribute path explicitly in <attribute> elements. These attributes are then output to the result file. If the <attributes> child element is set, the path and depth parameters are ignored.

Notes

RedDot LiveServer can read content from external repositories. The metadata of this content is loaded into the RedDot LiveServer object cache, but not the LiveServer Repository. To display metadata for this type of content, the metadata of the content is read from the object cache and the LiveServer Repository when you specify the content parameter.

Result

A list of all the metadata for the content of a project that is present in the LiveServer Repository is output together with the selected content attributes. If an output file is specified in the filename parameter, only this file is used for output.

Error Handling

The MetaData DynaMent's information, warning, and error messages begin with 8 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:



246


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading content data and attributes:

<rde-dm:metadata status="final"

resulttype="xml" filename="c:\all.xml"

locale="en" project="trails"/>

The result:

<rde-idea:content resulttype="xml" locale="en" project="trails" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsl-

template="http://www.reddot.de/rde/ns/template" xmlns:rde-dm="http://www.reddot.de/rde/ns/dm" xmlns:rde-fdl="http://www.reddot.de/rde/ns/fdl" xmlns:rde-idea="http://www.reddot.de/rde/ns/idea" xmlns:rde-rd="http://www.reddot.de/2000/rde/rd" xmlns:rde-xmaps="http://

www.reddot.de/rde/ns/xmaps"> <rde-idea:content-item guid="standardcontent-f.69bf6">

<rde-idea:name>351.xml</rde-idea:name> <rde-idea:type>0</rde-idea:type> <rde-idea:description></rde-idea:description> <rde-idea:priority>0</rde-idea:priority> <rde-idea:defaultlocale>en</rde-idea:defaultlocale> <rde-idea:creator rde-idea:datetime="21.02.02 11:02"></rde-

idea:creator> <rde-idea:lasteditor rde-idea:datetime="26.06.02 17:29"></rde-

idea:lasteditor> <Country>Brazil</Country> <CMS_List>2_1_Target_DynaMent_Liste</CMS_List> <Section>Keyword 2</Section> <Type>Type 1</Type> <rank>1</rank>

</rde-idea:content-item> .... </rde-idea:content>

>

In this example, all content data in the system and content attributes up to a depth of "10" are output. The data is output to an XML file (all.xml) in the specified directory.

247


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading content data and content attributes from "path":

<rde-dm:metadata status="final" path="Type" resulttype="xml"

filename="c:\path.xml" locale="en" project="trails"/>

The result:

<rde-idea:content-item guid="standardcontent-ffffffffc0a80290-ed05de4644-ed05da627e"> <rde-idea:name>5010A13CE57445239C70C7BED230312C.xml</rde-idea:name> <rde-idea:type>0</rde-idea:type> <rde-idea:description></rde-idea:description> <rde-idea:priority>0</rde-idea:priority> <rde-idea:defaultlocale>en</rde-idea:defaultlocale> <rde-idea:creator rde-idea:datetime="05.04.02 13:21"></rde-idea:creator> <rde-idea:lasteditor rde-idea:datetime="30.05.02 16:05"></rde-idea:lasteditor> <Type>Type 1</Type>

</rde-idea:content-item>

Alongside the general content data, the content attributes below the attribute path "Type" are also output.

248


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

MetaData DynaMent with Child Element <attributes>

<rde-dm:metadata status="final" resulttype="xml" filename="c:\childs.xml" locale="en" project="trails"> <attributes> <attribute>Type</attribute> <attribute>rank</attribute> </attributes>

</rde-dm:metadata>

The result:

<rde-idea:content-item guid="standardcontent-ffffffffc0a80290-ed05de4644-ed05da627e"> <rde-idea:name>5010A13CE57445239C70C7BED230312C.xml</rde-idea:name> <rde-idea:type>0</rde-idea:type> <rde-idea:description></rde-idea:description> <rde-idea:priority>0</rde-idea:priority> <rde-idea:defaultlocale>en</rde-idea:defaultlocale> <rde-idea:creator rde-idea:datetime="05.04.02 13:21"></rde-idea:creator> <rde-idea:lasteditor rde-idea:datetime="30.05.02 16:05"></rde-idea:lasteditor> <Type>Type 1</Type> <rank>1</rank>

</rde-idea:content-item>

Alongside the general content data for the "admin" user, the two content attributes "Type" and "rank" are output.

249


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Listing Content Versions ('list-versions')

Purpose

The MetaData DynaMent in "list-versions" mode is replaced at runtime with a list of versions of a content item.

Syntax

<rde-dm:metadata

mode ="list-versions" project ="{projectname}" content ="{contentname}"

chunk ="{chunk number}"

chunksize ="{number of records}"

/>




Simple Call

<rde-dm:metadata mode="list-versions" content="index.html" project="html-

demo" />

Parameters

mode Mode of the MetaData DynaMent, here "list-versions".

project (optional) Name of the project whose content data is to be listed. If no value is specified: Current project

content Name of the content item from the LiveServer Repository whose versions will be listed. If content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

chunk (optional, only effective when used together with chunksize) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which is usually displayed across a number of different pages. If no value is specified: "-1"; chunking is not used.

250


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

chunksize (optional, only effective when used together with chunk) The chunksize parameter specifies the maximum number of versions in the result of the MetaData DynaMent. If the number of versions found is greater than chunksize, then the remaining items are displayed in the next chunk after sorting. If no value is specified: "-1"; chunking is not used.

Result

The result is an XML-structured list of all versions of the specified content, listed by age of the entries in descending order. If chunking is activated (parameters chunk and chunksize), then additional parameters are displayed, similar to the Query DynaMent: parameters chunk, chunksize, lastchunk and hits for the <rde-rd:versions> element, as well as the hit parameter for each <version> element.

<rde-rd:versions content="..." project="..." > <version id="final"> <createdat>...</createdat> <createdby>...</createdby> <comment>...</comment> </version> <version id="draft"> ... </version> <version id="1"> ... </version>

</rde-rd:versions>

Error Handling

The MetaData DynaMent's information, warning, and error messages begin with 8 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:

Return code Meaning

-8505 The content was not found


251

DynaMent ReferencesPortal DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Portal DynaMent

The Portal DynaMent is only available with the appropriate license, which enables the application portal connectors and the Portal DynaMent.

The Portal DynaMent lets you integrate applications in your project; they can be accessed via URLs and are defined in the portal application connector.

When the first request in a session is sent to a portal application, RedDot LiveServer creates a so-called portal application instance for this portal application in the requesting session.


Using portal applications ('include' mode)

Logging information about the current instances of a portal application in an ongoing session (mode="session")

Removing instances of a portal application from a session (mode="remove")

For more information about connectors for application portals, see the Connectors documentation.

Integrating Portal Applications as Content ('include')

Purpose

In "include" mode, the Portal DynaMent includes the result of a request to an instance of a portal application in the content being processed. The portal application must be defined via an application portal connector.

Syntax

<rde-dm:portal mode ="include" application ="{portal application}" instance ="{application instance}" initial-url ="[rdeBase|rdeLogin|rdeLogout| rdeRelogin|{explicit URL}]" url ="{explicit URL}"

include-mode ="[html|xml|cdata|mixed]"

/>





252


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:portal mode="include" application="reddot"

/>

The portal application connector example that has been supplied for www.reddot.de is integrated. The first time it is used, a portal application instance is created in a session and the connector host (with start path) will be called because no other URL has been defined in the initial-url parameter.

Parameters

mode Mode of the Portal DynaMent, here "include".

application Name of the portal application as defined in the application portal connector. The first time this portal application is called within a session, the portal application data defined in the connector will be loaded in the session, so that no inconsistencies arise due to changes to the connector during operation. For each portal application, any cookies for the application are administered in the session, and these cookies are available for every instance of this application in the session.

instance (optional) You can choose a name to identify an instance of the portal application within the session. The instance is created the first time it is used. Every instance has its own data room in which information concerning its status and the next URL to be called is administered.

initial-url The URL of the application that is used the first time the instance is used provided that the url parameter has not been specified. If nothing is specified, the value is the "base" acronym, which identifies the following combination of information defined in the connector: protocol, host name, and port (with start path). The other acronyms "logon," "logoff," and "relogon" identify the other URLs defined in the connector.

url (optional) You can specify an explicit URL of the portal application whose call result should be integrated in the processed content. If nothing is specified: The Portal DynaMent calls the portal application with the URL that the end user requested via a respective link or uses the initial-url if no such URL is available.

include-mode (optional) The content returned in the external application response can only be integrated in RedDot LiveServer content if the content is text. If the content is not text, it will be ignored in mode="include". The include-mode determines how content is added to processed content.

If nothing is specified: One of the following will be assigned depending on the content type of the response content.

"html" The content contained in the response content's body tag is inserted within a CDATA element.

253


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"xml" The response content is inserted as is without XML and DOCTYPE declarations. This means that the responsibility for well-formedness including namespaces lies with the portal application supplying the content.

"cdata" The response content is inserted within a CDATA element.

Value if nothing is specified: "html"




Value if nothing is specified: "rde-html-section"

cachingtime (optional) Maximum period in minutes during which the content remains in the cache. With the specific value "-1" the cachingtime parameter is not interpreted. Value if nothing is specified: "0"

Result

The DynaMent is replaced by the result of a successful request sent to the specified portal application. If a request is not successful, for example, if a content item cannot be integrated, the default page of the RedDot LiveServer default project is displayed in the default setting. You can define other content in the General -> Content for... area of the application portal connector. This content is used when different errors occur during portal application calls.

Error Handling

The Portal DynaMent's information, warning, and error messages begin with 23 in the thousands' place. You can send the return codes with the default parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:


-23321 Application portal connector not found

-23331 Application portal connector not active

-23341 Unable to connect to portal application

-23599 The necessary license is missing

254


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Portal Instances of the Current Session ('session')

Purpose

In "session" mode, the Portal DynaMent generates an XML structure, which logs information about the portal applications used in the current session. This mode is particularly useful for project managers, allowing them to monitor the development phase of a project.

Syntax

<rde-dm:portal mode ="session" item-tag ="[{tagname}|notag]"

/>




Simple Call

<rde-dm:portal mode="session" />

Parameters

mode Mode of the Portal DynaMent, here "session".

item-tag (optional) Tag name of the XML element that surrounds each selected content item in the result.



Value if nothing is specified: "rde-rd:portal-instance"




Value if nothing is specified: "rde-rd:portal-instances"

255


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


Result

An XML structure is returned that provides information about the portal application being used in the current session. It especially provides pertinent runtime information both on the application and the instance. The basic framework of the XML structure looks like this:

<rde-rd:portal-instances > <rde-rd:portal-instance name="..." >

<rde-rd:portal-application name="..." > <rde-rd:runtime-data>

<rde-rd:data name="..." > </rde-rd:data>

</rde-rd:runtime-data> </rde-rd:portal-application> <rde-rd:runtime-data>

<rde-rd:data name="..." > </rde-rd:data>

</rde-rd:runtime-data> </rde-rd:portal-instance>

</rde-rd:portal-instances>

Error Handling





-23341 Unable to connect to portal application


256


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Removing Portal Instances from Sessions ('remove')

Purpose

In "remove" mode, the Portal DynaMent removes an instance of a portal application you have specified from the current session, provided it exists.

Syntax

<rde-dm:portal mode ="remove" application ="{portal application}" instance ="{application instance}"

/>




Simple Call

<rde-dm:portal mode="remove" application="{portal application}"/>

A previously created instance of the specified portal application will be deleted from the session.

Parameters

mode Mode of the Portal DynaMent, here "remove".

application Name of the portal application as defined in the application portal connector. The first time this portal application is called within a session, the portal application data defined in the connector will be loaded in the session, so that no inconsistencies arise due to changes to the connector during operation. For each portal application, any cookies for the application are administered in the session, and these cookies are available for every instance of this application in the session.

instance (optional) You can choose a name to identify an instance of the portal application within the session. The instance is created the first time it is used. Every instance has its own data room in which information concerning its status and the next URL to be called is administered.

257


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


Result

If available, an instance of a portal application will be removed from the current session.

Error Handling





-23341 Unable to connect to portal application connector

-23501 Cannot find object


258

DynaMent ReferencesPortlet DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Portlet DynaMent

The Portlet DynaMent is only available with the appropriate license, which enables the portlet connectors and the Portlet DynaMent.

The Portlet DynaMent lets you integrate the content of portlets in your project when they are defined in the portlet connector.


Including the contents of a portlet (mode="include")

Maximizing portlets (mode="maximize")

Removing instances of a portlet from a session (mode="remove")

For more information about connectors for portlets, see the Connectors documentation.

Integrating Portlet Content ('include')

Purpose

You can use the Portlet DynaMent in "include" mode to integrate the content of a portlet or a portlet instance in the currently processed content. The portlet must be defined in a portlet connector.

Syntax

<rde-dm:portlet mode ="include" connector ="{portlet connector}" portletContext ="{portlet application context}" portlet ="{portlet name}" instance ="{portlet instance}" > <rde-dm:param name="{parameter name-1}"> {value} </rde-dm:param> ... <rde-dm:param name="{parameter name-n}"> {value}

</rde-dm:param>

</rde-dm:portlet>





259


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:portlet mode="include" connector="PortletConnector" portletContext="/

demoPortlet" portlet="DemoPortlet"/>

The content of the DemoPortlet portlet is included.

Parameters

mode Mode of the Portlet DynaMent, here "include".

connector Name of the portlet connector assigned in RedDot LiveServer.

portletContext Context name of the portlet application.

portlet Name of the portlet of the portlet application.

instance (optional) Instance name of the portlet assigned in RedDot LiveServer.

Child Elements

The Portlet DynaMent has additional, optional child elements. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-dm:param> (optional) Render parameters and their values are specified within this child element. If nothing is specified: The default values from the portlet connector are used.

Notes

You can define a default error page with type Error in portlet execution in the project settings. This page is displayed when errors occur during the execution and inclusion of a portlet.

Result

The DynaMent is replaced with the portlet content. The DynaMent returns an XML structure that can be rendered with an XSL style sheet.

Error Handling

The Portlet DynaMent's information, warning, and error messages begin with 33 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:



260


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Document for Maximized Display of a Portlet

Portlet DynaMent The document for maximized display must contain a Portlet DynaMent in "maximize" mode: <rde-dm:portlet mode="maximize" />.

External links You have to use special placeholders for links that point to content outside the portlet:

javax.portlet.rdeMaximizedFrom - Placeholder for the document for maximized display

javax.portlet.rdeMaximizedFromXsl - Placeholder for the style sheet for maximized display

Example for a link:

<a href="/#RDE-REQUEST:rdePrefix/#/xchg /#RDE-REQUEST:rdeProjectID/# /#RDESESSION:javax.portlet.rdeMaximizedFromXsl/#

/index.html">Home</a>

Maximizing Portlets ('maximize')

The Portlet DynaMent in "maximize" mode lets you maximize the display of portlets. A special page is defined for the maximize display in the connector, the Document for maximized display of a portlet. When this page is called and it contains a Portlet DynaMent in "maximize" mode, the portlet is displayed maximized.

Syntax

<rde-dm:portlet

mode ="maximize"

/>





Simple Call

<rde-dm:portlet mode="maximize" />

261


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameter

mode Mode of the Portlet DynaMent, here "maximize".

Result

Portlets are displayed maximized.

Error Handling


Removing Portlet Instances from Sessions ('remove')

Purpose

You can use the Portlet DynaMent in "remove" mode to remove specific information of a portlet instance from the current session.

Syntax

<rde-dm:portlet mode ="remove" connector ="{portlet connector}" portletContext ="{portlet application context}" portlet ="{portlet name}"

instance ="{portlet instance}"

/>







262


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:portlet mode="remove" connector="PortletConnector" portletContext="/

demoPortlet" portlet="DemoPortlet"/>

All instances of the specified portlet are deleted from the session.

Parameters

mode Mode of the Portlet DynaMent, here "remove".

connector Name of the portlet connector assigned in RedDot LiveServer.

portletContext Context name of the portlet application.

portlet Name of the portlet of the portlet application.

instance (optional) Instance name of the portlet assigned in RedDot LiveServer.

Result

The specified instance (or all instances) of a portlet is removed from the current session.

Error Handling




263

DynaMent ReferencesProcess DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Process DynaMent

The Process Dynament lets you control DynaMent processing, allowing you to intervene directly in the process.

This section shows you how to perform the following actions:

Stop processing at the calling interface and restart with the child elements of the Process DynaMent (mode="forward)".

Cancel processing and redirect the request internally (mode="redirect)".

Stop processing at the calling interface and restart somewhere else (mode="break)".

Control processing within an Attribute DynaMent in "for-each" mode (mode="continue)".

Restarting Processing with Child Elements ('forward')

Purpose

The Process DynaMent in "forward" mode lets you cancel processing at the point where it was called, and proceed with the child elements of this Process DynaMent. The child elements are used instead of the element specified with the control-id parameter, or instead of the entire content. The request is not changed.

Syntax

<rde-dm:process mode ="forward" control-id ="{rde-id}" >

<Child-Elemente/>

/>


tag ="[notag|{tagname}]" roles ="{userrole1;userrole2}"

process-mode ="[standard|none|remove|execute|ignore]"

Simple Call

<rde-dm:process mode="forward" control-id ="{rde-id}" > <rde-dm:include content="text.html"/>

</rde-dm:process>

Parameters

mode Mode of the Process DynaMent, here: "forward".

control-id (optional) Freely definable string of characters that identifies an element (e.g. DynaMent) in the processed tree. Recursive processing up to and including this element is cancelled and

264


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

replaced by the child elements of the Process DynaMent. The control-id used must be declared to the relevant element (e.g. DynaMent) as a value of the rde-id standard parameter, otherwise all content is replaced by child elements.

If no value is specified: all content is replaced by the child elements of the Process DynaMent.

tag (optional) Tag name of the XML element that encloses the DynaMent's child elements.

"notag": The child elements are not enclosed in an XML element.

"{tagname}": Explicit specification of tag name. To replace all content with child elements, a value should be specified, as XML syntax allows only a single document element.

If no value is specified: "notag":

Child elements

You can use any child elements. The child elements are used instead of the element specified with the control-id parameter, or instead of the entire content. DynaMents within values of child elements are processed. Inline notation is not supported, however.

Results

The child elements replace the element specified with the control-id parameter, or the entire content.

Error Handling

The Process DynaMent's information, warning, and error messages begin with 29 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the Error Handling section in the chapter About RedDot DynaMents.

Terminating Processing and Redirecting Request ('redirect')

Purpose

The Process DynaMent in "redirect" mode lets you terminate processing at the point where it was called. The current request is redirected within RedDot LiveServer to the URL specified.

Syntax

<rde-dm:process mode ="redirect" url ="{redirect url}" type ="[http|html]" status ="{http response status}" >

<Child-Elemente/>

/>

265


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


roles ="{userrole1;userrole2}"

process-mode ="[standard|none|remove|execute|ignore]"

Simple Call

<rde-dm:process mode="redirect" url="/cps/rde/xchg/demo" >

<rde-dm:include content="text.html"/>

</rde-dm:process>

Parameters

mode Mode of the Process DynaMent, here: "redirect".

url The URL that is the redirect target. You can also specify URL parameters.

type (optional) Method for executing redirects from the browser. The following values are possible:

"http": The response specified in the http specification with statuses for group 3xx.

"html": The redirect specified via HTML headers, which is executed by the browser.

If no value is specified: "http"

status (optional) Only for type="http": Determines the HTTP response status. This should be a group 3xx status.

If no value is specified: "302"

Child elements

You can use any child elements. DynaMents within values of child elements are processed. Inline notation is not supported, however. The child elements sent as an entity with the redirect response after processing. Rendering is performed using the XSL style sheet of the original request. The predefined attribute "request:rdeCurrentXslId" lets you specify a different XSL style sheet. The rendered result is written to the redirect response as body. This body is displayed if the browser does not support redirecting. Enter a link to the page that should have been displayed and a message, such as: "If your browser does not support redirects, click this link:".

Results

The Process DynaMent is rendered and inserted as a document element in the document to be rendered. It therefore overwrites any existing content.

266


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The Process DynaMent's information, warning, and error messages begin with 29 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the Error Handling section in the chapter About RedDot DynaMents.

Restarting Processing Somewhere Else ('break')

Purpose

The Process DynaMent in "break" mode lets you stop processing at the point where it was called. Processing restarts following the innermost enclosing Control DynaMent, or following the element specified in the control-id parameter. Control DynaMents are the Attribute DynaMent in "condition" or "for-each" mode, and the Include DynaMent.

Syntax

<rde-dm:process mode ="break"

control-id ="{rde-id}"

/>




Parameters

mode Mode of the Process DynaMent, here: "break".

control-id (optional) Freely definable string of characters that identifies the enclosing element (e.g. DynaMent) in the processed tree. Processing restarts following this element. The control-id used must be specified in the relevant element (e.g. DynaMent) as a value of the rde-id standard parameter, otherwise processing restarts following the innermost enclosing Control DynaMent.

If no value is specified: processing restarts following the innermost enclosing Control DynaMent.

Notes

If no element is found after which processing should restart, the DynaMent is ignored and generates the return code shown below.

267


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Results

Processing restarts following the innermost enclosing Control DynaMent, or following the element specified in the control-id parameter.

Error Handling

The Process DynaMent's information, warning, and error messages begin with 29 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:

Return code Meaning

29502 Control element not found - no result

268


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Controlling Processing in for-each Loops ('continue')

Purpose

You can use the Process DynaMent in "continue" mode only within an Attribute DynaMent in "for-each" mode. The Process DynaMent stops processing of the current element of a for-each loop in the innermost enclosing Attribute DynaMent, and restarts processing with the next loop element. Elements within the current loop element that have not yet been processed are not processed, and they are not included in the result.

Syntax

<rde-dm:process

mode ="continue"

/>




Parameters

mode Mode of the Process DynaMent, here: "continue".

Results

Processing restarts with the next element of a for-each loop.

Error Handling

The Process DynaMent's information, warning, and error messages begin with 29 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:

See also:

Making Attribute Values or Child Attributes Available ('for-each') (Page 69)

Return code Meaning

29502 Control element not found - no result

269

DynaMent ReferencesQuery DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Query DynaMent

The Query DynaMent is only available with the appropriate license, which activates the search engine connectors and the Query DynaMent.

You use the Query DynaMent to address a search engine in order to perform a full-text search for content within one or several RedDot LiveServer projects. To execute the call, you have to have installed the necessary search engine and configured it for RedDot LiveServer. If you have the appropriate license, the Verity search engine is included with RedDot LiveServer.

If you use the K2 Server from Verity, you can search all the Verity indexes that are managed on the K2 Server—even those not generated by RedDot LiveServer. Important Note: The OEM partnership agreement between RedDot and Verity specifies that you may only index content that you have imported into a LiveServer Repository.

The Query DynaMent is replaced by the search result at runtime. When a Query DynaMent is processed, the corresponding call is sent to the search engine. The search engine responds to the call based on the content indexed in the search engine. RedDot LiveServer then checks any content it finds to ensure that it meets the content constraints in the requested session. Only the content that meets this criteria will be displayed as a result of the Query DynaMent.

In addition to this type of conditional personalization, you can also define other content attributes as search criteria to further classify or personalize, for example, comparing the user attributes of the calling session. The content attributes' paths must be specified in the search engine so that they will be included during indexing (go to Administer RedDot LiveServer -> Connectors -> Search Engines -> Map Content Attributes).

The search engine index will include all project content that has been released and for which the full-text search option has been selected. When relevant changes are made to content, RedDot LiveServer automatically creates a corresponding entry in the index queue, which is then processed asynchronously. To view the index queue, go to Administer RedDot LiveServer -> Connectors -> Search Engines -> Edit Index Queue.

A search engine index is created for each project language. A Query DynaMent call lets you search the search engine indexes of multiple languages. You specify the desired languages using the locale parameter. If no language is specified, the language of the calling user session is used. For searches run on multiple languages, one search query is sent for each language. The result lists for the individual searches are then compiled into one list. The individual results are sorted automatically, as determined by the internal ranking of the search engine.


Creating a search query

Using the searchable="true" parameter

Listing all the search engine indexes managed on the K2 Server (mode="list")

Entering simple search queries

For more information about search engine connectors, see the Connectors documentation.

270


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Creating Search Queries

Purpose

The Query DynaMent lets you carry out a full-text search on content, even on several RedDot LiveServer projects and languages. If you use the K2 Server, you can also search external Verity indexes that were not generated by RedDot LiveServer. The OEM partnership agreement between RedDot and Verity specifies that you may only index content that you have imported into a LiveServer Repository.

There are two ways of issuing search queries using the Query DynaMent:

A simple query in the child element <rde-dm:query-cis>

A query in the specific language of the search engine, for example in the child element <rde-dm:query-verity>.

Syntax

<rde-dm:query project ="{projectname;projectname;..}" locale ="{locale string}" repository ="{alias;alias;...}" external-only ="[no|yes|ignore]" include-mode ="[{include-mode},{tagname};]" metainfo ="[{metainfo-name},

{context-mode};]"

context-tags ="[{tagname},{context-mode};]"

context-mode ="[mixed|cdata|xml|none]" chunksize ="{number of records}"

chunk ="{chunk number}" maxhits ="{number}" sortedby ="{searchengine fieldname}" sortorder ="[asc|ascending| desc|descending]" highlight ="[no|yes]" ignore-constraints ="[no|yes|completely]" depth ="[0|1|...n]" appserver ="[yes|no]" dateformat-out ="{date format}"

dateformat-in ="{date format}"


<rde-dm:query-cis> query

</rde-dm:query-cis>

<rde-dm:query-verity> query (Verity-specific)

</rde-dm:query-verity>

</rde-dm:query>

271


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Special parameter (optional):

searchable = "[true|false]" (see next section for description)

Parameters

project (optional) Name of the project in which the search is to be conducted, or if multiple projects are to be searched, a list of names of the projects separated by semicolons. Value if nothing is specified: Project of the content containing the DynaMent.

locale (optional) Language of the search engine index to be searched; for searches over several languages, a list of languages separated by semicolons. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. A search engine index is created for each language of a project, where required. Value if nothing is specified: User language of the requesting session. The user language can be set using the respective user field in the Edit User dialog window via the User DynaMent or by using the Attribute DynaMent for the user attribute with the reserved name "rde.locale". If there is no search engine index for this language or for the locale specified, the default project language is used for the search.

repository (optional) Alias name of the external search engine indexes managed by the K2 Server that you want to search. If you want to specify several alias names, use semicolons as separators. Note: You can display a list of possible alias names using a Query DynaMent in "list" mode. If nothing is specified: No external search engine index.

external-only (optional) Indicates which of the search engine indexes managed by the K2 Server you want to search. The following values are possible:

"no": Both external and internal search engine indexes specified in parameters project, locale, and repository are searched.

"yes": The project and locale parameters are ignored. Only the search engine index specified in repository is searched.

"ignore": Only the internal search engine indexes from RedDot LiveServer that are specified using parameters project and locale are searched.


272


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

include-mode (optional) Selects which information about the content that has been found is added to the DynaMent result. The following values are possible:


"content-reference": Minimal information for rendering a reference to the applicable content in each of its XML elements: name, type, MIME type; for BLOB type content, also the file size in the size element.



"content": Only for content of the types XML, HTML, XSL, or SCRIPT: The actual content data for the respective language. For BLOB type content, only minimum information is specified (MIME type, size).

"metainfo": The search engine metadata selected in the metainfo parameter.


Every include-mode selected increases the runtime if the result is not already available in the cache. Therefore, we recommend using the include-mode parameter for information that needs to be evaluated or presented to the user. Note: Only the value for metainfo is evaluated for hits from external search engine indexes, which means only metadata is returned.

Value if nothing is specified: "content-info,notag;context-tags,notag"

metainfo (optional) Determines which of the metadata managed in the search engine is included in the result of the Query DynaMent. The type of metadata available - in addition to the search engine fields that are mapped to content attributes - is determined by the search engine used (also see tip below). You can specify one or more values separated by semicolons as metainfo. The values are not case sensitive. A separate context-mode can be specified for each of the selected metadata items if a value other than that of the global context-mode parameter is required. The following is an example of the correct syntax: "score,context-mode1;author;metainfo3,context-mode3" To be able to include metadata, you need to specify the mode "metainfo" in the include-mode parameter. If nothing is specified: No metadata is returned. Note: Only metadata is returned for hits from external search engine indexes. RedDot LiveServer has read access to the metadata provided by the external search engine indexes. To display a list of the metadata in an external search engine index, use a Query DynaMent in "list" mode.

context-tags (optional) Determines which tag should be added to the result of the Query DynaMent and how. A single tag name, or multiple tag names separated by semicolons, which are transferred from each content item found to the resulting XML of the DynaMent. Notes: To be able to use context tags, you have to select at least the context-tags mode in

273


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

the include-mode parameter (default setting). A separate context-mode can be specified for each individual tag name, if a value other than that of the global context-mode parameter is required. If you specify "none", then an individual context-mode must be specified for each tag so that the tag will appear in the result. Supported syntax: "tagname1,context-mode1;tagname2;tagname3,context-mode3" Only the content of the first content tag is returned with the specified name. The entire non-personalized content is used for the output; not only the area limited by a possible <rde-dm:query searchable="true">. If the tag includes child elements, they will be returned as well. You can use this function, for example, to add content information or information on displaying individual content items to the resulting XML and present it to the user. Value if nothing is specified: "title,[specification from context-mode]" Value if no value is specified for the context mode parameter: "title,mixed"

context-mode (optional) Mode used to integrate the content of the context-tags and the <context> element in the XML search result (for <context>, see "Result" below). You can specify the context-mode parameter either globally or separately for each individual tag name of context-tags.

"mixed": Any angle brackets of tags contained in the content are replaced with their XML entities (<, >). Integrates the <context> element.

"cdata": The content is encapsulated in CDATA sections. This mode ensures that the resulting XML is well-formed even if the contents are not. Integrates the <context> element.

"none": The context-tags will not be included in the result. The <context> element is not created.

"xml": The text from the content item is added to the XML with the search results without being replaced or verified. XML conformity is not guaranteed. In fact, the transferred section must be XML-compliant in order to deliver the XML with the search results. Integrates the <context> element. Note: Using the "xml" mode is not recommended for new projects. It is mainly intended to ensure downward compatibility with existing projects.


chunksize (optional) Maximum number of content items that may be included in a result of the Query DynaMent as defined by the chunksize parameter. If the number of items found is greater than chunksize, then the remaining items are displayed in the next chunk after sorting. Possible values: "1" to "500" Value if nothing is specified: "11"

chunk (optional) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. The resulting XML element of the Query DynaMent returns the parameters previouschunk, nextchunk, lastchunk, hits, maxchunks-ca, chunk, and chunksize, which can be implemented using XSL scrolling functions. Value if nothing is specified: "1". This value is also used if the starting point of the chunk exceeds the maximum possible value.

maxhits (optional) Maximum number of hits returned by the search engine (1 to n). Value if nothing is specified: "500"

274


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

sortedby (optional) Search engine field name that is assigned to the RedDot LiveServer attribute path and that is used to sort the content items alphanumerically in the result. To perform a cascading sort of several fields, specify several field names separated by spaces. When entering the field names, every field name except the last one must be followed by the sort direction, either "asc" or "desc" and separated by a space. Do not enter a sort direction for the last field name. It will be determined by the value of the sortorder parameter. Here is an example of a sort according to year (ascending) and month (descending): sortedby="year asc month" sortorder="desc" If nothing is specified: The sequence of content items in the result corresponds to the score calculated internally by the search engine.

Note:

There may be problems with this parameter if you specify multiple languages for the locale parameter, or projects with multiple languages for the project parameter. In such a case, avoid using the sortedby parameter, because separate searches are carried out and the result lists will be automatically compiled and sorted according to the search engine's internal ranking (score).

Entity values in search engine fields are not replaced with special characters. If content attribute values assigned to search engine fields contain entities, they can cause problems with the sort order of the search results.



"desc" or "descending": descending order

Value if nothing is specified: "asc"

Note: There may be problems with this parameter if you specify multiple languages for the locale parameter, or projects with multiple languages for the project parameter. In such a case, avoid using the sortorder parameter, because separate searches are carried out and the result lists will be automatically compiled and sorted according to the search engine's internal ranking (score).

highlight (optional) Display context and search term in search results. This parameter has no effect if context-mode is specified as "none".

"no": The context is not determined. The beginning of the searchable zone is returned as <context>. The search term itself is not highlighted. It is only displayed if it is contained in this zone.

"yes": The context is determined and returned. A markup is used to highlight the search term in the context.


ignore-constraints (optional) Setting that determines whether content constraints are considered for the display of search results (see also the constraints parameter in the Result section).

275


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"no": Default setting. Content is only found and displayed as a search result if the content constraints are met for the requesting user.

"yes": Content is found and displayed as a search result even if the content constraints are not met for the requesting user. The content constraints are still checked. The result for every content item found is shown as a constraints attribute in the search result. However, the content is not included, even if it is requested with include-mode="content".

"completely": The content constraints are not checked. Content is found irrespective of whether the content constraints are met, and shown in the search result. This setting allows you to accelerate the search if you do not have to check content constraints.


depth (optional) Maximum depth to which further DynaMent calls are to be included. Example for depth="1": If further Include statements are present in the inserted content then this content is also included. However, if this new content also contains Include statements, they will be ignored. Value if nothing is specified: "1"





dateformat-out (optional) Determines how date fields are displayed in search results. You can specify predefined Verity placeholders that will be replaced by DynaMent results. You can also specify your own text (for example, dateformat-out="${dd}.${mm}.${yyyy} – that was the ${ddd} day of the year and a ${day} "). A list of Verity placeholders and their meanings can be found in the file syntax_dateformat-out.pdf in the directory <RedDot Web application path>/docu/en/pdf_documents.

If nothing is specified: The default date formats of the respective locale will be used.

dateformat-in (optional) Determines the date format that will be used in search queries. This is particularly useful in cases where the date format is not clear. This does not affect date information that cannot be misinterpreted (for example, aa.bb.cccc). The following values are possible:

"MDY": American format (the default format used by all English search engine indexes). Date information in the format "aa-bb-cc" will be interpreted to mean "aa" month and "bb" day.

"DMY": English format (the default format used by all German search engine indexes): Date information in the format "aa-bb-cc" will be interpreted to mean "aa" day and "bb" month.

276


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"YMD": European format: Date information in the format "aa-bb-cc" will be interpreted so that "bb" means month and "cc" means day.

"YDM": Swedish format: Date information in the format "aa-bb-cc" will be interpreted so that "bb" means day and "cc" means month.

If nothing is specified: The default date formats of the respective locale will be used.

Note: If you use the K2 Server, the dateformat-in parameter is ignored. You can define the date format for the K2 Server or for individual indexes (collections). If you set the system configuration in RedDot LiveServer accordingly, the default value defined by the locale of the individual indexes will be overwritten by the date format used for indexing the search engine (key: reddot.searchengine.verity.dateformat.K2.set.collcreation, value: true). As a result, any changes to the date format in the K2 settings will be retained during the creation and reindexing of projects. You can specify the date format for search engine indexing in the reddot.searchengine.verity.dateformat key in the system configuration (go to <RedDot Web application path>/WEB-INF/etc). For more information, see the Installation documentation.

item-tag (optional) Tag name of the XML element that surrounds each found content item in the result.



Value if nothing is specified: "rde-rd:searchresult-item"




Value if nothing is specified: "rde-rd:searchresult"

cachingtime (optional) Interval in minutes during which the search results remain in the search result cache. Note: This interval will also be evaluated during the calculation of the actual caching time of contents in the component cache, which is determined by the shortest caching time of all the components. With the specific value "-1", the cachingtime parameter is not interpreted. Value if nothing is specified: Value of the Default caching time for search results entry in the settings of the project defined under project. If more than one projects are specified under project, the shortest caching time defined in one of these project is used. If nothing is specified in the project settings (go to: Main Menu ->Select Project -> Edit Project Settings -> area: search engine) then the default value is "10". For details on caching, see the information below: Caching Results of the Target DynaMent and of the Query DynaMent.

277


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Child Elements

The Query DynaMent has two alternative child elements. The search query is specified in one of these two elements.

Note: DynaMents within values of a child element are processed. Inline notation is supported. If you want to use slashes (/) and backslashes (\) in search queries, you have to model them as an escape sequence - that is, with a leading backslash. Because special characters, in particular angle brackets, are frequently used in search requests, it is advisable to enclose each query in a CDATA section: <![CDATA[query]]>.

<rde-dm:query-cis> (optional) The <rde-dm:query-cis> child element contains the search engine query in a simple form that is familiar to Internet visitors from the commonly used search engines. An XML node containing the search request is inserted for the employed search engine in the DynaMent's XML result. The <rde-dm:query-verity> child element is also inserted in the XML result. The search request, translated into Verity Query Language, is placed in the content of this child element.

<rde-dm:query-verity> (optional) Alternatively, the search engine query can be located in the <rde-dm:query-verity> child element in the Verity Query Language used by the Verity search engine. No further nodes are inserted in the XML result. This element is only required if you want to perform a high-performance search using Verity Query Language. For instructions on using this search language, see the description of the Verity Query Language in the Verity handbook, the English version of which is available in the RedDot LiveServer documentation directory (<RedDot Web application path>/docu/en/pdf_documents) in both PDF and HTML format.

Result

The result in XML for a Query DynaMent is a list of the content items found. The content list is enclosed by an element that is specified in the tag parameter. Each individual content item is enclosed by the tag specified in the item-tag parameter. The parameters of the tag element (default: "rde-rd:searchresult") consist of the repeated display of the parameters of the original Query DynaMent, augmented by the following parameters:

hits: Total number of all non-personalized content items found. Fewer hits may be displayed for a session.

maxchunks-ca: Maximum number of chunks.

lastchunk: Number of the last possible chunk (when all found content items for the session are available).

nextchunk: Number of the next chunk.

previouschunk: Number of the previous chunk.

error: Error code that is also returned in the standard parameter result-attribute (see Error Handling below). If a search was successful, error ="0" is returned here.

error-engine Search engine's internal error code. This parameter is only returned if an internal error has occurred in the search engine (error= -5301).

The individual content items found are placed consecutively in item-tag elements (default: "rde-rd-searchresult-item") in the order returned by the search engine. In addition to the name, the resulting XML also contains further information about a content item, such as

278


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

project, language, content group, content type, information about content constraints, serial number, and context. When hits are found in external search engine indexes, the alias name of the external search engine index is placed in the "repository" parameter.

constraints Information on whether the content constraints are met by the requesting user or not. The following values are possible:

"no-constraints": There are no content constraints for this content item.

"matched": Content constraints for this content item are met.

"not-matched": Content constraints for this content item are not met. Content items with this value are only displayed in the result if the ignore-constraints="yes" parameter has been set in the requesting Query DynaMent.

"not-evaluated": The content constraints for this content item were not checked. Either the ignore-constraints="completely" parameter was set in the requesting Query DynaMent or the hit came from an external search engine index.

hit Sequence number of the found content for the active session within all chunks.

<context>: Context where the found content is located. If search items were used without operators, the first of these words is sought in the found content items, highlighted, and added to the resulting XML in the center of a section approximately 180 characters long, under the <context> tag. This only works for content with type XML, XSL, and HTML, and cannot be guaranteed. RedDot LiveServer attempts to find the search item outside the markup and within the area that has actually been indexed. It is also possible that the context location lies within an area that is not delivered, for example, due to defined DynaMent rules. If no corresponding location is found, the searchable area starts with <context>, without taking markups into account. Note: The context is not returned if:

the value "none" was specified for the context-mode parameter, or

the value "meta-info" was specified as the only value for the include-mode parameter.

279


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The information, warning, and error messages for the Query DynaMent begin with 5 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:

For more information about setting the locale policy for the search engine, see the Projects/Contents documentation.

For more information about assigning content attributes to search engine fields, see the Connectors documentation.


5201 The maximum processing depth was reached.

-5300 General error message for unsuccessful searches.

-5301 The search engine itself reports an error (output in the "error-engine" result parameter).

-5310 None of the Verity repositories requested by the search is available.


-5321 Problem preparing the native search (JNI setting only).



-5330 General error message for unsuccessful search.

-5331 lsserver rejected the search due to a system overload.

-5332 Transfer to lsserver failed due to encoding problems.

-5333 lsserver not responding, or other URL connection problems.

-5334 The result returned by lsserver is completely blank.

-5335 The result returned by lsserver is uncertain.

-5336 The result returned by lsserver cannot be parsed.

-5337 Transfer of search query to lsserver has failed because parameters are too long.

-5340 Problems reading the result of a native search.

-5350 For the combination of ProjectIDs and localeStrings entered, no Query Plan could be created.

-5510 The SearchEngineIolet is not available.

-5520 The LiveServer that serves as search engine server is not accessible.


280


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Displaying Metadata in Results

The metainfo parameter lets you select which of the metadata administered in the search engine is included in the result of the Query DynaMent. The Verity search engine regularly supplies metadata such as score (hit list range) and, depending on the format of the indexed content, header information (such as author).

Other examples:

VDKSUMMARY: A static summery of the content is displayed in the result.

VDKPBSUMMARY: The keyword and its context are displayed in the result. Under the default settings, the display is limited to the first 8 kB of the content. If you use the K2 Server and set the highlight parameter to "yes", then the keyword is flagged with the <rde-rd:ts> tag. Note: If you want to change the default setting of 8 kB, you can do so in the style.prm file for each Verity index. You then have to reindex the content.

Caching Results of the Target DynaMent and of the Query DynaMent

Target DynaMent results or Query DynaMent results are stored in the search result cache if the caching time was not set to zero. If another call of a Target DynaMent or of a Query DynaMent has exactly the same search criteria, an entry in the search result cache is used as follows:

1. At first, the list of the content items found is used again regardless of any permission constraint.

2. The check of the permission constraints that follows filters the contents for every requesting session for each chunk. If requested again by the same session, the results of checking the permissions are used again, too.

3. XML displays are created according to parameters of the DynaMent for displaying the content of the requested chunk. These displays are saved as separate cache entries in the object cache and are re-used for repeat requests.

Re-using these data usually reduces the load and improves the performance. Therefore, results of the Target DynaMent and of the Query DynaMent should normally be held in the cache. The procedure described usually results in correct deliveries from the cache but has its limitations. In particular, not updated results are returned from the search result cache, if one of the following events occur before calling a Target DynaMent or Query DynaMent again:

Attributes are changed in the same session, affecting the result of checked content constraints.

Content constraints are changed, affecting the result of previously checked content constraints (for example, by additional import).

281


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

To ensure correct delivery from the search result cache in such project situations, you can

set the caching time in the DynaMent short enough, so that the effects of deviations in the project are irrelevant, or

change the search criteria a little or equivalently so that multiple entries are used in the search result cache, or

add a separate dependency (Cache DynaMent mode="add-dependency" or OpenAPI) and mark as changed if needed (Cache DynaMent mode="notify" or OpenAPI).

Simple HTML form for entering a search term. It calls the XML file (searchengineresult.xml):

<form action="/#RDE-REQUEST:rdePrefix/#/xchg/ #RDE-REQUEST:rdeSessionID/#/#RDE-REQUEST:rdeProjectID/# /searchengineresult.xml" method="GET"> <table>

<tr> <td>Suchanfrage: </td> <td><input name="query"> </input></td>

</tr> <tr>

<td><input type="submit"/></td> </tr> </table>

</form>

Subsection of the XML file (searchengineresult.xml) which describes the "action" of the HTML file and calls the search via the Query-DynaMent:

<result> <rde-dm:query context-tags="summary" highlight="yes">

<rde-dm:query-cis> <![CDATA[ [#request:query#] ]]>

</rde-dm:query-cis> </rde-dm:query>

</result>

The request parameter with the name query is used as the search request. The value of this parameter is entered in the HTML form.

Query DynaMent search result for the search term "Mexico":

In the example, the following content item is found (among others): 69_149.htm. The result of the Query DynaMent is displayed in the element <rde-rd:searchresult>. The individual located content items are output sequentially in <rde-rd-searchresult-item> elements in the order returned by the search engine. Other content-related information is also output in addition to the name.

282


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<result> ... <rde-rd:searchresult searchengine="verity" project="html-demo" locale="de" chunk="1" maxchunks-ca="3" lastchunk="3" nextchunk="2" chunksize="11" hits="33" highlight="yes" maxhits="500" context-tags="summary" context-mode="mixed" metainfo="">

<rde-rd:searchresult-item constraints="no-constraints" hit="1">

<name>69_149.htm</name> <locale>en</locale> <type>HTML</type> <released>true</released> <guid>standardcontent-ffffffffc0a8028c-efc721d070-efc764f885</guid> <group>html-content</group> <description /> <last-updated>2004-10-07 14:39:11.398</last-updated> <context> Up and Away: main page Countries (CT) ©2001 by RedDot Solutions AG <rde-rd:ts>Mexico</rde-rd:ts> Introduction Travel Info Geography GEOGRAPHY Area: 1,953,162 sq km (761,603 sq miles) Population: 94,400,000 ... </context> <summary />

</rde-rd:searchresult-item> ...

<rde-dm:query-verity> <![CDATA[mexico ]]>

</rde-dm:query-verity> <rde-dm:query-cis>

<![CDATA[mexico ]]> </rde-dm:query-cis>

</rde-rd:searchresult>

</result>

You can use a suitable XSL style sheet to convert the search results into an HTML page.

283


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Limiting Search Area with Parameter 'searchable'

Limiting the Full-Text Search

In additional Query DynaMents, you can use the special parameter searchable="[true|false]" to prevent particular content areas from being indexed by the search engine. In this way, for example, you can keep navigation bars and headers from being part of the search. Note: A Query DynaMent that uses this special function cannot use the other Query DynaMent parameters.

The search function options can be configured in a number of places. Use the check box "Full-text search" to define whether content groups and individual content items will be analyzed and indexed by the search engine. Also, each individual search request can be restricted to certain content groups and content types.

searchable (optional) Allows you to selectively control which areas of your content will be subject to indexing by the search engine.

"true": If a content item contains one or more Query DynaMents with searchable="true", only content within these DynaMents will be located and indexed. If searchable="true" is set, the DynaMent returns the enclosed content unchanged in the result. If a content item contains several embedded DynaMents with searchable="true", only the outermost DynaMent will be evaluated.

"false": If a content item contains one or more Query DynaMents with searchable="false", content within the DynaMents will be excluded from the search. This also holds true for those DynaMents with searchable="false" that are embedded in Query DynaMents with searchable="true".

If Query DynaMents with both searchable="false" and searchable="true" are located in a content item, the parameter that is found first determines how unenclosed content is evaluated. So,

if searchable="false" is found first, the value "true" applies to all content that is not enclosed by a Query DynaMent.

if searchable="true" is found first, the value "false" applies to all content that is not enclosed by a Query DynaMent.

Evaluation of Parameter Values yes/no and true/false

Some parameters of RedDot LiveServer have true and false as possible values, while others have yes and no. As of Version 3.5 of RedDot LiveServer, you can use both true and yes, as well as both false and no. You can use either upper or lower case.

This simplification applies to all areas of RedDot LiveServer. It applies in particular to the parameters of RedDot DynaMents.

284


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Illustration of the syntax of the parameter searchable based on schematic HTML content:

<html> <head> ... </head>

<title> ... </title>

<body> <navigation>Identical on all pages</navigation>

<advertisement: not for the search engine> .. </advertisement>

<Header: Identical on all pages>

</Header>

<rde-dm:query searchable="true"> <Text area> Content in this area will be indexed... </Text area>

</rde-dm:query>

<Search input> Input field

</Search input>

<rde-dm:query searchable="true"> <another search area> Content in this area will be indexed... <rde-dm:query searchable="false">

Text area excluded from the search... </rde-dm:query> Content in this area will be indexed...

</another search area>

</rde-dm:query>

<Footer: Identical on all pages> </Footer> </body>

</html>

In the previous example, only those areas enclosed in the Query DynaMents with searchable="true" will be indexed. One of these areas contains content that will be excluded from the search, because it is enclosed in a Query DynaMent with searchable="false".

285


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Listing Search Engine Indexes ('list')

Purpose

If you use a K2 Server, you can use the Query DynaMent in "list" mode to list all the search engine indexes that are managed on that K2 Server. These can include both internal indexes from RedDot LiveServer and search engine indexes that were not generated by RedDot LiveServer.

Syntax

<rde-dm:query mode ="list" external-only ="[yes|ignore|no]"

item-tag ="[{tagname}|notag]" />




Parameters

mode Mode of the Query DynaMent, "list".

external-only (optional) Indicates which of the search engine indexes managed by the K2 Server you want to list. The following values are possible:

"yes": Only external search engine indexes are listed-that is, indexes not generated by RedDot LiveServer.

"ignore": Only internal search engine indexes are listed-that is, indexes generated by RedDot LiveServer.

"no": Both external and internal search engine indexes are listed.





If no value is specified: "rde-rd:listresult-item"

286


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

tag (optional) Tag name of the resulting XML element that displays the results of the DynaMent.



If no value is specified: "rde-rd:listresult"

Results

A list of the search engine indexes is returned in XML format. The full list is enclosed by an element that is specified in the tag parameter. Each individual entry in the list is enclosed by the tag specified in the item-tag parameter. The result also contains a list of the metadata from external search engine indexes. RedDot LiveServer has read access to the metadata provided by the external search engine indexes.

Error Handling

The information, warning, and error messages for the Query DynaMent begin with 5 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the Error Handling section in the chapter About RedDot DynaMents.

Entering Simple Search Queries

A search query that uses a Query DynaMent should allow inexperienced users to obtain results quickly and easily, while also permitting more practiced users to formulate more refined searches. RedDot LiveServer provides the following options for entering a search engine query in child element <rde-dm:query-cis>:

Simple entry A single word as the search term. For example: "japan" or japan. Exactly this word is searched for. The case of the characters is only taken into account if the search term contains both uppercase and lowercase letters. The individual words can be entered, quoted, or unquoted.

Phrases Example: "used cars" Search terms that are entered in quotes (phrases) are searched for exactly in the specified form. You can search for "http" or other frequently used terms that search engines usually filter out or ignore (keyword: STOP words and phrases). Note: Some languages (such as German) use compound words. The Verity search engine automatically divides these words into their basic components and saves them individually in the search engine index. Example: A document contains the word Bundesministerium (federal ministry). The search engine index saves entries for Bundesministerium, Bundes and Ministerium in this case. Therefore, if a user searches for "Bundes", content items that contain the word Bundesministerium are also found.

287


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

List of search terms Example: japan airline delta If several search terms are entered, then only content items that contain all the search terms are returned as the result of the search (keyword: AND operator). Use of placeholders in a search term: *: The asterisk replaces an indefinite number of characters in the search text. Example: japa* finds "Japan", "Japanese", and so on. ?: A question mark replaces exactly one character in the search text. Example: japa?, finds "Japan". You can use placeholders at any position in a word.

Search term should not occur If the search term is preceded by a - (minus sign), then only contents are found that do not contain this search term (keyword: NOT operator). Alternatively, you can also use !, NOT, or ̂ .

Bracketed list of search terms Example: (japan australia germany) All pages that contain at least one of the search terms are displayed in the search result (keyword OR operator).

SOUNDEX operator Also finds words that sound the same. Example: SOUNDEX jpn also finds "Japan".

STEM operator Also finds variants of the specified word. Example: STEM Film also finds "Films".

Limit search for content groups and content types The search can be restricted to the contents of specific RedDot LiveServer content groups and/or types. You can specify several groups and/or types to search through for each search query. A list of groups/types in which an alternative search is to be performed must be enclosed in round brackets. Group names must be enclosed in quotation marks if they include a character that is used as a reserved character for the search entry logic, such as "*", "-", "!", "^", "(" or ")". Note: If the names of content items and content groups are not unique within a project, you must also specify the path name of the content group within the content group hierarchy. The path components are separated by slashes (example: demo/countries/countriesxml). Examples:

group:news only finds content in the content group "news" (also searches for content items found in its subgroups).

(group:news group:"products-main") only finds content in the content group "news" or the content group "products-main" (content in child groups of "news" or "products-main" is also searched and returned).

type:XML only finds content with the content type "XML".

(type:XML type:HTML) finds content items of content type "XML" or "HTML."

(group:news type:XML) finds content items of the content group "news" or with the content type "XML."

Please note that Verity Query Language offers further possibilities including the use of the operators IN, NEAR, ACCRUE, PARAGRAPH, SENTENCE, TYPO and additional placeholders. You can use the Verity Query Language directly by submitting your query via the child element <rde-dm:query-verity>. For instructions on using this search language, please consult the description of the Verity Query Language in the Verity handbook, the English version of which is available in the RedDot LiveServer documentation directory (<RedDot Web application path>/docu/en/pdf_documents) in both PDF and HTML format.

288

DynaMent ReferencesRDB DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

RDB DynaMent

The RDB DynaMent makes it possible to exchange data with an external database via SQL. The use of this DynaMent is the simplest way of integrating external data from a relational database into a Web site. If a relational database has been declared to RedDot LiveServer, then entering an RDB DynaMent in the required XML document causes an SQL query to be submitted.

To use the RDB DynaMent, you must have configured at least one relational database correctly.

This section shows you how to perform the following actions:

Query a relational database (mode="query") using an SQL statement (select)

Update a relational database (mode="update") using an SQL statement (update, insert, delete)

Send any SQL statement to a relational database (mode="statement")

For more information about connectors for relational databases, see the Connectors documentation.

Querying Relational Databases ('query')

Purpose

In "query" mode, the RDB DynaMent is replaced at runtime by the result of an SQL query on a relational database. The SQL query must start with "select". This mode is the default setting for the RDB DynaMent.

Syntax

<rde-dm:rdb mode ="query" alias ="{connector name}" sql ="{select...; select...}" row ="[{tagname}|notag]" item-tag ="[{tagname}|notag]" maxrows ="{number} chunksize ="{number of records}" chunk ="{chunk number}"

/>




289


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the RDB DynaMent, here "query". Default setting, can be omitted.

alias Name of a connector for a relational database defined in RedDot LiveServer.

sql Database query in SQL (in accordance with the ANSI standard). The statement must start with "select", otherwise an error message will be displayed. You can specify multiple statements (separated by semicolons).

row (optional) Tag name of the XML element that surrounds each record in the result. The XML tag names of the individual data fields are derived from the column names in the database table.



If nothing is specified: The value specified for the item-tag parameter. If the row and item-tag parameters are not specified: "row" Note: The row and item-tag parameters have the same function. If both parameters are specified, only the row parameter is evaluated.

item-tag (optional) Function: See row parameter. If both parameters are specified, only the row parameter is evaluated. If nothing is specified: The value specified for the row parameter. If the row and item-tag parameters are not specified: "row"

maxrows (optional) Maximum number of hits to return. Value if nothing is specified: "0", that is, an unlimited number of hits.

Note: This parameter is independent of the setting for the maximum number of hits when testing a database connection using the appropriate dialog window in RedDot LiveServer.

chunksize (optional) Maximum number of content items that may be included in a result of the RDB DynaMent as defined by the chunksize parameter. If the number of items found is greater than chunksize, then the remaining items are displayed in the next chunk after sorting. Possible values: "1" to "500" Value if nothing is specified: "10"

chunk (optional) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. The resulting XML element of the RDB DynaMent returns the parameters previouschunk, nextchunk, lastchunk, hits, maxchunks-ca, chunk, and chunksize, which can be implemented using XSL scrolling functions. Value if nothing is specified: "1". This value is also used if the starting point of the chunk exceeds the maximum possible value.




290


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Value if nothing is specified: "result"


Result

The RDB DynaMent is either replaced by the result of the database query or an error message is output (for example, RDB alias not configured).

The results list is enclosed by an element that is specified in the tag parameter. Each individual content item is enclosed by the tag specified in the row or item-tag parameter. The parameters of the tag element (default: "result") consist of the repeated display of the parameters of the original RDB DynaMent (chunk, chunksize), augmented by the following parameters:

hits: Total number of results.

maxhits: Maximum number of hits.


lastchunk: Number of the last chunk



Error Handling

The RDB DynaMent's information, warning, and error messages begin with 9 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the "RedDot DynaMents" chapter.

Special Characters in SQL Commands

Replace certain special characters in the text of the SQL commands during entry because they are already allocated:

> with > (greater than) < with < (less than) % with % (ASCII character number 37).

291


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Querying Hotels in a Given City

<rde-dm:rdb mode="query" alias="linux-mysql" sql="select Name,Street,Phone from hotellist where city='[#destination.city#]'"

tag="destination" row="hotel"/>

The result:

<destination description="Hotel"> <hotel> <Name>Gran Hotel Rio de Janeiro</Name> <Street>Rua da Panificadora, 12</Street> <Phone>(21) 555-4252</Phone> </hotel> <hotel> <Name>Hotel Carnevale</Name> <Street>Av. Copacabana, 267</Street> <Phone>(21) 555-3412</Phone> </hotel> <hotel> <Name>Hanari Hotel</Name> <Street>Rua do Paço, 67</Street> <Phone>(21) 555-0091</Phone> </hotel> <hotel> <Name>Hotel Brasil</Name> <Street>Rua Americana</Street> <Phone>(21) 555-3736</Phone> </hotel>

</destination>

All hotels matching the value of the "city" attribute selected by the active user are displayed.

292


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Updating Relational Databases ('update')

Purpose

You can use the RDB DynaMent in "update" mode to access an external database and edit its data using SQL commands.

Syntax

<rde-dm:rdb mode ="update" alias ="{connector name}" sql ="[update..|insert..|delete..]"

/>




Parameters

mode Mode of the RDB DynaMent, here "update".


sql Database query in SQL (in accordance with the ANSI standard). The statement must start with "update", "insert", or "delete"; otherwise an error message is displayed. You can specify multiple statements (separated by semicolons).


Result

The database is updated in accordance with the SQL command. No result is returned.

Error Handling

The RDB DynaMent's information, warning, and error messages begin with 9 in the thousands' place. You can send the return codes with the default parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the "RedDot DynaMents" chapter.

293


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Examples: Inserting, Modifying, and Deleting Records

Inserting a new record:

<rde-dm:rdb mode="update" alias="linux-mysql" sql="Insert Into HotelList

(Id,Name,City)Values(230,'The Panoramic','New York');"/>

Modifying fields in a record:

<rde-dm:rdb mode="update" alias="linux-mysql" sql="Update HotelList Set

Name='The Luxury Panoramic' Where Id=230"/>

Deleting a record:

<rde-dm:rdb mode="update" alias="linux-mysql" sql="Delete From HotelList

Where id=230;"/>

294


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Sending Any SQL Statement ('statement')

Purpose

You can use the RDB DynaMent in "statement" mode to access an external database and edit its data using SQL commands. The RDB DynaMent is replaced at runtime by the result of the SQL query, if a result is returned.

Syntax

<rde-dm:rdb mode ="statement" alias ="{connector name}" sql ="{sql statement}" row ="[{tagname}|notag]" item-tag ="[{tagname}|notag]" maxrows ="{number} chunksize ="{number of records}" chunk ="{chunk number}"

/>




Simple Call

<rde-dm:rdb> mode="statement" alias="testdb" sql="(select...from...where...group by...) union (select...from...where...group by...) order by ..."

</rde-dm:rdb>

This call simply illustrates that complex SQL statements are possible in "statement" mode.

Parameters

mode Mode of the RDB DynaMent, here "statement".


sql Precisely one database query in SQL (in accordance with the ANSI standard).

295


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

row (optional) Tag name of the XML element that surrounds each record in the result. The XML tag names of the individual data fields are derived from the column names in the database table.



If nothing is specified: The value specified for the item-tag parameter. If the row and item-tag parameters are not specified: "row" Note: The row and item-tag parameters have the same function. If both parameters are specified, only the row parameter is evaluated.

item-tag (optional) Function: See row parameter. If both parameters are specified, only the row parameter is evaluated. If nothing is specified: The value specified for the row parameter. If the row and item-tag parameters are not specified: "row"

maxrows (optional) Maximum number of hits to return. Value if nothing is specified: "0", that is, an unlimited number of hits. Note: This parameter is independent of the setting for the maximum number of hits when testing a database connection using the appropriate dialog window in RedDot LiveServer.

chunksize (optional) Maximum number of content items that may be included in a result of the RDB DynaMent as defined by the chunksize parameter. If the number of items found is greater than chunksize, then the remaining items are displayed in the next chunk after sorting. Possible values: "1" to "500" Value if nothing is specified: "10"

chunk (optional) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. The resulting XML element of the RDB DynaMent returns the parameters previouschunk, nextchunk, lastchunk, hits, maxchunks-ca, chunk, and chunksize, which can be implemented using XSL scrolling functions. Value if nothing is specified: "1". This value is also used if the starting point of the chunk exceeds the maximum possible value.




Value if nothing is specified: "result"


296


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

The database query is executed. The database is updated in accordance with the SQL command or the RDB DynaMent is replaced by the result of the database query, if a result is returned.

The results list is enclosed by an element that is specified in the tag parameter. Each individual content item is enclosed by the tag specified in the row or item-tag parameter. The parameters of the tag element (default: "result") consist of the repeated display of the parameters of the original RDB DynaMent (chunk, chunksize), augmented by the following parameters:

hits: Total number of results.

maxhits: Maximum number of hits.


lastchunk: Number of the last chunk



Error Handling

The RDB DynaMent's information, warning, and error messages begin with 9 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the "RedDot DynaMents" chapter.




297

DynaMent ReferencesRedDot DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

RedDot DynaMent

The RedDot DynaMent is used in XSL style sheets to prepare content for editorial processing (compilation) in preview mode and supply it with the corresponding RedDots.

The RedDot DynaMent can only be used in combination with extensible or modifiable content items.

Below you can find out how to use the RedDot DynaMent to integrate:

An Edit RedDot to edit a text (mode="edit")

A Template RedDot to edit a template (mode="template")

Inserting Edit RedDots ('edit')

Purpose

You can use the RedDot DynaMent in "edit" mode to insert an Edit RedDot. You can use an Edit RedDot to edit a text in preview mode.

Syntax

<rde-dm:reddot mode ="edit" method ="html" alt ="{alternative text}" show ="[yes|no]"

/>




Parameters

mode Mode of the RedDot DynaMent, here "edit".

method (optional) XML tag. If no value is specified: "html"

alt (optional) Text which is shown when the Edit RedDot is displayed.

298


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

show Specifies whether or not the RedDot is displayed.

"yes": RedDot is displayed.

"no": RedDot is not displayed.

Error Handling

The RedDot DynaMent's information, warning, and error messages begin with 17 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".

<rde-dm:reddot method="html" alt="Click here to edit the content"

mode="edit"/>

Inserts an Edit RedDot

Inserting Template RedDots ('template')

Purpose

You can use the RedDot DynaMent in "template" mode to insert an Template RedDot. You can use a Template RedDot to edit a content item's template (style sheet) directly in preview mode.

Syntax

<rde-dm:reddot mode ="template" method ="html" alt ="{alternative text}" show ="[yes|no]"

/>




299


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the RedDot DynaMent, here "template".

method (optional) XML tag. If no value is specified: "html"

alt (optional) Text which is shown when the Template RedDot is displayed.

show Specifies whether or not the RedDot is displayed.

"yes": RedDot is displayed.

"no": RedDot is not displayed.

Error Handling

The RedDot DynaMent's information, warning, and error messages begin with 17 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".

<rde-dm:reddot method="html" alt="Click here to edit the style sheet hs-

cont-news" mode="template"/>

Inserts an Template RedDot

300

DynaMent ReferencesReference DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reference DynaMent

The Reference DynaMent contains functions for various objects that are called by a reference.


Creating content references based on various content properties. Content references that you have created can be transformed into links using an XSL style sheet, or can simply serve to check content properties.

Setting the validity of entries in the object cache (mode="set-scope"). Note: This mode is deprecated and should no longer be used. Instead, use the "set-scope" mode of the Cache DynaMent.

Editing content names of content items in the object cache (mode="set-cache-id"). Note: This mode is deprecated and should no longer be used. Instead, use the "set-id" mode of the Cache DynaMent.

Processing or undoing file uploads and multipart request parameters (mode="read-multipart"). This allows you to optimize memory use when reading large upload files.

Integrating Content References

Purpose

You can use the Reference DynaMent to integrate content references. At runtime, a reference is replaced by the result of the content reference (for example image, PDF file). The associated XSL document must contain the corresponding Image or Link DynaMent in this case.

Along with the Reference DynaMent, the referenced content is checked to see whether it already exists in the LiveServer Repository. Optionally, you can also check to see whether the content meets any other DynaMent condition. You can have the result of the check output as a return code in the standard parameter result-attribute, where it can be used further (see "Error Handling" below).

If the referenced content does not exist or does not meet the specified conditions, nothing is returned. Among other things, this prevents dead links from being generated.

Syntax

<rde-dm:reference project ="{projectname}" content ="{projectname:contentname}" text ="{text}" validfrom ="{yyyy.mm.dd hh:mm:ss}" validto ="{yyyy.mm.dd hh:mm:ss}"

locale ="{locale string}" locale-policy ="[default|none|any]"

mode ="[exists|validperiod|constraints|data| localizeddata|group|grouphierarchically|

attributes|localizedattributes]" group ="{content group}"

path ="{attribute name}"

/>

301


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Parameters

project (optional) Old notation that should no longer be used. Name of the project, valid for content if the project specification is missing for this entry.

content Name of the referenced content. The syntax is "projectname:contentname". If no project is specified, then the project entered under project is accessed. If this also contains no project specification, then the current project is accessed. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

text (optional) Text specified as the reference text in the DynaMent result (for example, <text>This is the link text</text>). Not required if the Reference DynaMent does not add anything, but only checks whether content is available.

validfrom (optional) Specifies the date and time from which the reference is valid (format: yyy.mm.dd, hh:mm:ss). You do not need to specify seconds. If the values specified are incorrect, the reference is invalid and the reference content is not inserted. If no value is specified: The reference is valid immediately and until validto.

validto (optional) Specifies the date and time until which the reference is valid (format: yyy.mm.dd, hh:mm:ss). You do not need to specify seconds. If the values specified are incorrect, the reference is invalid and the reference content is not inserted. If no value is specified: The reference is valid indefinitely from validfrom. If no values are specified for validfrom or validto: The reference is valid immediately and indefinitely.

locale (optional) Language of the referenced content. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. If there is no content data for the selected language in the repository, a replacement language is determined in accordance with the locale policy. This is usually the default project language. If no value is specified: User language of the requesting session.

302


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

locale-policy (optional) Only for mode="localizeddata": Locale policy to access content data: If a content item has no data for the language variant determined by the locale parameter, the data for a different language variant is read. Possible settings:

"none": If content data is not available in the language you require, no data from any other language is read.

"default": If content data is not available in the language you require, the data for the project default language specified in the project settings is read. If no data is available there either, the default language specified in the system configuration (key: reddot.locale.default) is read. If no data is available in this language, nothing is read.

"any": If no content data is available in the language you require, the data for the project default language is read. If no data is available there either, the default language specified in the system configuration (key: reddot.locale.default) is read. If no data is available in that language, the system searches for and reads the first available content data in one of the languages, following the order of languages specified in the project settings.

If no value is specified: "default"

mode (optional) Specifies one or multiple constraints to be checked for your content. To specify several modes simultaneously, separate them with semicolons or commas.

"exists": Checks whether a content item of that name exists.

"validperiod": Checks whether a content item of that name exists, and whether its period of validity means that it can be called at any time.

"constraints": Checks whether a content item of that name exists, and whether its current content constraints are met by the active session.

"data": Checks whether a content item of that name exists and contains data for at least one language.

"localizeddata": Checks whether a content item of that name exists, and whether it contains data for the language specified in the "locale" parameter, or for the language requested in the current session.

"group": Checks whether a content item of that name exists and belongs to a group of the name specified in the "group" parameter. This mode only allows you to check the existence of content items that have been assigned to a group.

"grouphierarchically": Checks whether a content item of that name exists and belongs to a group of the name specified in the "group" parameter, or one of its subgroups. This mode only allows you to check the existence of content items that have been assigned to a group.

"attributes": Checks whether a content item has attributes.

"localizedattributes": Checks whether a content item has attributes, and whether at least one of these attributes has a value for the language specified in the locale parameter (or for the user's language in the requesting session).

If no value is specified: "exists;validperiod;constraints;localizeddata"

303


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

group (optional) Only for mode="group" or "grouphierarchically"; required in this case: Value of the path name of the content group within the content group hierarchy. The path components are separated by slashes (example: demo/countries/countriesxml).

path (optional) Only for mode="attributes" or "localizedattributes": Name of an attribute. If attributes are organized in a hierarchy, the entire attribute path must be specified (separated by periods, for example: "track.news"). The check is limited to this attribute and its child attributes. If no value is specified: The check is not limited.




If no value is specified: "reference"

Result

This results in the Reference DynaMent being replaced by the reference result. If the referenced content does not exist, or one of the constraints is not met, no content is inserted. The result of the check can be output as a return code in standard parameter "result-attribute".

Error handling

The Reference DynaMent's information, warning, and error messages begin with 14 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:



14203 The content item was not found.

14213 Content is currently not valid.

14223 The session does not meet the constraints placed on the content

14233 The content item has no content data.

14243 The content item does not have the matching content data (for the requesting session).

14253 The content item is not located in the specified (fully-qualified) group.

14263 The content item is neither in the specified (fully-qualified) group nor one of its subgroups.

14273 Content item has no attributes

14283 Content item has no matching attributes (for the requesting session)

304


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

XML file with Reference DynaMent: ... <linklist> <rde-dm:reference content="html-demo:news.htm" text="Link to existing content"/>

</linklist>

Associated XSL file with Link DynaMent: ... <xsl:template match="linklist/reference"> <rde-dm:link>

<xsl:value-of select="."/> </rde-dm:link> </xsl:template>

...

Result of the Reference DynaMent in XML: ... <linklist rde-rd:project="html-demo" rde-rd:content="Reference.xml" rde-rd:leasingtime="600000" rde-rd:locale="en">

<reference rde-rd:project="html-demo" rde-rd:content="news.htm">Link to

existing content </reference>

</linklist>

You use the Reference DynaMent to check if a content item exists and whether it meets certain constraints:

<rde-dm:reference content="index.htm" mode="group" group="html-content" result-attribute="result"/>

<rde-dm:attribute mode="read" attribute="result" source="request"/>

In the example above, a check is made as to whether the content with the name "index.htm" exits and is contained in the group "html-content." The result is returned as a value that is stored in the "result" attribute. You can use the Attribute DynaMent in "read" mode to read the value. Then other steps can be initiated based on whether the content item meets certain constraints.

<rde-dm:attribute mode="condition" tag="notag" attribute="result" source="request" op="eq" value="0">

...

305


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Setting the Validity of Entries in the Object Cache ('set-scope')

The Reference DynaMent in "set-scope" mode lets you change the validity of content items in the object cache. Content items can be saved in the object cache longer than the duration of the current request. This is especially useful for temporary items such as attachments or file uploads.

Attachments received via a Web service are stored as temporary content in the object cache; initially they are only valid for one request. To allow processing of an attachment in later requests, its validity within the session must be extended.

Note: This mode is deprecated and should no longer be used. Instead, use the "set-scope" mode of the Cache DynaMent.

See also:

Cache DynaMent (Page 97)Setting the Validity of Entries in the Object Cache ('set-scope') (Page 97)

Syntax

<rde-dm:reference mode ="set-scope" content ="{project:content name}" project ="{project}" scope ="{session|request|server}"

timeout ="{timeout in seconds}"

/>




Parameters

mode Mode of the Reference DynaMent, here: "set-scope".

content Name of the temporary content in the object cache that is referenced. You can also specify a project name, separating it with a colon (project name:content name). Note: If no project with the specified name exists, the entire entry is interpreted as the content name. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

You need to specify a project, because this information is part of the key used to store content in the object cache.

306


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

project (optional) Name of the project containing the temporary content. If nothing is specified: Project name specified in the content parameter. If no project is specified there, the project where the Reference DynaMent is located is used.

scope (optional) Validity period of the temporary content:

"request": The temporary content is valid throughout a request.

"session": The temporary content is valid throughout a session.

"server": The temporary content is valid as long as the server is running. Note: Entries with this setting are not removed from the object cache until the server is shut down and place a lasting load on memory.

If nothing is specified: "session"

timeout (optional) Maximum period of validity for a temporary content item in seconds.


Result

No result is returned. The validity of the content item specified is changed.

Error Handling

The Reference DynaMent's information, warning, and error messages begin with 14 in the thousands' place. You can send the return codes with the default parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:

See also:




307


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Editing Content Names in the Object Cache ('set-cache-id')

The Reference DynaMent in "set-cache-id" mode lets you rename content items in the object cache. This is particularly useful if content names have been defined externally and are not suitable to be used on the Web site. For example, it is useful for attachments that were loaded into the object cache using a Web service, or when uploading a multipart request.

Note: This mode is deprecated and should no longer be used. Instead, use the "set-id" mode of the Cache DynaMent.

See also:

Cache DynaMent (Page 97)Renaming Entries in the Object Cache ('set-id') (Page 100)

Syntax

<rde-dm:reference mode ="set-cache-id" content ="{project:content name}" project ="{project}" cache-id ="{cache-id}"

replace ="[true|false]"

/>




Simple call

<rde-dm:reference mode="set-cache-id" content="[#context:attachment#]"

cache-id="attachment.txt" />

The cache entry of an attachment is given a new name in the object cache.

Parameters

mode Mode of the Reference DynaMent, here: "set-cache-id".

content Name of the content item in the object cache. The content name is a component of the content key in the object cache, under which content is created. You can also specify a project name, separating it with a colon (project name:content name). Note: If no project with the specified name exists, the value is interpreted as the content name. If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml).

308


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

You need to specify a project, because this information is part of the key used to store content in the object cache.

project (optional) Name of the project containing the temporary content. If nothing is specified: Project name specified in the content parameter. If no project is specified there, the project where the Reference DynaMent is located is used.

cache-id New name of the temporary content item in the object cache. The content name is the last component of the content key in the object cache, under which content is created.

replace (optional) Determines whether to replace a content item with the same name in the object cache with the new content item, or to abort the process:

"true": A content item with the same name will be replaced.

"false": A content item with the same name will not be replaced.

Value if nothing is specified: "true"

Result

The name of the specified content in the object cache is modified. In persistent repositories, the content name is not modified.

Error Handling

The Reference DynaMent's information, warning, and error messages begin with 14 in the thousands' place. You can send the return codes with the default parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:

See also:



14275 The cache entry already exists. Cache ID has not been renamed.

309


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Processing Multipart Requests ('read-multipart')

The Reference DynaMent in "read-multipart" mode lets you control the processing of file uploads and of parameters from multipart requests. This allows you to optimize memory use when reading large upload files.

You can also use the <rde-rd:import> child element to add metadata to a content item.

Syntax

<rde-dm:reference mode ="read-multipart" op ="[full|next-field|discard]" attachment-attribute ="{attribute name}" attachment-name-prefix ="{prefix name}" attachment-size ="{size in kb}" max-attachments ="{number}" buffer-stream ="[discard|keep]" cache-id ="{cache-id}" > <rde-rd:import> ...metadata... </rde-rd:import>

</rde-dm:reference>




Parameters

mode Mode of the Reference DynaMent, here: "read-multipart".

op (optional) Way in which a multipart request is processed further. The following options are available:

"full": The multipart request is fully processed.

"next-field": Only the next entry in the multipart request is processed.

"discard": The multipart request is discarded. The other parameters of the Reference DynaMent are ignored (attachment-attribute, attachment-name-prefix, attachment-size, max-attachments, and buffer-stream).

Value if nothing is specified: "full"

310


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

attachment-attribute (optional) Name of a request attribute into which information about attachments in a multipart request will be written. If nothing is specified: All attachments in the multipart request are discarded; only the remaining form fields are made available as Request attributes.

attachment-name-prefix (optional) Prefix for the content IDs of the attachments obtained, to ensure the content IDs are unique.

attachment-size (optional) Maximum attachment size in KB. Larger attachments are not read. Value if nothing is specified: "10000"

max-attachments (optional) Maximum number of attachments in the multipart request that are read. All other attachments are ignored here; they can be read later, for example, with additional Reference DynaMent calls. Value if nothing is specified: "1"

buffer-stream (optional) Specification of whether the multipart request should be temporarily saved for use after its initial call.

"discard": The multipart request is discarded after processing and cannot be read later.

"keep": The multipart request is temporarily saved and can be read later. This can take up a lot of memory, particularly if a multipart request involves very large files; only use this setting when required.

Value if nothing is specified: "discard"

cache-id (optional) Creates a cache entry (scope="request") in the object cache. Specify a content name. This will be the last element of the content key used to store the read content (as RedDot LiveServer content) in the object cache. The content item contains the content data in the default language of the project to which the content is assigned. The cache-id is used as name for the content in RedDot LiveServer.



Child Elements

A child element called <rde-rd:import> is available in "read-multipart" mode for assigning metadata to content.


311


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

No result is returned. File uploads and parameters of multipart requests are processed further as specified.

Error Handling

The Reference DynaMent's information, warning, and error messages begin with 14 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:

Mapping MIME Types to RedDot LiveServer Content Types

When you import content to the LiveServer Repository, the MIME type and file extension of the content you are importing are automatically mapped to a RedDot LiveServer content type. This requires that the MIME type and the mapping have been declared to RedDot LiveServer. Both are read from the mimetype.txt file (located in the <RedDot Web application path>/WEB-INF/etc/ directory), which contains a wide range of mappings. If a MIME type is not listed in the file, you can add it.

If a MIME type is missing, the system attempts to identify the content type in RedDot LiveServer from the media type information given. A MIME type consists of the following information: media type and a sub type, separated by a forward slash (example: text/html).

See also:

Integrating Internal or External Content (Page 160)



-14501 Processing of the multipart attachment has failed.

-14503 No access to Weblet request

-14504 The session does not meet the constraints placed on the content

-14505 Unknown operator for "read-multipart" mode

-14506 Unknown value in the buffer-stream attribute

14264 Attachment too large: size {file size} > attachment-size

14265 The current request is not a multipart request

312

DynaMent ReferencesReporting DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reporting DynaMent

The Reporting DynaMent is only available with the appropriate license, which activates the reporting connectors and the Reporting DynaMent.

This DynaMent lets you control the recording of data used in reports and query data for live reports.


Reading browser properties and passing them to RedDot LiveServer (mode="browser")

Using the acknowledgement mechanism (mode="acknowledge")

Requesting data for live reports and presenting them in XML format or as a diagram (mode="report")

For more information about reporting connectors, see the Connectors documentation.

Reading Browser Properties ('browser')

Purpose

In "browser" mode, the Reporting DynaMent lets you determine the properties of the requesting browser.

The following requirements must be met in the Tracking engine -> Browser properties area of the relevant reporting connector:

The Record browser properties check box is selected.

The name of the pixel image is specified.

Check boxes for individual browser properties are selected.

Once the browser properties to be recorded have been selected, the matching JavaScript has been generated using the Generate JavaScript button.

Syntax

<rde-dm:reporting mode ="browser"

connector ="{connector name}" />




313


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple call

<rde-dm:reporting mode="browser" connector="Test" />

Parameters

mode Mode of the Reporting DynaMent, here "browser".

connector Name of the reporting connector to be used, as defined in RedDot LiveServer.

Notes

The Reporting DynaMent must be added to the header section of an HTML page.

Results

The Reporting DynaMent is replaced by a JavaScript that has been generated in the relevant reporting connector. The JavaScript reads the browser properties.

Error handling

The Reporting DynaMent's information, warning, and error messages begin with 28 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".

Using Acknowledgement Mechanism ('acknowledge')

Purpose

In "acknowledge" mode of the Reporting DynaMent, an acknowledgement mechanism tells you whether a page has been requested either by a specific browser, or automatically by a search engine or a Web crawler.

The following requirements must be met in the Tracking engine area of the relevant reporting connector:

The Acknowledge delivery of pages check box is selected

Name of a pixel image for confirmation is specified

Also, to determine whether JavaScript has been enabled in the browser, the Reporting DynaMent has to be used in "acknowledge" mode.

314


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:reporting mode ="acknowledge"

connector ="{connector name}" />




Simple call

<rde-dm:reporting mode="acknowledge" connector="Test" />

Parameters

mode Mode of the Reporting DynaMent, here "acknowledge".


Notes

The Reporting DynaMent must be added to the body section of an HTML page. There can only be one pixel image per RedDot LiveServer page to ensure accurate results.

Results

The Reporting DynaMent is replaced by a JavaScript and a section for <noscript> HTML tags. This ensures the acknowledgement mechanism will work, whether or not JavaScript is enabled in the browser. With JavaScript enabled, the script requests the acknowledgement pixel image from RedDot LiveServer. With JavaScript disabled, an image tag for the acknowledgement pixel image is inserted in the HTML page, and the browser requests the pixel image from RedDot LiveServer. Both confirm that the page has really been requested by a browser.

Error handling

The Reporting DynaMent's information, warning, and error messages begin with 28 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".

315


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Creating Live Reports ('report')

Function

With the Reporting DynaMent in "report" mode, you can do the following:

Requesting data for reports from the tracking database SQL queries have been supplied for using the reporting connector for a series of standard reports. You can create additional SQL queries for reports that you define yourself. The result is an XML structure that you can render with XSL or present with the diagram engine.

Presenting XML data as diagrams If the chart-type parameter selects a diagram type, the Reporting DynaMent will use the BIRT diagram engine to make diagrams. The data source can be data for reports, data from other databases that was queried by the RDB DynaMent, or data from XML content.

The diagram engine creates image files for the diagrams that you can show in the current session or save as content in the LiveServer Repository for later use or for documentation. For more information on different types of diagrams and their parameters, see the Diagram Types and Parameters section below. You can assemble several diagrams on one page as compact information for the user.

Example for Charts in the demo Project

You can return three live reports as diagrams by using the user statistics link on the start page of the supplied demo example project. The first diagram shows the number of visits of the current user as a bar chart. The second diagram shows the absolute number of all visits as a bar chart; the third one gives the percentage of visits as a pie chart. The first call by the first user may take a few seconds, as the diagram engine is initialized once on that occasion.

316


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:reporting mode ="report" connector ="{connector name}" name ="{report name}" chart-type ="{chart type}" content ="{content name}" project ="{project name}" cache-id-attribute ="{attribute name}"

cache-id ="{cache id}" >

<rde-dm:param name="{report parameter name-1}"> {param-1 value, optionally in CDATA} </rde-dm:param> ... <rde-dm:param name="{report parameter name-n}"> {param-n value, optionally in CDATA}

</rde-dm:param>

<rde-dm:constraint> {constraint expression}


</rde-dm:reporting>




Simple Call

<rde-dm:reporting mode="report" connector="Reporting" name="Test" />

The above call starts a user-defined report called Test. You have to specify additional parameters when you call a standard report (see the example below).

Parameters

mode Mode of the Reporting DynaMent, here "report".


name (alternative to project and content parameters) Name of the live report to be accessed, as defined in RedDot LiveServer (user-defined or standard report). For a list of the standard reports, see the next section (and the link below).

chart-type (optional) Specifies a diagram type. Possible values:

"rdeDefaultBarChartWithDepth": Two-dimensional bar chart with depth

317


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"rdeDefaultBarChart": Two-dimensional bar chart

"rdeDefaultPieChartWithDepth": Two-dimensional pie chart with depth

"rdeDefaultPieChart": Two-dimensional pie chart

"rdeDefaultLineChart": Two-dimensional line chart

"{diagram name}": Additionally defined BIRT diagram See also the section Modifying BIRT Diagrams for Live Reports.

When a diagram type has been specified, the Reporting DynaMent generates an HTML fragment that contains an Image element for the diagram that is also generated. These two generated content items are saved in the object cache with the scope="session". The names of the content items can be read with the cache-id-attribute parameter. The generated content items can be saved in the LiveServer Repository (see the example below). If nothing is specified: The result of the DynaMent is in XML format, and no diagram is generated.

content (if used together with project, this is an alternative to the name parameter.) If no live report is specified with the name parameter: Defining XML content of the LiveServer Repository as a data source for a diagram. Should only be used when specifying the chart-type parameter. The content must match the following format:

<report-data> <rows> <row> <{name column 1}>{value 1 column 1}</{name column 1}> <{name column 2}>{value 1 column 2}</{name column 2}> <{name column 3}>{value 1 column 3}</{name column 3}> <...>...</...> </row> <row> <{name column 1}>{value 2 column 1}</{name column 1}> <{name column 2}>{value 2 column 2}</{name column 2}> <{name column 3}>{value 2 column 3}</{name column 3}> <...>...</...> </row> ...

</rows>

</report-data>

project (if used together with content, this is an alternative to the name parameter.) Specifies the project for the XML content of the content parameter. Should only be used when specifying the chart-type parameter. If nothing is specified: The name of the project in which the DynaMent is located.

cache-id-attribute (optional; should only be used when chart-type parameter has been specified.) Name of an attribute with optional additional source specification (default: request). Let us assume the Reporting DynaMent has the chart-type parameter specified. Once the Reporting DynaMent is executed, the values for the specified attribute are the names of the content items that, as the result of the DynaMent, make up the generated report:

318


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

First value: Content name for the HTML fragment that contains the diagram as an img element. The name is created by following this pattern: rdeReportHtml{random-id}.htm. This content name can be used as the call parameter cache-id for further calls of the Reporting DynaMent (see the description of the cache-id parameter).

Second value: Content name of the BLOB content for the actual diagram. The name is created by following this pattern: rdeReportImg{random-id}.png.

You can use the Content DynaMent in "import" mode to save the content items of a generated report in the LiveServer Repository. You can view them later without having to create them again (see example below). Note: When you are reusing generated content as results by specifying the cache-id parameter, content names are not returned in the specified attribute.

cache-id (optional; should only be used when chart-type parameter has been specified.) Name of the content item of the HTML fragment that is to be used as the result instead of the HTML fragment to be generated. Background: When the chart-type parameter is specified, the Reporting DynaMent should generate a diagram and return an HTML fragment with reference to this diagram as result. In a project, situations arise in which the same diagram should be reused, but it is not clear whether it has already been generated. In this case, use the cache-id parameter to avoid the repeated generation of the diagram. You can enter the first value of the attribute that is returned by the cache-id-attribute parameter as the value of the cache-id parameter. If the content specified in the cache-id parameter does not exist, the Reporting DynaMent is executed according to the parameters set.

cachingtime (optional) Caching time in minutes of the created report in the object cache. All generated content that comprise the report are marked as cannot be restored. If no <rde-dm:constraint> child element is defined, the content is stored in the object cache with the Session retention period. Thus the reports created remain stored in the object cache until the end of the LiveServer session and use memory capacity. If an <rde-dm:constraint> is given, the corresponding constraint and the specified caching time are given to the content in the object cache. By using the Cache DynaMent in "notify" mode, you can clear the cache entries from the cache earlier. Value if nothing is specified: "60"

Child Elements

There are some additional optional child elements for the Reporting DynaMent. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-dm:param> (optional) Within this child element, parameters and their values are specified for various purposes:

Here you have to specify the necessary call parameters for the predefined standard report that you defined in the name parameter. The parameters are evaluated when the Reporting DynaMent is called. There is a section with a list of the standard reports and their parameters.

In the same way, you can specify optional parameters of a diagram type here that you defined in the chart-type parameter. With these parameters, you can modify the design of the diagram and the legend. There is a section with a list of the predefined diagram types and their parameters.

319


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

When using the chart-type parameter, there are two optional parameters for use with user-defined live reports with which you can assign the columns of the report to the x and y axes:

"datamapping-x" and "datamapping-y": Entry of the column name from the result of the database query. If nothing is specified, the value of the first column is used for the x axis and the value of the second column for the y axis.

<rde-dm:constraint> (optional) For specifying a constraint. Access to the generated reports is only allowed when the constraint is met. The constraint is added as a content constraint to the generated content items that comprise the generated report. Value if nothing is specified: The report is only visible for the session in which it was generated.

For the exact syntax of this child element, see the description of the Attribute DynaMent in "condition" mode.

Result

The Reporting DynaMent executes the specified report, which usually contains an SQL query. It returns either an XML file that can be rendered or, when a chart-type was specified, an HTML fragment with an Image element for a diagram.

Error Handling

The Reporting DynaMent's information, warning, and error messages begin with 28 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), other messages are possible.

For more information about the names and parameters of the standard reports and about different types of diagrams and their parameters, see the separate sections.

See also:

Predefined Standard Reports (Page 328)Diagram Types and Parameters (Page 334)

For more information about reporting connectors, see the Connectors documentation.

You can find information on how to use the <rde-dm:constraint> child element in a separate section.

See also:

Checking Constraints for Attributes ('condition') (Page 61)


-28601 Invalid RDB connector

-28602 Error from the RDB DynaMent

-28701 Chart engine not initialized

320


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Customizing BIRT Diagrams for Live Reports

The integrated diagram engine BIRT supports the graphic display of the live reports as a diagram. For the standard diagrams available, templates are used comprising so called BIRT report design files. You can find the files here: <RedDot Web application path>\WEB-INF\etc\reporting\reports. If the parameters available through the Reporting DynaMent are not sufficient, you can customize layout and display of the files by using the BIRT Report Designer Version 2.2.2 (http://download.eclipse.org/birt/downloads/).

You can find a report_names.properties properties file in the WEB-INF\etc\reporting directory with which you assign the names of the BIRT report design files to the logical names used in the Reporting DynaMent. If you want to create and use additional files based on the templates, use the properties file to assign logical names to them, too. Now you can access these names in the DynaMent.

Example: Requesting Standard Report

<rde-dm:reporting mode="report" connector="Reporting" name="page-impressions-sum-of-a-day-per-site" > <rde-dm:param name="year">2007</rde-dm:param> <rde-dm:param name="month">1</rde-dm:param> <rde-dm:param name="day">1</rde-dm:param> <rde-dm:param name="site">mysite</rde-dm:param>

</rde-dm:reporting>

This call requests the total of all page requests of the mysite Web site on January 1, 2007.

321


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Requesting Custom Report with Bar Chart and Parameter Information

<rde-dm:reporting mode="report" connector="Test" name="my_report" report-tag="dm-report" chart-type="rdeDefaultBarChartWithDepth"> <rde-dm:param name="month">10</rde-dm:param>

<rde-dm:param name="year">2007</rde-dm:param> <rde-dm:param name="site">mysite</rde-dm:param>

<rde-dm:param name="datamapping-x">day</rde-dm:param>

<rde-dm:param name="datamapping-y">page_impressions</rde-dm:param>

<rde-dm:param name="chartHideAxes">false</rde-dm:param> <rde-dm:param name="chartWidth">400</rde-dm:param> <rde-dm:param name="chartHeight">300</rde-dm:param> <rde-dm:param name="chartLegendVisible">true</rde-dm:param> <rde-dm:param name="chartLegendTitle">My Legend...</rde-dm:param>

</rde-dm:reporting>

With this call, a custom report is requested and shown as a bar chart. With the datamapping-x and datamapping-y parameters, columns from the result of the database query are assigned to the axes. By defining further parameters, the diagram and the legend are customized.

322


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Requesting Standard Report with Line Chart

Reporting DynaMent:

<rde-dm:reporting mode="report" connector="test" name="visits-per-site-per-hour" chart-type="rdeDefaultLineChart"> <rde-dm:param name="year">2007</rde-dm:param> <rde-dm:param name="month">5</rde-dm:param> <rde-dm:param name="day">2</rde-dm:param> <rde-dm:param name="year">2007</rde-dm:param>

<rde-dm:param name="site">html-demo</rde-dm:param>

<rde-dm:param name="chartTitle">Visits per hour - 2007/05/02</rde-dm:param>

</rde-dm:reporting>

This call requests the visits per hour of the html-demo Web site for May 2, 2007, and shows them as a line chart.

323


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Requesting Standard Report with Bar Chart

Reporting DynaMent:

<rde-dm:reporting mode="report" connector="test" name="page-impressions-per-site-per-day" chart-type="rdeDefaultBarChart"> <rde-dm:param name="month">5</rde-dm:param> <rde-dm:param name="year">2007</rde-dm:param>


<rde-dm:param name="chartTitle">Page Impressions - 2007/05</rde-dm:param> <rde-dm:param name="chartFontSize">12</rde-dm:param> <rde-dm:param name="chartFont">Arial</rde-dm:param> <rde-dm:param name="chartWidth">500</rde-dm:param> <rde-dm:param name="chartHeight">300</rde-dm:param> <rde-dm:param name="chartAxisLabelFontSize">8</rde-dm:param> <rde-dm:param name="chartXAxisStep">1</rde-dm:param> <rde-dm:param name="chartXAxisStagger">true</rde-dm:param> <rde-dm:param name="chartLegendVisible">true</rde-dm:param> <rde-dm:param name="chartLegendTitle">Page Impressions</rde-dm:param> <rde-dm:param name="chartXAxisTitle">Day</rde-dm:param> <rde-dm:param name="chartYAxisTitle">Hits</rde-dm:param>

</rde-dm:reporting>

This call requests the page impressions per day of the html-demo Web site for the month of May, 2007, and shows them as a bar chart. The diagram and the legend were customized by using the <rde-dm:param> child elements.

324


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: XML Content as Data Source, Output as Pie Chart

XML content: XML content is expected by RedDot LiveServer as data source for a diagram in the form specified. You can assign your own names for the child elements of the <row> elements. All <row> elements need to contain child elements with identical names in identical order. The sample-data.xml content used looks as follows:

<report-data> <rows>

<row> <category>index</category> <level>4</level>

</row> <row>

<category>news</category> <level>1</level>

</row> <row>

<category>magazine</category> <level>1</level>

</row> <row>

<category>shop</category> <level>1</level>

</row> </rows>

</report-data>

Reporting DynaMent:

<rde-dm:reporting mode="report" connector="test" content="sample-data.xml" chart-type="rdeDefaultPieChartWithDepth"> <rde-dm:param name="chartLegendVisible">true</rde-dm:param> <rde-dm:param name="chartLegendPosition">insideTopRight</rde-dm:param> <rde-dm:param name="chartLegendTitle">hits / column</rde-dm:param> <rde-dm:param name="chartSeriesLabelPosition">inside</rde-dm:param> <rde-dm:param name="chartXAxisTitle">Site</rde-dm:param> <rde-dm:param name="chartYAxisTitle">Hits</rde-dm:param> <rde-dm:param name="chartTitle">all users</rde-dm:param> <rde-dm:param name="chartTitleFontSize">14</rde-dm:param> <rde-dm:param name="chartFont">Arial</rde-dm:param> <rde-dm:param name="chartHeight">200</rde-dm:param> <rde-dm:param name="chartBackgroundColor">#ffffff</rde-dm:param>

</rde-dm:reporting>

325


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

XML content is specified in the content parameter. This call requests the total visits of all users for a Web site and shows them as a percentage in a pie chart.

Example: Saving Content by Using Content DynaMent

You can also store diagrams that were created with the Reporting DynaMent in the LiveServer Repository. In this way, diagrams once generated can be reused later without having to be regenerated. This is especially useful for reports about past time periods.

When the chart-type parameter is set, the Reporting DynaMent generates both the diagram as a content item of the type BLOB in RedDot LiveServer and an HTML fragment that references the diagram with an img element. With the following example, you can store both the HTML fragment and the diagram in the LiveServer Repository.

Requirements:

First, the call of the Reporting DynaMent with the parameters chart-type="..." and cache-id-attribute="cacheId" for reading the names of the generated content.

Import job Import Report Contents as the prerequisite for the Content DynaMent mode="import". The import job has two import definitions: Report HTML Content for content of the type HTML and Report BLOB Content for content of the type BLOB.

The example follows this procedure: (1) Defining the access constraint (rights) for the content to be saved (2) Reading the names of the generated content in a loop using the value of the request:cacheId attribute (3) Selecting the import definition, first content: HTML type, other: BLOB type (4) Storing in the LiveServer Repository

 <rde-dm:attribute mode="write" attribute="request:myConstraint" value="reportLevel gt 2"/>  <rde-dm:attribute mode="write" attribute="request:loop" value="0"/> <rde-dm:attribute mode="for-each" attribute="request:cacheId"

326


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

alias="reportContentName" > <rde-dm:attribute mode="write" attribute="request:loop" op="increase" />  <rde-dm:attribute mode="condition" attribute="request:loop" op="eq" value="1" >

<rde-dm:if> <rde-dm:attribute mode="write"

attribute="request:myImportDefinition" value="Report HTML Content"/> </rde-dm:if>

<rde-dm:else> <rde-dm:attribute mode="write"

attribute="request:myImportDefinition" value="Report BLOB Content"/> </rde-dm:else> </rde-dm:attribute>  <rde-dm:content mode="import" content="[#context:reportContentName#]" ref-type="named" ref="[#context:reportContentName#]" importtask="Import Report Contents"

importdef="[#request:myImportDefinition#]" report-tag="dm-report" >

<rde-rd:import> <constraints> <constraint mode="expression">

[#request:myConstraint#] </constraint>

</constraints> </rde-rd:import>

</rde-dm:content>

</rde-dm:attribute>

327


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Predefined Standard Reports

This section contains a list of the standard reports provided by RedDot for consolidated reporting data. You can use the Reporting DynaMent in "report" mode to access the name by using the name parameter. By using the rde-dm:param child element you can access the report parameters. The reports can be returned and displayed as diagrams (see example below).

Page impressions on the selected day (Web site):

Name: page-impressions-sum-of-a-day-per-site

Description: Total number of all page impressions of a Web site on a selected day

Parameters:

year

month

day

site (value of the Web site field from a reporting connector)

Page impressions during the selected month (Web site):

Name: page-impressions-sum-of-a-month-per-site

Description: Total number of all page impressions of a Web site during the selected month

Parameters:

year

month


Page impressions during the selected year (Web site):

Name: page-impressions-sum-of-a-year-per-site

Description: Total number of all page impressions of a Web site during the selected year

Parameters:

year


Visits on the selected day (Web site):

Name: visits-sum-of-a-day-per-site

Description: Total number of all visits to a Web site on a selected day

Parameters:

year

month

day


328


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Visits of a selected month (Web site):

Name: visits-sum-of-a-month-per-site

Description: Total number of all visits to a Web site for a selected month

Parameters:

year

month


Visits during the selected year (Web site):

Name: visits-sum-of-a-year-per-site

Description: Total number of all visits to a Web site during the selected year

Parameters:

year


Page impressions per day for a Web site:

Name: page-impressions-per-site-per-day

Description: Total number of page impressions for each day of a selected month

Parameters:

year

month


Page impressions per month for a Web site:

Name: page-impressions-per-site-per-month

Description: Total number of page impressions for each month of a selected year

Parameters:

year


Page impressions per hour for a Web site:

Name: page-impressions-per-site-per-hour

Description: Total number of all page impressions of a Web site for each hour of a selected day

Parameters:

year

month

day


329


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Visits per day to a Web site:

Name: visits-per-site-per-day

Description: Total number of visits for each day of a selected month

Parameters:

year

month


Visits per month to a Web site:

Name: visits-per-site-per-month

Description: Total number of visits for each month of a selected year

Parameters:

year


Visits per hour to a Web site:

Name: visits-per-site-per-hour

Description: Total number of visits for each hour of a selected day

Parameters:

year

month

day


Page impressions per hour for a content item:

Name: page-impressions-per-hour-per-content

Description: Total number of all page impressions for a content item in an hour

Parameters:

year

month

day

hour

project (project of the content item)

content (content item)


330


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Page impressions per day for a content item:

Name: page-impressions-per-day-per-content

Description: Total number of all page impressions for a content item on a selected day

Parameters:

year

month

day




Page impressions per month for a content item:

Name: page-impressions-per-month-per-content

Description: Total number of all page impressions for a content item in a month

Parameters:

year

month




Page impressions per year for a content item:

Name: page-impressions-per-year-per-content

Description: Total number of all page impressions for a content item in a year

Parameters:

year




331


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Requesting Standard Reports

<rde-dm:reporting mode="report" connector="Reporting" name="page-impressions-sum-of-a-day-per-site" > <rde-dm:param name="year">2007</rde-dm:param> <rde-dm:param name="month">1</rde-dm:param> <rde-dm:param name="day">1</rde-dm:param> <rde-dm:param name="site">mysite</rde-dm:param>

</rde-dm:reporting>

This call requests the total of all page requests of the mysite Web site on January 1, 2007.

332


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Requesting Standard Reports with Line Charts

Reporting DynaMent:

<rde-dm:reporting mode="report" connector="test" name="visits-per-site-per-hour" chart-type="rdeDefaultLineChart"> <rde-dm:param name="year">2007</rde-dm:param> <rde-dm:param name="month">5</rde-dm:param> <rde-dm:param name="day">2</rde-dm:param> <rde-dm:param name="year">2007</rde-dm:param>


<rde-dm:param name="chartTitle">Visits per hour - 2007/05/02</rde-dm:param>

</rde-dm:reporting>

This call requests the visits per hour of the html-demo Web site for May 2, 2007, and shows them as a line chart.

You can find more information about the "report" mode of the Reporting DynaMent in a separate section.

For this, see:

Creating Live Reports ('report') (Page 316)

333


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Diagram Types and Parameters

This section contains a list of the diagrams provided by RedDot for visualizing live reports. You use the chart-type parameter of a Reporting DynaMent in "report" mode to choose a diagram. With optional rde-dm:param child elements, you access the diagram parameters to customize the display of the image and of the legend.

The following diagram types are available:

Bar Chart (Example):

Two-dimensional Pie Chart with Depth (Example):

rdeDefaultBarChart Two-dimensional bar chart

rdeDefaultBarChartWithDepth Two-dimensional bar chart with depth

rdeDefaultPieChart Two-dimensional pie chart

rdeDefaultPieChartWithDepth Two-dimensional pie chart with depth

rdeDefaultLineChart Two-dimensional line chart

334


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Line Chart (Example):

Bar Chart: rdeDefaultBarChart

335


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

General Parameters

Parameter Description Values

chartAreaColor Background color of the diagram area

Hexadecimal value with leading #. Default: transparent

chartAreaGradient Additional background color of the diagram area. Creates a smooth transition from right to left to the color specified here.


chartBackgroundColor Background color for the entire image


chartBackgroundGradient Additional background color for the entire image. Creates a smooth transition from right to left to the color specified here.


chartFont Font for all captions (title, axes, values, legend)

Name of a font, available in the RedDot LiveServer operating system. Default: Arial

chartFontColor Font color for all captions (title, axes, values, legend)

Hexadecimal value with leading #. Default: black (#000000)

chartFontSize Font size for all captions except title and values along the axes

Value in pixels. Default: 10

chartHeight Height of image Value in points. Default: 400

chartWidth Width of image Value in points. Default: 300

chartSeriesColor Colors to be used Hexadecimal value with leading #. Default: BIRT setting

chartSeriesLabelPosition Position at which numerical values of the diagram are shown

Possible values: inside, outside. Default: outside

chartTitle Diagram title Default: Bar Chart

chartTitleFontSize Font size for title Value in pixels. Default: 16

336


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters for X Axis and Y Axis


chartAxisLabelFontSize Font size of values along the axes

Value in pixels. Default: 10

chartAxisLineColor Color of the axes Hexadecimal value with leading #. Default: black (#000000)

chartAxisTickColor Color of ticks along the axes Hexadecimal value with leading #. Default: black (#000000)

chartGridColor Color of the grid lines Hexadecimal value with leading #. Default: Light gray (#dddddd)

chartHideAxes Hide axes Possible values: true, false. Default: false

chartXAxisGridVisible Showing grid lines of x axis (vertical lines)

Possible values: true, false. Default: false

chartXAxisStagger Values staggered along the x axis


chartXAxisStep Step of values and ticks along the x axis. Is not evaluated if string is given as value for chartXAxisType.

Integer. Default: 1

chartXAxisType Defines if values for x axis are evaluated as string or integer.

Possible values: string, integer. Default: integer

chartXAxisTitle Caption of x axis Default: None

chartYAxisGridVisible Showing grid lines of y axis (horizontal lines)


chartYAxisStagger Staggered view of the values along the y axis


chartYAxisStep Step of values and ticks along the y axis

Integer. Default: 1

chartYAxisTitle Caption of y axis Default: None

337


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters for the Legend


chartLegendBackgroundColor

Background color of the legend


chartLegendBackgroundGradient

Additional background color of the legend. Creates a smooth transition from right to left to the color specified here.


chartLegendPosition Position of the legend Default: rightMiddle Possible values:

Above the diagram: aboveLeft, aboveMiddle, aboveRight

Below the diagram: belowLeft, belowMiddle, belowRight

Left of the diagram: leftBottom, leftMiddle, leftTop

Right of the diagram: rightBottom, rightMiddle, rightTop

Within the diagram, at the bottom: insideBottom, insideBottomLeft, insideBottomRight

Within the diagram, in the middle: insideLeft, inside Right

Within the diagram, at the top: insideTop, insideTopLeft, insideTopRight

chartLegendTitle Headline of the legend Default: None

chartLegendVisible Showing the legend Possible values: true, false. Default: false

338


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Bar Chart with Depth: rdeDefaultBarChartWithDepth

The same parameters as for the rdeDefaultBarChart diagram type apply. The following parameters are possible in addition:

Line Chart: rdeDefaultLineChart

The same parameters as for the rdeDefaultBarChart diagram type apply. Here, the default for chartTitle is Line Chart. For the following parameter other values are possible:


chartFloorColor Color of the depth dimension on the x axis with diagrams that have depth and axes.

Hexadecimal value with leading #. Default: Dark gray (#808080)

chartWallColor Color of the depth dimension on the y axis with diagrams that have depth and axes.

Hexadecimal value with leading #. Default: Dark gray (#808080)


chartSeriesLabelPosition Position at which numerical values of the diagram are shown

Possible values: above, below, left, right. Default: above

339


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Pie Charts: rdeDefaultPieChart, rdeDefaultPieChartWithDepth

You can find more information about the "report" mode of the Reporting DynaMent in a separate section.

For this, see:

Creating Live Reports ('report') (Page 316)


chartAreaColor see above see above

chartAreaGradient see above see above

chartBackgroundColor see above see above

chartBackgroundGradient see above see above

chartFont see above see above

chartFontColor see above see above

chartFontSize see above see above

chartHeight see above see above

chartWidth see above see above

chartSeriesColor see above see above

chartLegendPosition see above see above

chartLegendTitle see above see above

chartLegendVisible see above see above

chartTitle see above Default: Pie Chart

chartTitleFontSize see above see above

chartSeriesLabelPosition see above Possible values: inside, outside. Default: outside

chartSeriesLabel Defines if numerical values are shown as an absolute value or as a percentage

Possible values: dataValue, percentage. You can have both values shown, separated by a semicolon. Default: percentage

chartMinSliceBoundary All values below the limit shown here are combined to one segment

Floating point number. Default: 0

chartMinSliceLabel Name of the combined segment

Default: None

chartMinSliceType Specifies if the number given for chartSeriesLabel is to be evaluated as an absolute value or as a percentage

Possible values: dataValue, percentileDataValue. Default: percentileDataValue

340

DynaMent ReferencesRepository DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Repository DynaMent

The Repository DynaMent is only available with the appropriate license, which activates the Repository connectors and the Repository DynaMent.

Uniform access to external repositories The Repository DynaMent lets you access content in external repositories using a Repository connector. In this context, an external repository is a (server) application that saves documents in folders and can deliver them for editing. In general, repositories enable at least basic document management functions, such as flexible attribute assignment, search, and check-in/check-out. As soon as you configure a repository connector, the Repository DynaMent gives you read and write access to content in the external repositories, as well as its document management functions.

Livelink DM and Livelink Discussion Web Components RedDot Solutions offers preconfigured Web Components that use the Repository and Livelink DynaMents. You can integrate these components directly in your own projects. As a result, you can integrate the sophisticated document management and collaboration functions available on an existing Livelink Enterprise Server.


Reading content from an external repository (mode="read")

Searching an external repository (mode="query")

Creating content in an external repository (mode="create")

Creating a folder in an external repository (mode="create-folder")

Updating content in an external repository (mode="update")

Updating a folder in an external repository (mode="update-folder")

Deleting content from an external repository (mode="delete")

Deleting a folder from an external repository (mode="delete-folder")

Checking content into an external repository (mode="checkin")

Checking content out of an external repository (mode="checkout")

Removing a lock on content in an external repository (mode="cancel-checkout")

Listing content classes (in Livelink: categories) for content in an external repository (mode="list-classes")

Listing content classes (in Livelink: categories) for folders in an external repository (mode="list-classes-folder")

Listing folder items (mode="list")

More information about connectors for repositories and accessing Livelink objects with the Open API is available in the Connectors documentation.

You need the Livelink DynaMent to access certain objects on the Open Text Livelink Enterprise Server. For more information, see the separate section.

See also:

Livelink DynaMent (Page 205)

341


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Content from External Repository ('read')

Purpose

You can read content from an external repository specified using the Repository DynaMent in "read" mode. You can also use the <rde-rd:import> child element to add metadata to a content item.

The content item is identified through the content parameter, which is given the content ID of the repository content as a value. To view such a content ID, you can send a query in "query" mode using the include-mode="content-info" parameter.

Syntax

<rde-dm:repository mode ="read" name ="{connector name}" content ="{content id}" locale ="[locale1;locale2;...]" dateformat-out ="{date format}" include-mode ="[{include-mode},{tagname};]" metainfo ="[rdeallmetainfo|property}]" version ="{version name}"

project ="{project name}"

cache-id ="{cache-id}" size-max ="{size in KB}" size-swap ="{size in KB}" size-determine ="{size in KB}"

encoding ="{encoding}" repository-attribute ="{attribute name}"

access ="[all|session]" >


</rde-rd:import>

</rde-dm:repository>




Parameters

mode Mode of the Repository DynaMent, here "read".

name Name of the repository connector to be used, as defined in RedDot LiveServer.

content Unique string to identify an entry in the repository (content-id).

342


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

locale (optional) Value for the language of the cached content. Possible values include all languages supported by RedDot LiveServer. If nothing is specified: Default project language.

dateformat-out (optional) Defines the date format to use for dates output in the DynaMent result. The syntax is based on that used for standard Java class java.text.SimpleDateFormat (example: yyyy-MM-dd'T'HH:mm).

include-mode (optional) Selects which information about the content that has been found is added to the DynaMent result. The output attributes can have different degrees of detail, depending on which repository is accessed. The following values are possible:

















343


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


Note: Every include-mode selected increases the runtime if the result is not already available in the cache. Therefore, we recommend using the include-mode parameter for information that needs to be evaluated or presented to the user. Value if nothing is specified: "content-listdisplay,notag"







To be able to output metadata, you need to specify the mode "metainfo" in the include-mode parameter. If nothing is specified: No metadata is returned.

version (optional) Content version label that is read. The version label must be the same as that used in the repository.

project (optional) Only used when entering the cache-id parameter: Project name to which the read content in the object cache is assigned. If nothing is specified: the project containing the Repository DynaMent is used.

cache-id (optional) Creates a cache entry (scope="request") in the object cache. Note: No communication takes place with the external repository when content is delivered from the cache, which means no information is written to the audit trail in the external repository either. Specify a content name. This will be the last element of the content key used to store the read content (as RedDot LiveServer content) in the object cache. The content item contains the content data in the default language of the project to which the content is assigned. For RedDot LiveServer content, only the master data that is available through the properties of the external repository, and which can be assigned, is set. The cache-id is used as the name; the description is passed. All data specified in content-info is created as child attributes of the predefined rdeRepository.rdeContentInfo attribute, which has the name of the repository connector as a value. The data requested with the metainfo parameter is stored as a string in the predefined attribute rdeRepository.rdeMetainfo. When the property type of the bridge is transmitted, it is entered as a value of the predefined rdePropertyType child attribute. The root attribute name rdeRepository can be overwritten using the repository-attribute parameter.

344


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8






size-determine (optional) Only for size information for BLOB type content. File size in KB. Data up to this size is read. Value if nothing is specified: "8"

encoding (optional) Specifies the encoding to be used when content from the repository is converted to strings. You can use all encodings supported by JVM, for example, UTF-8. If nothing is specified: "ISO-8859-1"

repository-attribute (optional) Name of the content attribute that takes on the attributes sent from the repository as child elements (see cache-id). In the external repository, folder objects can be administered and returned to RedDot LiveServer as items when read. To differentiate between different types of these objects in RedDot LiveServer, there are two additional content attributes that are subordinate to the repository-attribute:

rdeRepoItemTypeLabel: Type of folder object delivered by the repository. Possible values: "Content" and "Folder".

rdeRepoItemTypeInternal: Contains the type information for the folder object supplied by the bridge.

Value if nothing is specified: "rdeRepository"





345


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Value if nothing is specified: "rde-rd:repository-result"

Child Elements

A child element called <rde-rd:import> is available in "read" mode for assigning metadata to content.

<rde-rd:import> (optional) This child element contains the metadata that will be added to the content. The content of this element will be processed before it is inserted. DynaMents within values of a child element are processed. Inline notation is supported. The syntax is the same as for the Import DynaMent. See the description there.

Result

The content is read from the repository specified and returned in the result XML.

346


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The Repository DynaMent's information, warning, and error messages begin with 27 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:










-27515 Unable to check repository (for capabilities)




-27530 General execution error

-27561 General error while accessing RepositoryItem (content/folder)



-27582 Error while compiling a display element (content-reference)





27101 Versioning has been requested but is not supported by the repository.

27103 Incorrect argument for a parameter (parameter name is specified in the error message).


347


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Searching External Repository ('query')

Purpose

You can use the Repository DynaMent in "query" mode to perform a search of content in the specified external repository. Different child elements are used for the search strings, depending on the repository used:

If you use Open Text Livelink Enterprise Server, use the <rde-rd:query-native> child element for all search strings formulated in the specific search language, Livelink Query Language (LQL). For information on using this search language, see the online help for Livelink Enterprise Server.

If you use IBM WebSphere Information Integration Content Edition (IICE), specify search strings for full-text searches in the <rde-rd:query-fulltext> child element, or search strings for finding properties in the <rde-rd:property> child element. For information about the precise syntax of search strings, please refer the IICE documentation VBrQueryExpressionLanguageGuide.htm.

Note: Not every repository supports the full search functionality. If this is the case, an appropriate error message is shown.

348


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:repository mode ="query" name ="{connector name}" project ="{project name}" locale ="[locale1;locale2;...]" dateformat-out ="{date format}" include-mode ="[{include-mode},{tagname};]"

metainfo ="[rdeallmetainfo|{property}]" chunk ="{chunk number}" chunksize ="{number of records}" maxhits ="{number}" sortedby ="{property name}" sortorder ="[asc|ascending|

desc|descending]"

depth ="[0|1|...n]" appserver ="[yes|no]"

version ="{version name}" item-tag ="[{tagname}|notag]"

cache-id ="{cache id}" size-max ="{size in KB}" size-swap ="{size in KB}" size-determine ="{size in KB}"

encoding ="{encoding}" repository-attribute ="{attribute name}" access ="[all|session]"

sources ""{Search Broker;...}" >

<rde-rd:query-native> query (für Open Text Livelink Server)

</rde-rd:query-native>

<rde-rd:query-fulltext> query (for IBM WebSphere IICE) </rde-rd:query-fulltext> <rde-rd:query-property> query (for IBM WebSphere IICE)

</rde-rd:query-property>





Parameters

mode Mode of the Repository DynaMent, here "query".


349


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



dateformat-out (optional) Defines the date format to use for dates output in the DynaMent result. The syntax is based on that used for standard Java class java.text.SimpleDateFormat (example: yyyy-MM-dd'T'HH:mm).
















350


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8












chunk (optional) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. The resulting XML element of the Repository DynaMent contains the parameters previouschunk, nextchunk, lastchunk, hits, chunk, and chunksize, which can be implemented using XSL scrolling functions. Value if nothing is specified: "1". This value is also used if the starting point of the chunk exceeds the maximum possible value.

chunksize (optional) Maximum number of content items that may be included in the result of the Repository DynaMent. If the number of items found is greater than chunksize, then the remaining items are displayed in the next chunk after sorting. Possible values: "1" to "500" Value if nothing is specified: "11"

maxhits (optional) Maximum number of hits returned by the repository (1 – n). Value if nothing is specified: "500"

351


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

sortedby (optional) Name of a property in the repository that will be used to sort the content alphanumerically in the result. If nothing is specified: The sequence of contents in the result corresponds to the score calculated internally by the repository. Notes: The hits are only sorted once the search query has been executed. Consequently, hits that are not returned due to the max-hits parameter cannot be taken into account. The sorting is alphabetical even for numeric values, which means 200 comes before 30.


"asc" or "ascending": Ascending












Value if nothing is specified: "rde-rd:result-item"

cache-id (optional) Creates a cache entry (scope="request") in the object cache. Note: No communication takes place with the external repository when content is delivered from the cache, which means no information is written to the audit trail in the external repository either. Specify a content name. This will be the last element of the content key used to store the read content (as RedDot LiveServer content) in the object cache. The content item contains the content data in the default language of the project to which the content is assigned. For

352


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

RedDot LiveServer content, only the master data that is available through the properties of the external repository, and which can be assigned, is set. The cache-id is used as the name; the description is passed. All data specified in content-info is created as child attributes of the predefined rdeRepository.rdeContentInfo attribute, which has the name of the repository connector as a value. The information requested with the metainfo parameter are stored as a string in the predefined attribute rdeRepository.rdeMetainfo. When the property type of the bridge is transmitted, it is entered as a value of the predefined rdePropertyType child attribute. The root attribute name rdeRepository can be overwritten using the repository-attribute parameter.








repository-attribute (optional) Name of the content attribute that takes on the attributes sent from the repository as child elements. In the external repository, folder objects can be administered and returned to RedDot LiveServer as items when read. To differentiate between different types of these objects in RedDot LiveServer, there are two additional content attributes that are subordinate to the repository-attribute:



353


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8






sources (optional) Specifies one or more SearchBrokers of the repository. Multiple attributes are separated by semicolons. When the DynaMent runs, only the SearchBrokers specified here are called, to minimize the system load.

If no value or an empty string is specified: The SearchBrokers specified in the corresponding repository connector (General area, Default SearchBroker field) are used. If nothing is specified there either, all SearchBrokers are called.





Child Elements

The Repository DynaMent has the child elements below for formulating search queries. You must use at least one of these. DynaMents within values of a child element are processed. Inline notation is supported. If you use Open Text Livelink Enterprise Server, use the <rde-rd:query-native> child element for all search strings formulated in the specific search language, Livelink Query Language (LQL). For information on using this search language, see the online help for Livelink Enterprise Server.

If you use IBM WebSphere Information Integration Content Edition (IICE), specify search strings for full-text searches in the <rde-rd:query-fulltext> child element, or search strings for finding properties in the <rde-rd:property> child element. For information about the precise syntax of search strings, please refer the IICE documentation VBrQueryExpressionLanguageGuide.htm.

Not every repository supports the full search functionality for the child elements. If this is the case, an appropriate error message is shown.

<rde-rd:query-native> (optional) Only used for Livelink search queries. The query is sent to the bridge unmodified. Because special characters, and in particular angle brackets, are frequently used in search requests, it is advisable to enclose each query in a CDATA section: <![CDATA[query-native]]>.

<rde-rd:query-fulltext> (optional) Only used for IICE: Search query for a full-text search. The query is sent to the bridge unmodified. Because special characters, and in particular angle brackets, are frequently used in search requests, it is advisable to enclose each query in a CDATA section: <![CDATA[query-fulltext]]>.

354


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-rd:query-property> (optional) Only used for IICE: Search query for a search for properties. The query is sent to the bridge unmodified. Because special characters, and in particular angle brackets, are frequently used in search requests, it is advisable to enclose each query in a CDATA section: <![CDATA[query-property]]>.

Result

The result in XML for a Repository DynaMent is a list of the content items found. The content list is enclosed by an element that is specified in the tag parameter. Each individual content item is enclosed by the tag specified in the item-tag parameter. The parameters of the tag element (default: "rde-rd:repository-result") consist of the repeated display of the parameters of the original Repository DynaMent, augmented by the following parameters:

hits: Total number of located content items




The individual content items found are output consecutively in item-tag elements (default: "rde-rd-result-item"). In addition to the name, the resulting XML also contains additional information regarding the content, such as project, language, content type, and serial number.

Error Handling



-27102 mode="query" has been requested but is not supported by the repository.

-27103 mode="query" with property search has been requested but is not supported by the repository.

-27104 mode="query" with full-text search has been requested but is not supported by the repository.

-27105 mode="query" with full-text search AND simultaneous property search has been requested, but is not supported by the repository.

-27106 Incorrect full-text criterion

-27107 Incorrect property criterion

-27108 Invalid query expression

355


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8













-27571 Error while searching. None of the (syntax ?!) errors in 271xx.

-27572 Error while sorting











27111 Exceptions that occurred during query.execute()

27112 Folder search not supported

27113 Content class search not supported


356


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Creating Content in External Repository ('create')

Purpose

You can create content in an external repository using the Repository DynaMent in "create" mode. You can pass on content data as well as metadata.

The <rde-rd:content> child element contains the content data. The content of this element will be processed before it is inserted. You can also use the <rde-rd:import> child element to add metadata to a content item. Only metadata that has been defined as properties in the external repository, and which allow write access, can be transferred.

Syntax

<rde-dm:repository mode ="create" name ="{connector name}" folder ="{folder id}" content-name ="{content name}" contentclass-name ="{contentclass name}" dateformat-in ="{date format}" ref-type ="[embedded|file|named]" ref ="{reference}" encoding ="{encoding}" abort-events ="[error|warn|none|{warning-codes}|

{error-codes}]" >

<rde-rd:import>

<keywords keyword-separator =","

name-value-separator =":" value-delimiters ="{delimiter}" resolve-entities ="[no|yes]" > attribute1:value1, attribute2:value2,... </keywords> </rde-rd:import> <rde-rd:content> ...embedded content...

</rde-rd:content>





357


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Repository DynaMent, here "create".


folder (optional) ID of the folder where the content should be created. Depending on the repository, content items can only be created within a folder.

content-name (optional) Alternative name for the content you wish to create. Depending on the repository, this name need not be unique.

contentclass-name (optional) Name of the content class (in Livelink: category) used for the folder that you want to create. You can enter a list of multiple names separated by commas or semicolons. Depending on the repository, you may have to specify a content class when you create folders. To determine the names of the available classes, use the Repository DynaMent in "list-classes" mode.

dateformat-in (optional) Determines the date format to use for dates delivered to the external repository. The syntax is based on that used for standard Java class java.text.SimpleDateFormat (example: yyyy-MM-dd'T'HH:mm). Also see the Livelink repository-specific information below.


"embedded": The content data specified in the value of the child element <rde-rd:content> is passed on. The child element is processed prior to transfer. This means that you can transfer content from attribute values or include DynaMents in the content. Any DynaMents you want to include in the content must not be processed before. You need the parameter value process-mode="ignore" to achieve this. If the <rde-rd:content> child element does not exist, only metadata from the <rde-rd:import> child element is passed on.


"named": Content data of the content specified in the ref parameter is transferred. However, only content data for the language of the current session is transferred. The content must be stored in the object cache under the name specified in ref for the current project. If the content cannot be found in the object cache, an error message is returned. In this case, nothing is transferred - not even the metadata from the <rde-rd:import> child element.


358


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


ref-type="file": URI for transfer Specifies either an absolute path and file name on RedDot LiveServer where the file for transfer is located or a relative path starting with the Web application path .../cps/WEB-INF/. If the specified file is not available, nothing is transferred - not even the metadata from the <rde-rd:import> child element. If no value is specified, ref-type="embedded" is used instead of "file".

ref-type="named": Name of the content item whose data is to be transferred. However, only content data for the language of the current session is transferred. The content must be stored in the object cache under the name specified for the current project. If the content cannot be found in the object cache, an error message is returned. In this case, nothing is transferred - not even the metadata from the <rde-rd:import> child element.









Child Elements

In "create" mode, there are two child elements, <rde-rd:import> and <rde-rd:content>, each of which can be used once in a Repository DynaMent. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:import> (optional) This child element contains the metadata to be transferred. Only metadata that has been defined as properties in the external repository and to which write access is allowed can be transferred.

<keywords> (optional) Specifies attributes and values for a current content item. You can only specify one <keywords> element. You need to specify separators between each attribute and its value (name-value-separator parameter). When specifying multiple attributes, you need to specify separators between the attribute-value pairs (keyword-separator parameter; example of default setting for separators: attribute1: value1, attribute2: value2). To create attributes without values, you can leave out the values. You do have to include the separators (example: attribute1:, attribute2:).

359


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



value-delimiters (optional) Text block separators for enclosing attribute values. These make it possible for you to use a variety of characters in values, for example, even those defined as separators. The specification of one or more text block separators for attribute values. Enter the characters one right after the other (without spaces or separators). Each character you enter is interpreted as a text block separator. If the first character of an attribute value is one of the characters specified as a text block separator, it will be treated as the opening separator for this value and thus must also close the value. If nothing is specified: No text block separator is used. If you want to use double quotation marks (") and backslashes (\) as text delimiters, you have to model them as an escape sequence—that is, with a leading backslash (example: delimiters="\""). value-delimiters="\"").


"yes": All entities are resolved according to the DTD definition file included (go to RedDot Web application path/WEB-INF/var/xml/doctype.txt). This setting is helpful, for example, if an external system delivers HTML code with entities that are to be used as attribute values in Unicode in RedDot LiveServer.


<rde-rd:content> (optional) Only for ref-type="embedded": This child element contains the content data to be transferred. If the child element does not exist, only the metadata from the <rde-rd:import> child element is transferred.

Result

The transferred content is created with the specified metadata in the specified repository. The content ID of the new content item is returned in the result in the "performed" attribute.

360


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling




-27131 The mode ="create" has been requested, but it is not supported by the repository in this form

-27133 The parameter contentclass-name has been specified but cannot be interpreted by the repository specified












-27532 "Native" content must be provided


27106 The parameter contentclass-name has been specified but cannot be interpreted by the repository specified. Null-contentclasses are possible.

27108 The property specified in the import tag cannot be set, as it has not been defined.

27109 The property specified in the import tag cannot be set, as it is read only.

27110 The property specified in the import tag can possibly not be set (unable to determine type).

361


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameter dateformat-in: Data Information in Livelink

Livelink differentiates between several date attribute types in attribute definitions. Values of parameter dateformat-in are handled differently, depending on the type:

Date: Field: In this case, the display accuracy in the Livelink UI is limited to days and hours, which means minutes do not have to be specified in parameter dateformat-in for display purposes in Livelink. In particular, the values are not rounded up (which means the value 2008-01-01T07:59 is displayed as 2008-01-01, 7:00 in the Livelink UI). If you need a more exact time figure, you can read an attribute using the Repository DynaMent.

Date: Popup: In this case, only date information is allowed in Livelink, without time information. For times to be recognized as allowed, values, the time must always be specified as 00:00 in the dateformat-in parameter.

362


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Creating Folder in External Repository ('create-folder')

Purpose

The Repository DynaMent in "create-folder" mode allows you to create folders in an external repository. You can also use the <rde-rd:import> child element to add metadata to a folder. Only metadata that has been defined as properties in the external repository, and which allow write access, can be transferred.

Syntax

<rde-dm:repository mode ="create-folder" name ="{connector name}" folder ="{folder id}" folder-name ="{folder name}" contentclass-name ="{contentclass name}" dateformat-in ="{date format}" item-type ="[folder|compound_document]" abort-events ="[error|warn|none|{warning-codes}|

{error-codes}]" >

<rde-rd:import>


name-value-separator =":" value-delimiters ="{delimiter}" resolve-entities ="[no|yes]" > attribute1:value1, attribute2:value2,... </keywords> </rde-rd:import>





Parameters

mode Mode of the Repository DynaMent, here "create-folder".


folder (optional) ID of the folder where the folder should be created. Depending on the repository, you can create folders only within another folder.

363


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

folder-name (optional) Alternative name for the folder you wish to create. Depending on the repository, this name need not be unique.

contentclass-name (optional) Name of the content class (in Livelink: category) used for the folder that you want to create. You can enter a list of multiple names separated by commas or semicolons. Depending on the repository, you may have to specify a content class when you create folders. To determine the names of the available classes, use the Repository DynaMent in "list-classes-folder" mode.


item-type (optional) Defines which type of folder to create. Possible values:

"folder": Folder (default setting).

"compound_document": Type for using an Open Text Livelink repository. Folder with version information.

Value if nothing is specified: "folder"







Child Elements

In "create-folder" mode, there is one child element. DynaMents within values of a child element are processed. Inline notation is supported.


<keywords> (optional) Specifies attributes and values. You can only specify one <keywords> element. You need to specify separators between each attribute and its value (name-value-separator parameter). When specifying multiple attributes, you need to specify separators between the attribute-value pairs (keyword-separator parameter; example of default setting for separators: attribute1: value1, attribute2: value2). To create attributes without values, you can leave out the values. You do have to include the separators (example: attribute1:, attribute2:).

364


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8





"yes": All entities are resolved according to the DTD definition file included (at RedDot Web application path/WEB-INF/var/xml/doctype.txt). This setting is helpful, for example, if an external system delivers HTML code with entities that are to be used as attribute values in Unicode in RedDot LiveServer.


Result

The folder including the metadata specified is created in the repository specified. The folder ID of the new folder is returned in the "performed" attribute of the result.

365


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling




-27132 mode="create-folder" has been requested but is not supported by the repository in this form.

-27133 The parameter contentclass-name has been specified but cannot be interpreted by the repository specified













27106 The parameter contentclass-name has been specified but cannot be interpreted by the repository specified. Null-contentclasses are possible.




366


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8





367


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Updating Content in External Repository ('update')

Purpose

The Repository DynaMent in "update" mode allows you to update content in an external repository. You can edit both the content data and the metadata. Prerequisites: The content is not locked and you have the necessary rights.

The <rde-rd:content> child element contains the content, the <rde-rd:import> child element has the metadata. Only metadata that has been defined as properties in the external repository, and which allow write access, can be transferred.

Syntax

<rde-dm:repository mode ="update" name ="{connector name}"

content ="{content id}" dateformat-in ="{date format}"

ref-type ="[embedded|file|named]" ref ="{reference}" encoding ="{encoding}" abort-events ="[error|warn|none|{warning-codes}| {error-codes}]" contentclass-name ="{contentclass name}"

contentclass-action="[add|remove]" >

<rde-rd:import>



</rde-rd:content>





368


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Repository DynaMent, here "update".


content Unique string to identify an entry in the repository (content ID).










encoding (optional) Only for reftype="embedded" and "named": Encoding used to interpret the transferred content data.

369


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8









contentclass-action (optional) Is only evaluated if parameter contentclass-name is specified. Used to add or remove content classes (in Livelink: categories).

"add": Adds a content class.

"remove": Removes a content class.

Value if nothing is specified: "add".

Child Elements

There are two child elements, <rde-rd:import> and <rde-rd:content> in "update" mode, each of which can be used once in a Repository DynaMent. DynaMents within values of a child element are processed. Inline notation is supported.



keyword-separator (optional) Separator between multiple attribute-value pairs (for example: profile:3, category:5). Make sure you only use this character as a separator and not in attribute names or values. You can only specify one character. Value if nothing is specified: "," (comma).

370


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Note: An attribute can take several different values. Multivalue attributes are also implemented in the form of multiple attribute-value pairs (for example, profile level:1, profile level:5) and not by character-delimited values. level:1, level:5), not by character-delimited values.




"yes": All entities are resolved according to the DTD definition file included (go to RedDot Web application path/WEB-INF/var/xml/doctype.txt). This setting is helpful, for example, if an external system delivers HTML code with entities that are to be used as attribute values in Unicode in RedDot LiveServer.



Result

The content item specified is changed in the repository.

371


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling




-27101 The specified user does not have the rights to perform this action on the content item selected.

-27141 mode="update" has been requested but is not supported by the repository in this form.











-27561 General error while accessing the repository content.

-27565 General error while attempting update for repository content


27107 mode="update" query was made to change or define the ID of the content. This is not supported by the repository in this form.




372


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8





373


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Updating Folder in External Repository ('update-folder')

Purpose

The Repository DynaMent in "update-folder" mode allows you to edit the metadata of folders in an external repository. To specify metadata, use the <rde-rd:import> child element. Only metadata that has been defined as properties in the external repository, and which allow write access, can be transferred.

Syntax

<rde-dm:repository mode ="update-folder" name ="{connector name}" folder ="{folder id}"

dateformat-in ="{date format}" abort-events ="[error|warn|none|{warning-codes}|

{error-codes}]" contentclass-name ="{contentclass name}"


<rde-rd:import>


name-value-separator =":" value-delimiters ="{delimiter}" resolve-entities ="[no|yes]" > attribute1:value1, attribute2:value2,... </keywords> </rde-rd:import>





Parameters

mode Mode of the Repository DynaMent, here "update-folder".


folder Folder ID of the folder that will be updated.

374


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8








contentclass-name (optional) Name of the content class (in Livelink: category) used for the folder that you want to create. You can enter a list of multiple names separated by commas or semicolons. Depending on the repository, you may have to specify a content class when you create folders. To determine the names of the available classes, use the Repository DynaMent in "list-classes-folder" mode.





Child Elements

In "update-folder" mode, there is one child element. DynaMents within values of a child element are processed. Inline notation is supported.



375


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8







Result

The folder specified is changed in the repository.

376


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling





-27110 mode="update-folder" has been requested, but the repository does not support folders.

-27142 mode="update-folder" has been requested but is not supported by the repository in this form.












-27561 General error while accessing the repository content

-27565 General error while attempting update for repository content

27107 mode ="update-folder" query was made to change or define the ID of the content. This is not supported by the repository in this form.




377


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8





Deleting Content from External Repository ('delete')

Purpose

You delete content from an external repository using the Repository DynaMent in "delete" mode.

Syntax

<rde-dm:repository mode ="delete" name ="{connector name}"

content ="{content id}" />




Parameters

mode Mode of the Repository DynaMent, here "delete".


378


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

content Content ID of the content item that will be deleted.

Results

Provided the user has the necessary rights, the content item is deleted from the external repository.

Error Handling

The Repository DynaMent's information, warning, and error messages begin with 27 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:

Return code Meaning



-27111 mode="delete" has been requested but is not supported by the repository in this form.

-27501 Unknown error when using the bridge.









-27530 General error while executing

-27551 General error while deleting a repository item.

-27561 General error while accessing a repository item.


379


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Deleting Folder from External Repository ('delete-folder')

Purpose

You delete folders from an external repository using the Repository DynaMent in "delete-folder" mode.

Syntax

<rde-dm:repository mode ="delete-folder" name ="{connector name}"

folder ="{folder id}" />




Parameters

mode Mode of the Repository DynaMent, here "delete-folder".


folder Folder ID of the folder that will be deleted.

Results

Provided the user has the necessary rights, the folder is deleted from the external repository.

380


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling


Return code Meaning



-27110 mode="delete-folder" has been requested but is not supported by the repository.

-27112 mode="delete-folder" has been requested but is not supported by the repository in this form.











-27551 General error while deleting a repository item.

-27561 General error while accessing a repository item.

381


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Checking Content into External Repository ('checkin')

Purpose

The Repository DynaMent in "checkin" mode allows a user to update content in an external repository after having locked this content. You can edit both the content data and the metadata. The content lock is then removed, making the content item editable again.

The <rde-rd:content> child element contains the content, the <rde-rd:import> child element has the metadata. Only metadata that has been defined as properties in the external repository, and which allow write access, can be transferred.

Syntax

<rde-dm:repository mode ="checkin" name ="{connector name}"

content ="{content id}" dateformat-in ="{date format}"

ref-type ="[embedded|file|named]" ref ="{reference}" encoding ="{encoding}" abort-events ="[error|warn|none|{warning-codes}| {error-codes}]" contentclass-name ="{contentclass name}"


<rde-rd:import>



</rde-rd:content>





382


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Repository DynaMent, here "checkin".


content Unique string to identify an entry in the repository (content ID).











383


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8













Child Elements

There are two child elements, <rde-rd:import> and <rde-rd:content> in "checkin" mode, each of which can be used once in a Repository DynaMent. DynaMents within values of a child element are processed. Inline notation is supported.



keyword-separator (optional) Separator between multiple attribute-value pairs (for example: profile:3, category:5). Make sure you only use this character as a separator and not in attribute names or values. You can only specify one character. Value if nothing is specified: "," (comma).

384


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Note: An attribute can take several different values. Multivalue attributes are also implemented in the form of multiple attribute-value pairs (for example, profile level:1, profile level:5) and not by character-delimited values. level:1, level:5), not by character-delimited values.







Result

The content item specified is changed in the repository and the content lock removed.

385


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling




-27121 mode="checkin" has been requested but is not supported by the repository in this form.

-27143 mode="checkin" has been requested but is not supported by the repository in this form.











-27533 General error while setting the properties of a repository item.

-27561 General error while accessing the repository content

-27564 General error while attempting checkin for repository content.

-27566 The repository content is not checked out


27107 mode="checkin" query was made to change or define the ID of the content. This is not supported by the repository in this form.




386


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8





Checking Out Content from External Repository ('checkout')

Purpose

You can use the Repository DynaMent in "checkout" mode to check out content from an external repository. This makes the content unavailable to other users for editing, deleting or checking out.

This mode is similar to "read" mode, but also blocks content. Such a content lock is always assigned to the user who checks out a content item from the external repository. This is the user who has been defined in the repository connector. "checkout" mode is available only if the repository that is addressed via the bridge supports checkout locks. RedDot LiveServer or the bridge itself do not support such checkout locks.

For this mode, all parameters described for "read" mode are available.

387


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:repository mode ="checkout" {parameters of the Repository DynaMent

in "read" mode} />




Parameters

mode Mode of the Repository DynaMent, here "checkout".

Additional Parameters All parameters of the Repository DynaMent in "read" mode apply. See the relevant section and the link below for details.

Results

Provided the user has the necessary rights, the content item is checked out from the external repository.

Error Handling

The Repository DynaMent's information, warning, and error messages begin with 27 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), and the return codes for "read" mode, the following messages are possible:

Return code Meaning


-27121 mode="checkout" has been requested but is not supported by the repository in this form.

-27320 Project was not found


-27562 General error while attempting checkout for repository content.

-27567 The content item you wish to check out is already checked out


388


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

For additional return codes, see "read" mode.

See also:

Reading Content from External Repository ('read') (Page 342)

Removing Content Lock ('cancel-checkout')

Purpose

When you have locked a content item in an external repository using "checkout" mode, you can remove that lock using the Repository DynaMent in "cancel-checkout" mode. The content item remains unchanged.

Syntax

<rde-dm:repository mode ="cancel-checkout" name ="{connector name}"

content ="{content id}" />




Parameters

mode Mode of the Repository DynaMent, here "cancel-checkout".


content Content ID of the content item whose lock will be removed.

Results

Provided the user has the necessary rights, an existing lock on a content item is removed. Only the user who has set the lock (checkout) can remove it again.

389


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling


Return code Meaning



-27122 mode="cancel-checkout" has been requested but is not supported by the repository in this form.












-27563 General error while attempting CancelCheckout for repository content.


27105 Content is not currently checked out.

390


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Listing Content Classes/Categories for Content ('list-classes')

Purpose

The Repository DynaMent in "list-classes" mode allows you to determine which content classes (in Livelink: categories) are available for creating content.

Syntax

<rde-dm:repository mode ="list-classes" name ="{connector name}"

details ="[false|true]" />




Parameters

mode Mode of the Repository DynaMent, here "list-classes".


details (optional) Indicates whether the list of content classes (in Livelink: categories) will also show the attribute definitions. Possible values:

"false": The attribute definitions are not displayed.

"true": The attribute definitions are displayed.

If no value is specified: "false"

Result

The available content classes or categories for all contents are listed.

391


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling


Return code Meaning












27106 Although content classes are supported, they cannot be listed.

392


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Listing Content Classes/Categories for Folders ('list-classes-folder')

Purpose

The Repository DynaMent in "list-classes-folder" mode allows you to determine which content classes or categories are available for creating folders. When repository connectors use a Livelink bridge, the Livelink categories that are assigned to the CategoryWorkspace are determined.

Syntax

<rde-dm:repository mode ="list-classes-folder"

name ="{connector name}" />




Parameters

mode Mode of the Repository DynaMent, here "list-classes-folder".


Result

The available content classes for all folders are listed. When a repository connector with a Livelink bridge is used, the Livelink categories that are assigned to the CategoryWorkspace are listed.

393


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling




-27110 mode="list-classes-folder"has been requested, but the repository does not support folders.











27106 Although content classes are supported, they cannot be listed.

394


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Listing Folder Items ('list')

Purpose

The Repository DynaMent in "list" lets you list all items in a specified folder (which you specify in the folder parameter) in the directory structure of a repository. These can be content items as well as directly subordinate folders.

Syntax

<rde-dm:repository mode ="list" name ="{connector name}"

folder ="{folder id}" project ="{project name}" locale ="[locale1;locale2;...]" dateformat-out ="{date format}" include-mode ="[{include-mode},{tagname};]"

metainfo ="[rdeallmetainfo|{property}]" chunk ="{chunk number}" chunksize ="{number of records}" maxhits ="{number}"

depth ="[0|1|...n]" appserver ="[yes|no]"

version ="{version name}" item-tag ="[{tagname}|notag]"

cache-id ="{cache-id}" size-max ="{size in KB}" size-swap ="{size in KB}" size-determine ="{size in KB}"

encoding ="{encoding}" repository-attribute ="{attribute name}" access ="[all|session]"

/>




Parameters

mode Mode of the Repository DynaMent, here "list".


folder ID of the folder in the external repository whose items are to be listed.

395


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



dateformat-out (optional) Defines the date format to use for dates output in the DynaMent result. The syntax is based on that used for standard Java class java.text.SimpleDateFormat (example: yyyy-MM-dd'T'HH:mm). If nothing is specified: No formatting.











type: Content type in RedDot LiveServer that is mapped to a MIME type from the repository Note: The mapping between MIME content types in a repository and RedDot LiveServer content types is defined in the <RedDot Web application path>/WEB-INF/etc/mimetype.txt file. You can add MIME types and map content types.





396


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8












chunk (optional) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. The resulting XML element of the Repository DynaMent contains the parameters previouschunk, nextchunk, lastchunk, hits, chunk, and chunksize, which can be implemented using XSL scrolling functions. Value if nothing is specified: "1". This value is also used if the starting point of the chunk exceeds the maximum possible value.

chunksize (optional) Maximum number of content items that may be included in the result of the Repository DynaMent. If the number of items found is greater than chunksize, then the remaining items are displayed in the next chunk after sorting. Possible values: "1" to "500" Value if nothing is specified: "11"

maxhits (optional) Maximum number of hits returned by the repository (1 – n). Value if nothing is specified: "500"

397


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8










Value if nothing is specified: "rde-rd:result-item"

cache-id (optional) Creates a cache entry (scope="request") in the object cache. Note: No communication takes place with the external repository when content is delivered from the cache, which means no information is written to the audit trail in the external repository either. Specify a content name. This will be the last element of the content key used to store the read content (as RedDot LiveServer content) in the object cache. The content item contains the content data in the default language of the project to which the content is assigned. For RedDot LiveServer content, only the master data that is available through the properties of the external repository, and which can be assigned, is set. The cache-id is used as the name; the description is passed. All data specified in content-info is created as child attributes of the predefined rdeRepository.rdeContentInfo attribute, which has the name of the repository connector as a value. The information requested with the metainfo parameter are stored as a string in the predefined attribute rdeRepository.rdeMetainfo. When the property type of the bridge is transmitted, it is entered as a value of the predefined rdePropertyType child attribute. The root attribute name rdeRepository can be overwritten using the repository-attribute parameter.

398


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8








repository-attribute (optional) Name of the content attribute that takes on the attributes sent from the repository as child elements. In the external repository, folder objects can be administered and returned to RedDot LiveServer as items when read. To differentiate between different types of these objects in RedDot LiveServer, there are two additional content attributes that are subordinate to the repository-attribute:








399


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8





Result

The result in XML for a Repository DynaMent is list of all the direct subitems of a folder, for example, content items and subordinate folders. The list of entries is enclosed by an element that is specified in the tag parameter. Each individual entry is enclosed by the tag specified in the item-tag parameter. The parameters of the tag element (default: "rde-rd:repository-result") consist of the repeated display of the parameters of the original Repository DynaMent, augmented by the following parameters:

hits: Total number of located content items




parents IDs of the parent folders which contain the folder. The value is blank if the folder has no parent folder, or if the repository does not support this specification.

The individual entries found are output consecutively in item-tag elements (default: "rde-rd-result-item"). Along with the ID of the item (content-id parameter), further information about the individual item is also returned in the result XML, such as name (content-name), language (locale) and MIME type (rde-rd:mime). You can recognize from the MIME type whether the item is a content item or a folder.

Note: If a connector has a bridge to Open Text Livelink, all relevant information for the current Livelink object is output. All the relevant information for the folder is output, particularly the ID of the parent folder.

400


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling
















-27573 Error while executing the finder











27111 Exceptions which occurred during finder.execute()

27114 Display of parent folders is not supported

401

DynaMent ReferencesScript DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Script DynaMent

The Script DynaMent runs scripts for the dynamic display of contents.


Call a script

Specify additional parameters using child elements

Calling Scripts

Purpose

The Script DynaMent runs Python scripts for the dynamic display of contents. At runtime, it is replaced by the result of a Python script call.

In the same way as for the Iolet DynaMent, you can use additional parameters by inserting them as (hierarchically subordinate) child elements in the Script DynaMent. You can use the Script DynaMent either with or without child elements.

Syntax

<rde-dm:script project ="{projectname}" name ="{projectname:contentname}" content ="{projectname:contentname}" script-requestparams ="[none|readonly|readwrite]" include-mode ="[cdata|text|xml|mixed]" item-tag ="[notag|{tagname}]" > <parameter name-1>{value 1}</parameter name-1> ... <parameter name-n>{value n}</parameter name-n> ...

</rde-dm:script>




Parameters

project (optional) Old notation that should no longer be used. The name of the project (valid for name and content) if no project information has been provided.

Name Name of the script that is to be run. The syntax is "projectname:contentname". If the names of content items and content groups are not unique within a project, you must

402


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml). If the project is not specified here in the case of internal content, then the project parameter is used. If no project is specified there, then the current project is accessed. For external content: No project is specified and the name of the content item begins with "http://", "https://", or "file://". The request uses the specified URL.

content Content (XML, XSL, HTML, script), supplied with the name content from the database as the "content" variable in the Python script. The syntax is "projectname:contentname". If the names of content items and content groups are not unique within a project, you must also specify the path name of the content within the content group hierarchy. The path components are separated by slashes (example: demo:modules/news/news.xml). If the project is not specified here in the case of internal content, then the project parameter is used. If no project is specified there, then the current project is accessed. For external content: No project is specified and the name of the content item begins with "http://", "https://", or "file://". The request uses the specified URL.

script-requestparams (optional) Rules for the access to request parameters in Python scripts (also see the Notes).

"none": Request parameters can be neither read nor written.

"readonly": Request parameters can be read.

"readwrite": Request parameters can be read and written.

If no value is specified: "none"

include-mode (optional) Defines how the results of the script will be added to the content (also see the example below).

"cdata": The results will be inserted into a CDATA element. This mode ensures that even HTML sections that are not XML compliant can be transferred to the XML result without causing problems.

"text": The unmodified result will be inserted as text. If the text contains non-XML compliant characters, the page may not display correctly.

"xml": The results are parsed and inserted as XML. If there is an error during parsing, the include-mode="mixed" will be used automatically. The result will then be inserted in a tag defined by the item-tag parameter.

"mixed": The result will be inserted as text. Non-XML compliant characters will be replaced by their predefined XML entities.

If no value is specified: "cdata"

item-tag (optional) Only for include-mode="xml": Tag name of the XML element that is used to enclose the result within the result tag in case an error occurs during parsing.




403


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

tag (optional) This is the tag name of the resulting XML element that displays the results of the DynaMent.




Child elements

RedDot LiveServer provides a set of standard variables that you can access when running scripts (see Info below). You can also define more parameters from which variables for the script are generated. To enable this, the Script DynaMent has additional, optional child elements. DynaMents within child elements are processed; inline notation is supported.

<parameter name> (optional) Additional parameters from whose variables the script is generated. You can enter as many different parameters as you wish. All child elements of each parameter are processed and the text value of all child elements is used. When a DynaMent has been executed, a valid list of child elements must have been generated. Note: You can select the parameter names as required. Make sure that you do not use any predefined parameter or variable names, or they will be overwritten.

Notes

In previous versions, request parameters had been provided as a variable in Python script. This function is deprecated and should no longer be used. Instead use the following method for accessing the request parameters:

An object of the type de.reddot.api.web.WebletRequest that has been generated new for the Python script, is provided in the webletRequest variable, which only serves as a container for the request parameters. You can access the request parameters with the methods of this class described in the API documentation. For reasons of runtime, the object is only passed when the parameter script-requestparam has the value readonly or readwrite.

Result

A result of type "String" is expected in the "result" variable. If there is no output value or the value is incorrect, a corresponding error message is displayed. Because the functions of the Python scripts can be very different, the output result may also differ accordingly.

404


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error handling

The Script DynaMent's information, warning, and error messages begin with 11 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible:

Standard Variables for Scripts in RedDot LiveServer


-11511 The script generated an error message.

11111 Result is not XML; include-mode="mixed" was used.

11401 The script returns no value.

Variable Data type Value

session CoaSession Current session in the form of an object of the type de.reddot.api.common.

session.CoaSession. You can find the description of the methods of this object in the API documentation.

content String Content

type String Content type (XML, XSL, HTML, Script)

base64 Object Base64 encoder for authentication

project String Project name

405


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Use of the include-mode parameter:

test.xml <test> <rde-dm:script name="test.py" />

</test>

test.py import sys

result="<result><a>aaa</a><b>bbb</b></result>"

Result with include-mode="cdata" <test> <![CDATA[<result><a>aaa</a><b>bbb</b></result>]]>

</test>

Result with include-mode="text" <test><result><a>aaa</a><b>bbb</b></result></test>

Result with include-mode="xml" <test> <result>

<a>aaa</a> <b>bbb</b>

</result>

</test>

Result with include-mode="mixed" <test><result><a>aaa</a><b>

bbb</b></result></test>

406

DynaMent ReferencesTagging DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Tagging DynaMent

The Tagging DynaMent lets you assign tags to content, evaluate the tags, and make tag clouds. The Tagging DynaMent also provides access to all relevant tagging/voting data, as well as methods for administering tags efficiently.

The various modes of the Tagging DynaMent are described below:

Tag configuration:

Define tags (mode="defineTags")

Read tags (mode="getTags")

Delete tags (mode="deleteTags")

Rename tags (mode="renameTag")

Tag assignment:

Assign tags to target objects (mode="assignTags")

Delete tag assignments (mode="unassignTags")

Suggest tags (mode="suggestTags")

Tag queries:

Read tag assignments (mode="getAssignments")

Read assigned tags (mode="getAssignedTags")

Read assigned target objects (mode="getTargets")

Tag evaluation:

Consolidate tagging data (mode="consolidateData")

Provide consolidated data (mode="getConsolidatedData")

Delete consolidated data (mode="deleteConsolidatedData")

Example Project for Tagging and Voting

The provided sample project tagvote contains several examples of how you can use the Tagging DynaMent to implement basic tagging and voting functions.

The tagvote project is shipped as a project export in the share folder. You can import the project export quickly and easily the GUI (with: Main Menu -> Administer Projects -> Import).

For information about defining and assigning tags with the Import DynaMent, see:

Defining and Assigning Tags (Page 155)

For information about tagging/voting for individual projects, see the Projects/Contents documentation.

407


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Using Tagging and Voting

Tags and Their Target Objects Tags can be assigned one or more times to one or more target objects. Different types of objects can be used as target objects. In most cases, content items in RedDot LiveServer (type="content") or snippets (type="content-snippet") are used as target objects. Snippets can include RedDot pages from RedDot CMS, for example, that are composed when publishing a Web site. Snippets can be used in one or more content items in RedDot LiveServer. It may also be helpful to use other objects as target objects for tag assignments, depending on the project requirements. Accordingly, target objects and tags only have loose links in RedDot LiveServer and are identified by the following information:

type Type of target object. RedDot LiveServer assumes administration of relational integrity for types "content" and "content-snippet", particularly for the deletion of tag assignments.

guid Globally unique identifier for the target object. The project and content parameters are used as alternatives for content in RedDot LiveServer.

variant/locale Variant within the target object. For content items and snippets in RedDot LiveServer, the locale parameter is used for the language variant to which the assigned tag refers.

project Project in RedDot LiveServer where the target object is located or to which it refers.

Tags and Their Types Each tag is identified by its name. RedDot LiveServer can store additional information for tags, such as how a given tag is used. In particular, each tag has a type that enables filtering for various actions. You can assign user-defined types for tags. The following predefined types are available:

community Default type assigned if no other value is specified. Used for non-predefined tags that an end user assigns.

editorial Used for tags that are created by an editor or administrator.

Special case: Voting Voting in RedDot LiveServer is used for ranking - rating target objects with a predefined rank. From a technical perspective, voting can be considered a special form of tagging.

The idea is to define a tag for each predefined rank, with an appropriate weight assigned to the rank. Submitting a vote then involves assigning one of these tags to the corresponding target object. Of course, multiple assignment is possible in this case. The tag weight is transferred to the weight of the tag assignment by default.

Data consolidation is used to determine the voting result (number, distribution, average). During each data consolidation, both the number of data records and their respective weights are counted. Alternatively, the consolidation type can be used to define consolidation by target object instead of consolidation by tag. The consolidated data is displayed using the Tagging DynaMent in mode="getConsolidatedData". This makes it possible to find answers to the following questions, for example, without generating a high system load:

408


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

How many content items were ranked? (Consolidation type: content target object, grand total)

How are the rankings distributed? (Consolidation type: tag, display by weight or number)

What is the average ranking of a content?

What are the top content items?

Defining Tags ('defineTags')

Purpose

You can use the Tagging DynaMent in "defineTags" mode to create and change tags in the database.

Normally, tags are created automatically in the background whenever they are assigned. You only have to define tags explicitly if you want to save additional information for a tag, such as a type to enable filtering for different actions. Predefined types are community and editorial.

Syntax

<rde-dm:tagging mode ="defineTags" storage-project ="{project name}" > <rde-rd:tag mode="[update|create|set]"> <name>{tagname}</name> <type>{community|editorial}</type> <author>{username}</author> <description>{description}</description> <weight>{weight}</weight> <rubrics> <rubric>{category name}</rubric> ... </rubrics> </rde-rd:tag>

....

</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "defineTags".

<storage-project> Name of the project where the tags are saved.

409


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Child Elements

The Tagging DynaMent in "defineTags" mode has one child element.

<rde-rd:tag> Child element to define a tag. You can specify multiple elements.

mode (optional) Mode to use for writing the tag. Possible values:

"update": If the tag already exists, it is updated with the fields specified in the other elements. If the tag does not exist, an error is raised.

"create": If the tag does not exist yet, it is created using the fields specified in the other elements. If the tag already exists, an error is raised.

"set": Either an "update" or a "create" is carried out, depending on whether or not the tag already exists.

Value if nothing is specified: "update".

<name> Tag name.




<author> (optional) User name of tag creator.

<description> (optional) Description of the tag.

<weight> (optional) Integer that defines the tag weight for voting.

<rubrics> (optional) List of tag categories in individual <rubric> elements.

<rubric> (optional) Name of an individual tag category.

Result

The specified tags are created or changed.

410


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The Tagging DynaMent's information, warning, and error messages begin with 35 in the thousands' place. You can send the return codes with the standard parameter result-attribute. In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:

Example: Defining Tags

<rde-dm:tagging mode="defineTags" storage-project="demo" > <rde-rd:tag mode="set"> <name>sports</name> <type>editorial</type> </rde-rd:tag> <rde-rd:tag mode="set"> <name>politics</name> <type>editorial</type> </rde-rd:tag>

</rde-dm:tagging>

In this example, two tags are defined in the demo project.


-35333 Cannot locate tagging configuration service

-35334 Cannot locate tagging configuration

411


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Tags ('getTags')

Purpose

You can use the Tagging DynaMent in "getTags" mode to read all the tags that meet the filter criteria specified in the <rde-rd:tag-filter> child element.

Syntax

<rde-dm:tagging mode ="getTags" storage-project ="{project name}" metainfo ="[tag-name|tag]" chunksize ="{number of records}" chunk ="{chunk number}" > <rde-rd:tag-filter> <rde-rd:tags> <rde-rd:tag-name>{tagname}</rde-rd:tag-name> ... </rde-rd:tags> <type>[community|editorial]</type> <lastChange op="[eq|gt|lt|ge|le]" dateformat-in="{date format}"> {date} </lastChange> ... <rubrics> <rubric>{category name}</rubric> ... </rubrics> <authors> <author>{author name}</author> ... </authors> <whitelist match="[false|true]"> configuration-project ="{project name}" tagging-configuration ="{tagging configuration}" suggestion-list-variant="{variant name}" </whitelist> <blacklist match="[true|false]"> configuration-project ="{project name}" tagging-configuration ="{tagging configuration}" </blacklist>

</rde-rd:tag-filter>

</rde-dm:tagging>

412


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Parameters

mode Mode of the Tagging DynaMent, here "getTags".

storage-project RedDot LiveServer project where the tags are saved.

metainfo (optional) Type of output. Possible values:

"tag-name": Only the names of the assigned tags are returned.

"tag": The full XML structure of the tags is returned.

Value if nothing is specified: "tag-name"

chunksize (optional) Maximum number of content items that may be included in the result of the DynaMent as defined by the chunksize parameter. If the number of entries selected is greater than chunksize, then the remaining entries are displayed in the next chunk after sorting. Possible values: "1" to "100" Value if nothing is specified: "10"

chunk (optional) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. Value if nothing is specified: "1"

Child Elements

The Tagging DynaMent in "getTags" mode has one child element.

<rde-rd:tag-filter> (optional) Child element with various optional filter criteria to restrict the set of tags to return. All the specified filter criteria must be fulfilled for a tag to be returned. If no filter is specified, all tags are returned.

<rde-rd:tags> List of tag names in individual <rde-rd:tag-name> child elements.

<rde-rd:tag-name> Tag name. You can also use the wildcard "*".


413


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



<lastChange> Date the tag was last changed. You can specify several elements to define a date range.

op Operator used to compare the last change date of the tag with the specified date. Possible values:

"eq": The date is identical to the specified date.

"gt": The date is later than the specified date.

"lt": The date is earlier than the specified date.

"ge": The date is later than or equal to the specified date.

"le": The date is earlier than or equal to the specified date.

dateformat-in Defines which date format to use for date information in the <lastChange> child element. The syntax is based on that used for standard Java class java.text.SimpleDateFormat. Value if nothing is specified: "yyyy-MM-dd HH:mm:ss"

<rubrics> List of tag categories in single <rubric> elements.

<rubric> Name of an individual tag category.

<authors> List of user names in individual <author> elements.

<author> User name of tag creator.

<whitelist> Child element for a suggestion list as a filter criterion: Whether or not a tag is returned depends on whether it is contained in the variant of the suggestion list specified in the tagging/voting configuration defined in the Tags for Suggestion Lists area.

match Defines whether the tags have to be contained in the suggestion list.

"false": Tags that are not contained in the suggestion list are returned.

"true": Tags that are contained in the suggestion list are returned.

configuration-project RedDot LiveServer project containing the tagging/voting configuration.

tagging-configuration Name of a tagging/voting configuration on RedDot LiveServer.

414


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

suggestion-list-variant Name of a variant from the suggestion list defined in the tagging/voting configuration. Only the tags in this variant are searched. If nothing is specified: All tags of all variants of the suggestion list are searched.

<blacklist> Child element for blacklisted tags as a filter criterion: Whether or not a tag is returned depends on whether it is contained in the blacklisted tags specified in the tagging/voting configuration defined in the Blacklisted Tags area.

match Defines whether the tags have to be contained in the blacklisted tags.

"false": Tags that are not contained in the blacklisted tags are returned.

"true": Tags that are contained in the blacklisted tags are returned.



Result

The name or the XML structures of the read tags are returned, depending on the setting in the metainfo parameter.

Error Handling


Deleting Tags ('deleteTags')

Purpose

You can use the Tagging DynaMent in "deleteTags" mode to delete all tags from the database that meet the filter criteria specified in the <rde-rd:tag-filter> child element. All tag assignments of the deleted tags are also deleted. These tag assignments are also deleted from all data consolidations that are not finished yet.




415


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:tagging mode ="deleteTags" storage-project ="{project name}" > <rde-rd:tag-filter> <rde-rd:tags> <rde-rd:tag-name>{tagname}</rde-rd:tag-name> ... </rde-rd:tags> <type>[community|editorial]</type> <lastChange op="[eq|gt|lt|ge|le]" dateformat-in="{date format}"> {date} </lastChange> ... <rubrics> <rubric>{category name}</rubric> ... </rubrics> <authors> <author>{author name}</author> ... </authors> <whitelist match="[false|true]"> configuration-project ="{project name}" tagging-configuration ="{tagging configuration}" suggestion-list-variant="{variant name}" </whitelist> <blacklist match="[true|false]"> configuration-project ="{project name}" tagging-configuration ="{tagging configuration}" </blacklist>

</rde-rd:tag-filter>

</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "deleteTags".

storage-project Name of the project where the tags are saved.

416


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Child Elements

The Tagging DynaMent in "deleteTags" mode has one child element.

<rde-rd:tag-filter> (optional) Child element with various optional filter criteria to restrict the set of tags to be deleted. All the specified filter criteria must be fulfilled for a tag to be deleted. If no filter is specified, no tags are deleted.

<rde-rd:tags> List of tag names in individual <rde-rd:tag-name> child elements.

<rde-rd:tag-name> Tag name. You can also use the wildcard "*".




<lastChange> Date the tag was last changed. You can specify several elements to define a date range.

op Operator used to compare the last change date of the tag with the specified date. Possible values:

"eq": The date is identical to the specified date.

"gt": The date is later than the specified date.

"lt": The date is earlier than the specified date.

"ge": The date is later than or equal to the specified date.

"le": The date is earlier than or equal to the specified date.

dateformat-in Defines which date format to use for date information in the <lastChange> child element. The syntax is based on that used for standard Java class java.text.SimpleDateFormat. Value if nothing is specified: "yyyy-MM-dd HH:mm:ss"

<rubrics> List of tag categories in single <rubric> elements.

<rubric> Name of an individual tag category.

<authors> List of user names in individual <author> elements.

<author> User name of tag creator.

<whitelist> Child element for a suggestion list as a filter criterion: Whether or not a tag is deleted depends on whether it is contained in the variant of the suggestion list specified in the tagging/voting configuration defined in the Tags for Suggestion Lists area.

417


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

match Defines whether the tags have to be contained in the suggestion list.

"false": Tags that are not contained in the suggestion list are deleted.

"true": Tags that are contained in the suggestion list are deleted.



suggestion-list-variant Name of a variant from the suggestion list defined in the tagging/voting configuration. Only the tags in this variant are searched. If nothing is specified: All tags of all variants of the suggestion list are searched.

<blacklist> Child element for blacklisted tags as a filter criterion: Whether or not a tag is deleted depends on whether it is contained in the blacklisted tags specified in the tagging/voting configuration defined in the Blacklisted Tags area.

match Defines whether the tags have to be contained in the blacklisted tags.

"false": Tags that are not contained in the blacklisted tags are deleted.

"true": Tags that are contained in the blacklisted tags are deleted.



Result

The specified tags are deleted.

Error Handling





418


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Renaming Tags ('renameTag')

Purpose

You can use the Tagging DynaMent in "renameTag" mode to change the name of a tag. It helps you identify typing errors and similar tags.

The tag name is changed automatically for all tag assignments. The change is reflected in all future evaluations. If a tag with the new name already exists, you can use the allow-merge parameter to rename the tag and change all the existing tag assignments.

Syntax

<rde-dm:tagging mode ="renameTag" storage-project ="{project}" allow-merge ="[true|false]" > <rde-rd:tag-name-old>{tagname}</rde-rd:tag-name-old>

<rde-rd:tag-name-new>{tagname}</rde-rd:tag-name-new>

</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "renameTag".

storage-project Name of the project where the tag is saved.

allow-merge (optional) Defines the system response if a tag with the new name already exists. Possible values:

"true": The tag is renamed. Existing tag assignments are changed. This setting may result in high system loads. You should therefore use it sparingly.

"false": The tag is not renamed.


419


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Child Elements

The Tagging DynaMent in "renameTag" mode has two child elements.

<rde-rd:tag-name-old> Previous name of the tag.

<rde-rd:tag-name-new> New name of the tag.

Result

The name of the tag is changed.

Error Handling


Assigning Tags ('assignTags')

Purpose

You can use the Tagging DynaMent in "assignTags" mode to assign tags to targets.

When you specify the tagging/voting configuration, you define the consolidation rules that will apply to tag assignment in this configuration. When a tag is assigned, a tag with type community is created automatically if it does not exist yet.




420


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:tagging mode ="assignTags" configuration-project ="{project name}"

tagging-configuration ="{tagging configuration}" >

<rde-rd:targets> <rde-rd:target>

<type>[content|content-snippet|{type name}]</type> <project>{project}</project> <content>{content}</content> <guid>{guid}</guid> <variant>{variant}</variant> <locale>{locale}</locale> <owner>{content; content;...}</owner>

</rde-rd:target> ...

</rde-rd:targets> <rde-rd:tags> <rde-rd:tag-name> {tagname} </rde-rd:tag-name> ... </rde-rd:tags>

</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "assignTags".



Child Elements

The Tagging DynaMent in "assignTags" mode has two child elements.

<rde-rd:targets> List of target objects that are assigned tags, in individual <rde-rd:target> elements.



421


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8










<owner> (optional, not evaluated for type="content") Content item or semicolon-separated list of content items in RedDot LiveServer in the project specified in the project parameter. If you use this element, the defined tag assignment is deleted from the database automatically when the last of the specified content items is deleted (relational integrity). If the target objects have type "content-snippet", you do not need to specify this element if the owner relationship was already established with the content-snippet element during import with the Import DynaMent.

<rde-rd:tags> List of tags that are assigned to target objects in individual <rde-rd:tag-name> elements.

<rde-rd:tag-name> Single tag assigned to the target objects.

Result

The specified tags are assigned to all specified target objects. Tags that do not exist yet are created automatically with type community.

422


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling


For more information about assigning tags with the Import DynaMent, see the separate section.


Import DynaMent (Page 140)Defining and Assigning Tags (Page 155)

Example: Assigning a Tag

<rde-dm:tagging mode="assignTags" configuration-project="tagging-project" tagging-configuration="taggingConfig"> <rde-rd:targets> <rde-rd:target> <project>html-demo</project> <type>content</type> <content>index.htm</content> <locale>en</locale> </rde-rd:target> <rde-rd:target> <project>html-demo</project> <type>content</type> <content>news.htm</content> <locale>en</locale> </rde-rd:target> </rde-rd:targets> <rde-rd:tags> <rde-rd:tag-name>sports</rde-rd:tag-name> </rde-rd:tags>

</rde-dm:tagging>

In this example, the sports tag is assigned to content items index.htm and news.htm.


-35333 Cannot locate Tagging configuration service

-35334 Cannot locate Tagging configuration

423


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Deleting Tag Assignments ('unassignTags')

Purpose

You can use the Tagging DynaMent in "unassignTags" mode to delete tags from targets. The tag assignments are also deleted from all data consolidations that are not finished yet.

Syntax

<rde-dm:tagging mode ="unassignTags"

configuration-project ="{project name}" tagging-configuration ="{tagging configuration}"

uniqueness-values ="{value;value;..." >

<rde-rd:targets> <rde-rd:target>

<type>[content|content-snippet|{type name}]</type> <project>{project}</project> <content>{content}</content> <guid>{guid}</guid> <variant>{variant}</variant> <locale>{locale}</locale>

<owner>{content; content;...}</owner> </rde-rd:target> ... </rde-rd:targets> <rde-rd:tags>

<rde-rd:tag-name> {tagname} </rde-rd:tag-name> ...

</rde-rd:tags>

</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "unassignTags".



uniqueness-values (optional) For multiple assignment: List of values that determines which tag assignments will be deleted. The tag assignments whose evaluated uniqueness expression corresponds to one

424


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

of the specified values are deleted. If left blank or not specified: No restrictions. The assignments of all specified tags are deleted for all specified target objects.

Child Elements

The Tagging DynaMent in "unassignTags" mode has two child elements.

<rde-rd:targets> List of target objects whose tag assignments will be deleted, in individual <rde-rd:target> elements.

<rde-rd:target> Single target object whose tag assignments will be deleted.












425


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-rd:tags> List of tags whose assignments to target objects will be deleted, in individual <rde-rd:tag-name> elements.

<rde-rd:tag-name> Single tag whose assignment will be deleted.

Result

The assignments of the specified tags are deleted for all specified target objects.

Error Handling


Example: Deleting a Tag Assignment

<rde-dm:tagging mode="unassignTags" configuration-project="tagging-project" tagging-configuration="taggingConfig"> <rde-rd:targets>

<rde-rd:target> <project>html-demo</project>

<type>content</type> <content>index.htm</content> <locale>en</locale> </rde-rd:target> </rde-rd:targets> <rde-rd:tags> <rde-rd:tag-name>news</rde-rd:tag-name> </rde-rd:tags>

</rde-dm:tagging>

In this example, the news tag is removed from content item index.htm.


-35333 Cannot locate Tagging configuration service

-35334 Cannot locate Tagging configuration

426


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Suggesting Tags ('suggestTags')

Purpose

You can use the Tagging DynaMent in "suggestTags" mode to suggest a list of tags based on the specified tagging/voting configuration and the first character entered during tag assignment.

You should use this mode to avoid tag confusion and typing errors during tag assignment. To keep the suggestion lists to a manageable size, you can use the maxtags parameter to limit the number of suggested tags. The set of possible tags is specified by the settings in the tagging/voting configuration for the tags for suggestion lists. You can also restrict the selections to one or more categories.

Syntax

<rde-dm:tagging mode ="suggestTags"

configuration-project ="{project name}" tagging-configuration ="{tagging configuration}"

suggestion-list-variant ="{variant name}" maxtags ="{1-n}"

item-tag ="[{tagname=|notag]"

> <rde-rd:tag-name>{tagname}</rde-rd:tag-name>

<rde-rd:rubrics> <rde-rd:rubric>{category name}</rde-rd:rubric>

...

</rde-rd:rubrics>

</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "suggestTags".


tagging-configuration Name of a tagging/voting configuration on RedDot LiveServer. You can only add tags to the DynaMent result that correspond to the tag settings for suggestion lists in this configuration.

427


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

suggestion-list-variant (optional) Name of a variant from the suggestion list defined in the tagging/voting configuration. Only the tags in this variant are searched. If nothing is specified: All tags of all variants of the suggestion list are suggested.

maxtags (optional) Maximum number of tags to suggest. Value if nothing is specified: "20"

item-tag (optional) Tag name of the XML element that surrounds each tag in the result.



Child Elements

The Tagging DynaMent in "suggestTags" mode has two child elements.

<rde-rd:tag-name> First character of the tag name to be entered.

<rde-rd:rubrics> (optional) List of categories in individual <rde-rd:rubric> elements to restrict the set of proposed tags.

<rde-rd:rubric> (optional) Name of an individual category. Only tags to which one or more categories have been assigned are suggested.

Result

A list of suggested tags is returned. Each individual result tag is enclosed by the tag specified in the item-tag parameter.

Error Handling





428


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Tag Assignments ('getAssignments')

Purpose

You can use the Tagging DynaMent in "getAssignments" mode to read selected tag assignments and their metadata. You can use the <rde-rd:assignment-filter> child element to restrict the selection. You can use the fields saved directly during tag assignment (assignment time, assigning user, target object) as selection criteria, as well as the attributes specified as metadata for tag assignments in the active tagging configuration.

Syntax

<rde-dm:tagging mode ="getAssignments"

configuration-project ="{project name}"

tagging-configuration ="{tagging-configuration}" chunksize ="{number of records}" chunk ="{chunk number}" maxhits ="{number}" ignore-constraints ="[no|yes|completely]" dateformat-out ="{date format}" dateformat-in ="{date format}"

context-mode ="[mixed|cdata|none]" item-tag ="[{tagname}|notag]"

>

<rde-rd:assignment-filter>

<rde-rd:assignmenttime op ="[eq|ne|lt|gt|le|ge]">...

</rde-rd:assignmenttime>

<rde-rd:user-filter>{login name}</rde-rd:user-filter>

<rde-rd:target> <type>[content|content-snippet|{type name}]</type> <project>{project}</project> <content>{content}</content> <guid>{guid}</guid> <variant>{variant}</variant> <locale>{locale}</locale>

<owner>{content; content;...}</owner> </rde-rd:target>

<rde-rd:tag-assignment> <rde-rd:constraint> {constraint expression} </rde-rd:constraint>


</rde-rd:assignment-filter>

</rde-dm:tagging>

429


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




Parameters

mode Mode of the Tagging DynaMent, here "getAssignments".





maxhits (optional) Maximum number of hits returned (1 – n). If nothing is specified: No restriction; all hits are returned.

ignore-constraints (optional) Defines whether or not to take content constraints into account when displaying the hits in the search result.



"completely": The content constraints are not checked. Content is found regardless of whether the content constraints are met and shown in the search result. This setting allows you to accelerate the search if you do not have to check content constraints.


430


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

dateformat-in (optional) Defines which date format to use for date information in the <rde-rd:assignmenttime> child element. The syntax is based on that used for standard Java class java.text.SimpleDateFormat. Value if nothing is specified: "yyyy-MM-dd HH:mm:ss"

dateformat-out (optional) Defines the date format to use for formatting dates in the DynaMent result. The syntax is based on that used for standard Java class java.text.SimpleDateFormat. Value if nothing is specified: "yyyy-MM-dd HH:mm:ss"

context-mode

Way in which the metadata is included in the DynaMent's result XML.








Value if nothing is specified: "item-tag"

Child Elements

The Tagging DynaMent in "getAssignments" mode has one optional child element.

<rde-rd:assignment-filter> (optional) You can specify filter criteria in additional elements within this child element to restrict the result.

<rde-rd:assignmenttime> Time when the tag was assigned to the target object.

op Operator used to compare the assignment time of the tag with the assignment time specified above. Possible values:

"eq": The assignment time is equal to the specified time.

"ne": The assignment time is not equal to the specified time.

"lt": The assignment time is earlier than the specified time.

"gt": The assignment time is later than the specified time.

"le": The assignment time is earlier than or equal to the specified time.

"ge": The assignment time is later than or equal to the specified time.

431


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-rd:user-filter> (optional) Specifies a user name. Only target objects that the specified user has assigned are included in the result.













<rde-rd:tag-assignment> (optional) Child element for additional filter constraints.

<rde-rd:constraint> Constraint expression you can use to filter the attributes collected during assignment. These are the attributes you defined as Metadata for tag assignments in the tagging configuration. The syntax is equivalent to an

432


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Attribute DynaMent in "condition" mode. The only difference is: the attributes are flagged with a leading exclamation point. Example: [#!session:attr1#] gt "5"

Result

A list of target objects is returned. The list is enclosed by an element that is specified in the tag parameter. Each individual result is enclosed by the tag specified in the item-tag parameter.

Error Handling





433


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Returning Tag Assignments and Their Metadata

<rde-dm:tagging mode="getAssignments" configuration-project="tagging" tagging-configuration="sampleConfig"> <rde-rd:assignment-filter> <rde-rd:tag-filter> <rde-rd:tags> <rde-rd:tag-name>Sport</rde-rd:tag-name> </rde-rd:tags> </rde-rd:tag-filter> </rde-rd:assignment-filter>

</rde-dm:tagging>

The result: Information is output for the tags, the target objects, and the assignments themselves.

<tag-assignments> <assignment> <tag> <name>Sport</name> <type>community</type> <storage-project>t01</storage-project> <author>user</author> <description></description> <weight>1</weight> <lastChange value="1227168627680">2008-11-20 09:10:27 </lastChange> <rubrics /> </tag> <target> <guid></guid> <owner>index.html</owner> <project>html-demo</project> <variant>de</variant> <target-type>content</target-type> <owner-type>content</owner-type> </target> <assignment-metadata> <login>user01</login>

<assignmenttime> 2008-11-20 09:10:27

</assignmenttime> </assignment-metadata> </assignment> <assignment> <tag> <name>Sport</name> <type>community</type> <storage-project>t01</storage-project> <author>user</author> <description></description> <weight>1</weight> <lastChange value="1227168627680"> 2008-11-20 09:10:27 </lastChange>

434


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rubrics /> </tag> <target> <guid>snippet-01</guid> <owner>sport-overview.html</owner> <project>html-demo</project> <variant>de</variant> <target-type>content_snippet</target-type> <owner-type>content</owner-type> </target> <assignment-metadata> <login>admin</login> <assignmenttime> 2008-11-20 09:10:30 </assignmenttime> <attributes> <attribute path="profile.level" source="user"> <values> <value>0</value> </values> </attribute> <attribute path="favorites.entryPage" source="session"> <values> <value>news.html</value> </values> </attribute> <attribute path="history.exitPoints" source="request"> <values> <value>5</value> <value>7</value> </values> </attribute> </attributes> </assignment-metadata> </assignment>

</tag-assignments>

435


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Assigned Tags ('getAssignedTags')

Purpose

The Tagging DynaMent in "getAssignedTags" mode lets you read the tags that are assigned to a target object.

You can use the <rde-rd:assignment-filter> child element to restrict the set of tags. The assigning user and any attributes used as metadata for tag assignments in the active tagging/voting configuration can be used as selection criteria.

Syntax

<rde-dm:tagging mode ="getAssignedTags" configuration-project ="{project name}"

tagging-configuration ="{configuration name}" metainfo ="[tag-name|tag]" sortedby ="{field name of tag}" sortorder ="[asc|desc]" dateformat-out ="{date format}"

>


<owner>{content; content;...}</owner>

</rde-rd:target>


<rde-rd:user-filter>{login name}</rde-rd:user-filter> <rde-rd:tag-assignment>

<rde-rd:constraint> {constraint expression} </rde-rd:constraint>

</rde-rd:tag-assignment> </rde-rd:assignment-filter>

</rde-dm:tagging>




436


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Tagging DynaMent, here "getAssignedTags".



metainfo (optional) Type of output. Possible values:

"tag-name": Only the names of the assigned tags are output.

"tag": The full XML structure of the tags is output.

Value if nothing is specified: "tag-name"

sortedby (optional) Element name of the XML structure of the tag whose values you want to sort alphanumerically in the result. If nothing is specified: Sequence of content in the result is not defined.

sortorder (optional, only effective when used together with sortedby) Sort order of the entries in the result:

"asc": ascending order

"desc": descending order



Child Elements

The Tagging DynaMent in "getAssignedTags" mode has two child elements.

<rde-rd:target> Target object whose assigned tags will be read.





437


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8








<rde-rd:assignment-filter> (optional) This child element can contain filter constraints in additional elements for the assigned tags you want to include in the result.

<rde-rd:user-filter> (optional) Specifies a user name. Only tags that the specified user has assigned are included in the result.


<rde-rd:constraint> Constraint expression you can use to filter the attributes collected during assignment. These are the attributes you defined as Metadata for tag assignments in the tagging configuration. The syntax is equivalent to an Attribute DynaMent in "condition" mode. The only difference is: the attributes are flagged with a leading exclamation point. Example: [#!session:attr1#] gt "5"

Result

The name or the XML structures of the read tags are returned, depending on the setting in the metainfo parameter.

438


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling


Example: Reading All Tags Assigned to a Content Item

<rde-dm:tagging mode="getAssignedTags" configuration-project="demo" tagging-configuration="taggingConfig" metainfo="tag-name" sortedby="name" sortorder="asc"> <rde-rd:target> <project>html-demo</project> <type>content</type> <content>index.htm</content> <locale>en</locale> </rde-rd:target>

</rde-dm:tagging>

The result:

<tags>

<tag-name>sports</tag-name>

<tag-name>news</tag-name>

</tags>




439


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Assigned Target Objects ('getTargets')

Purpose

The Tagging DynaMent in "getTargets" mode lets you read the target objects that are assigned to a tag.

You can use the <rde-rd:assignment-filter> child element to restrict the set of target objects. You can use the fields saved directly during tag assignment (assignment time, assigning user, target object) as selection criteria, as well as the attributes specified as metadata for tag assignments in the active tagging configuration.

You can use child element <rde-rd:include-modes> to add additional metadata in the result, like in the Query and Target DynaMents, provided the target object is a content item.

Syntax

<rde-dm:tagging mode ="getTargets"

configuration-project ="{project name}"

tagging-configuration ="{tagging-configuration}" sortedby ="assignmenttime" sortorder ="[asc|desc]"

chunksize ="{number of records}" chunk ="{chunk number}" maxhits ="{number}" ignore-constraints ="[no|yes|completely]" dateformat-out ="{date format}" dateformat-in ="{date format}" cache-id-attribute ="{attribute name}" cache-id ="{cache id}" item-tag ="[{tagname}|notag]"

>

<rde-rd:tag-name>{tagname}</rde-rd:tag-name>


<rde-rd:assignmenttime op ="[eq|ne|lt|gt|le|ge]">...

</rde-rd:assignmenttime>

<rde-rd:user-filter>{login name}</rde-rd:user-filter>


<owner>{content; content;...}</owner> </rde-rd:target>

<rde-rd:tag-assignment> <rde-rd:constraint> {constraint expression} </rde-rd:constraint>



440


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-rd:include-modes> <rde-rd:include-mode

target-type =">[content|content-snippet|{typename}]" include-mode ="[{include-mode},{tagname};]" context-tags ="[{tagname},{context-mode};]" context-mode ="[mixed|cdata|none]" />

.... </rde-rd:include-modes>

</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "getTargets".



sortedby (optional) Element used to sort the content items in the result.

"assignmenttime": Time when the tag was assigned to the target object.

If nothing is specified: Sequence of content in the result is not defined.

sortorder (optional, only effective when used together with sortedby) Sort order of the entries in the result:






441


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


ignore-constraints (optional) Defines whether or not to take content constraints into account when displaying the hits in the search result.



"completely": The content constraints are not checked. Content is found regardless of whether the content constraints are met and shown in the search result. This setting allows you to accelerate the search if you do not have to check content constraints.


dateformat-in (optional) Defines which date format to use for date information in the <rde-rd:assignmenttime> child element. The syntax is based on that used for standard Java class java.text.SimpleDateFormat. Value if nothing is specified: "yyyy-MM-dd HH:mm:ss"


cache-id-attribute (optional) Name of an attribute with optional additional source specification (default: request). After the Target DynaMent has been executed, the search result cache key under which the result of the DynaMent is held in the cache is written to the specified attribute. The name can be used, for instance, when the DynaMent is called again, to reuse the entry with the help of the cache-id parameter.

cache-id (optional) Specifies the search result cache key under which the result of the DynaMent is held in the cache. This key is read from the value of the cache-id-attribute parameter. If a value is specified for the parameter and when the DynaMent is called, the entry to the search result cache is searched for and used.




Value if nothing is specified: "item-tag"

442


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Child Elements

The Tagging DynaMent in "getTargets" mode has three child elements.

<rde-rd:tag-name> Name of the tag assigned to the target objects.


<rde-rd:assignmenttime> Time when the tag was assigned to the target object. Only target objects to which the tag was assigned at the specified time are included in the result.









<rde-rd:target> Element that restricts the set of target objects included in the result.








443


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8







<rde-rd:include-modes> (optional) List for adding data for target objects in individual <rde-rd:include-mode> elements.

<rde-rd:include-mode> Individual element for returning additional data for target objects.

target-type Type of target object. Possible values:

"content": Content item in RedDot LiveServer.

include-mode Selects which information about the content is added to the DynaMent result. The following values are possible:



"content-identifier": Name of the content in the XML name element.

444


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


"content": Only for text type (XML, HTML, XSL, SCRIPT): The actual content data for the respective language.


Every requested information item increases the runtime if the result is not already available in the cache. Therefore, we recommend using the include-mode parameter for information that needs to be evaluated or presented to the user. Value if nothing is specified: "content,notag"

context-tags Determines which tag should be added to the result of the DynaMent and how. A single tag name, or multiple tag names separated by semicolons, which are transferred from each content item found to the resulting XML of the DynaMent. Notes: To be able to use context tags, you have to select at least the context-tags mode in the include-mode parameter. A separate context-mode can be specified for each individual tag name, if a value other than that of the global context-mode parameter is required. If you specify "none", then an individual context-mode must be specified for each tag so that the tag will appear in the result. Supported syntax: "tagname1,context-mode1;tagname2;tagname3,context-mode3" Only the content of the first content tag is returned with the specified name. If the tag includes child elements, they will be returned as well. You can use this function, for example, to add content information or information on displaying individual content items to the resulting XML and present it to the user. Value if nothing is specified: "title,[specification from context-mode]" Value if no value is specified for the context mode parameter: "title,mixed"

context-mode The way in which the content of the context-tags parameter is integrated in the result XML of the DynaMent. You can specify the context-mode parameter either globally or separately for each individual tag name of context-tags.





445


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

A list of target objects is returned. The list is enclosed by an element that is specified in the tag parameter. Each individual result is enclosed by the tag specified in the item-tag parameter.

Error Handling


Example: Reading Target Objects

<rde-dm:tagging mode="getTargets" configuration-project="demo" tagging-configuration="taggingConfig"> <rde-rd:tag-name>sports</rde-rd:tag-name>

</rde-dm:tagging>

In this example, the target objects of the sports tag are read.

The result:

<tag-targets>

<target>

<guid />

<owner>index.htm</owner>

<project>html-demo</project>

<variant>en</variant>

<target-type>content</target-type>

<owner-type>content</owner-type>

</target>

<target>

<guid />

<owner>news.htm</owner>

<project>html-demo</project>

<variant>en</variant>

<target-type>content</target-type>

<owner-type>content</owner-type>

</target>

</tag-targets>




446


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Consolidating Tagging Data ('consolidateData')

Purpose

You can use the Tagging DynaMent in "consolidateData" mode to create consolidated data from selected tag assignments and provide it in XML format for display in tag clouds or for reports.

In contrast to "getConsolidatedData" mode, data that has already been consolidated at runtime is not accessed. Instead, the data for the selected tag assignments is consolidated directly using the database. Note that this operation can take some time.

You can use the <rde-rd:assignment-filter> child element to restrict the set of tags. You can use the fields saved directly during tag assignment (assignment time, assigning user, target object) as selection criteria, as well as the attributes specified as metadata for tag assignments in the active tagging configuration. If your selection criteria are included in a defined index, this will speed up consolidation considerably.

Syntax

<rde-dm:tagging mode ="consolidateData" configuration-project ="{project}" tagging-configuration ="{tagging configuration}" aggregationtype ="[tag|target]" assignmenttime ="{date within reporting period}" qualifying-values ="{value;value;...}" mulitcount ="[true|false]"

scaling-range ="{first}..{last}" sortedby ="[tag|assignments| qualifying-value, tag| qualifying-value, assignment]" sortorder ="[asc|desc]" maxhits ="{number}" dateformat-in ="{date format}"

dateformat-out ="{date format}" cache-id-attribute ="{attribute name}"

cache-id ="{cache id}" >

<rde-rd:assignment-filter> <rde-rd:assignmenttime op ="[eq|ne|lt|gt|le|ge]">... </rde-rd:assignmenttime> <rde-rd:user-filter>{login name}</rde-rd:user-filter> <rde-rd:target> <type>[content|content-snippet|{type name}]</type> <project>{project}</project> <content>{content}</content> <guid>{guid}</guid> <variant>{variant}</variant> <locale>{locale}</locale> <owner>{content; content;...}</owner> </rde-rd:target> <rde-rd:tag-assignment> <rde-rd:constraint> {constraint expression}

447


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

</rde-rd:constraint> </rde-rd:tag-assignment>


</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "consolidateData".



aggregation-type (optional) Aggregation type used to consolidate data:

"tag": Consolidation by tags.

"target": Consolidation by target objects. This setting is used particularly to answer specific questions regarding voting on target objects.

Value if nothing is specified: "tag"

assignmenttime (optional) Date and time to select a reporting period. The format is specified using the dateformat-in parameter. The following options are available:

"{time_value}": Reporting period in which the date and time are contained.

"*": The reporting period for time interval Perpetual is sent in the <report-data> element.

"[gt|ge|lt|le] {time_value}": All reporting periods whose end time (lt, le) or start time (gt, ge) matches are returned, each in a separate <report-data> element.

"{time_value}...{time_value}": All reporting periods that lie within the specified period are returned, each in a separate <report-data> element.

If nothing is specified: Current date/time

qualifying-values (optional) Semicolon-separated list of values to restrict the output data records: Only the data records whose attribute values from the grouping settings of the data consolidation rule match one of the specified values are returned.

448


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

multicount (optional) Determines how multiply assigned tags will be taken into account during consolidation.

"true": Multiply assigned tags are taken into account multiple times during consolidation.

"false": Multiply assigned tags are only taken into account once during consolidation.


scaling-range (optional) Specifies the scale limits of the scale in which the data consolidation is displayed (such as the font sizes to use in a tag cloud). RedDot LiveServer forms the frequency values for tag assignment logarithmically in the scale limits. The value range must be greater than zero.

sortedby (optional) Determines the order in which the data lines are displayed. The following values are possible:

"tag": Alphabetically by tag name

"assignments": Numerically by number of assignments

"qualifying-value, tag": Numerically or alphabetically by the value from qualifying-value, depending on the type of the first value. Alphabetically by tag name within identical values.

"qualifying-value, assignments": Numerically or alphabetically by the value from qualifying-value, depending on the type of the first value. Numerically by number of assignments within identical values.





maxhits (optional) Maximum number of data records for each reporting period. The first data records for the defined sort sequence are always included. If nothing is specified: No restriction; all data records are included.

dateformat-in (optional) Defines which date format to use for date information in the assignmenttime parameter. The syntax is based on that used for standard Java class java.text.SimpleDateFormat. Value if nothing is specified: "yyyy-MM-dd HH:mm:ss"


cache-id-attribute (optional) Name of an attribute with optional additional source specification (default: request). If the parameter is defined, a content item containing the DynaMent is created and placed in the cache after the DynaMent runs. The cache key (or content name) used is returned in the specified attribute. This value is always a generated key that the user cannot influence. Example: cache-id-attribute="session:cacheContent" writes the content name to

449


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

session attribute "cacheContent". The name can be used, for instance, when the DynaMent is called again, to reuse the entry with the help of the cache-id parameter. If nothing is specified: No cache entries are created.

cache-id (optional) You can use this parameter to reuse content that was created previously with the Tagging DynaMent, to save runtime. If a content item with this name is available in the cache, the DynaMent returns that content and does not run further.

Child Elements

The Tagging DynaMent in "consolidateData" mode has one optional child element.


<rde-rd:assignmenttime> Time when the tag was assigned to the target object.















450


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8









Result

The consolidated data is put in an XML structure. The <consolidation> child element is flagged with type="rule", as consolidation is predefined.

Error Handling





451


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Calculating Consolidated Data Based on Assignments

<rde-dm:tagging mode="consolidateData" configuration-project="tagging" tagging-configuration="taggingConfig" scaling-range="1..12"

sortedby="tag" sortorder="asc" />

The result:

<consolidated-data> <consolidation type="runtime"> <configuration-project>tagging </configuration-project> <tagging-configuration>taggingConfig </tagging-configuration> <aggregation-type>tag</aggregation-type> <multicount>true</multicount> </consolidation> <periods> <period> <start>2008-11-14 02:08:28</start> <end>2008-11-14 02:08:28</end> </period> </periods> <report-data aggregate-periods="false" assignmenttime="2008-11-14 02:25:42" maxhits="-1" period-end="2008-11-14 02:08:28" period-start="2008-11-14 02:08:28" storage-project="tagging" qualifying-values="" rows="1" scaling-range="1..12" sortedby="tag" sortorder="asc"> <rows> <row> <tag-name>Sport</tag-name> <qualifying-value /> <assignments>1</assignments> <assignments-weight-sum>0 </assignments-weight-sum> <assignments-weight-average>0.00 </assignments-weight-average> <scale>12.00</scale> </row> </rows> </report-data>

</consolidated-data>

452


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Providing Consolidated Tagging Data ('getConsolidatedData')

Purpose

You can use the Tagging DynaMent in "getConsolidatedData" mode to select consolidated tagging data and provide it in XML format, for display in tag clouds or for reports. You can use the optional <rde-rd:target> child element to restrict the set of target objects.

Note: You can determine the target objects that are assigned to a tag using the Tagging DynaMent with mode="getTargets". You can generate links during rendering that point to a content item with the corresponding DynaMent.

Syntax

<rde-dm:tagging mode ="getConsolidatedData" configuration-project ="{project}" tagging-configuration ="{tagging configuration}" consolidation-rule ="{tagging consolidation rule}" assignmenttime ="{date within reporting period}" qualifying-values ="{value;value;...}" aggregate-periods ="[false|true]"

scaling-range ="{first}..{last}" sortedby ="[tag|assignments| qualifying-value, tag| qualifying-value, assignment]" sortorder ="[asc|desc]" maxhits ="{number}" dateformat-in ="{date format}"

dateformat-out ="{date format}" cache-id-attribute ="{attribute name}" cache-id ="{cache id}"

flush-proxy ="[false|true]" >

<rde-rd:target> <type>[content|content-snippet|{type name}]</type> <project>{project}</project> <content>{content}</content> <guid>{guid}</guid> <variant>{variant}</variant> <locale>{locale}</locale> <owner>{content; content;...}</owner>

</rde-rd:target>

</rde-dm:tagging>




453


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the Tagging DynaMent, here "getConsolidatedData".



consolidation-rule Name of a consolidation rule in the specified tagging/voting configuration.


"{time_value}": Reporting period in which the date and time are contained.


"[gt|ge|lt|le] {time_value}": All reporting periods whose end time (lt, le) or start time (gt, ge) matches are returned, each in a separate <report-data> element.

"{time_value}...{time_value}": All reporting periods that lie within the specified period are returned, each in a separate <report-data> element.


qualifying-values (optional) Semicolon-separated list of values to restrict the output data records: Only the data records whose attribute values from the grouping settings of the data consolidation rule match one of the specified values are returned.

aggregate-periods (optional) Determines how the data for multiple reporting periods is returned. Possible values:

"false": Data from multiple reporting periods is returned individually for each period.

"true": Data from multiple reporting periods is aggregated before it is returned.

Value if nothing is specified: "false"

scaling-range (optional) Specifies the scale limits of the scale in which the data consolidation is displayed (such as the font sizes to use in a tag cloud). RedDot LiveServer forms the frequency values for tag assignment logarithmically in the scale limits. The value range must be greater than zero.

sortedby (optional) Determines the order in which the data lines are displayed. The following values are possible:

"tag": Alphabetically by tag name

"assignments": Numerically by number of assignments

454


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"qualifying-value, tag": Numerically or alphabetically by the value from qualifying-value, depending on the type of the first value. Alphabetically by tag name within identical values.

"qualifying-value, assignments": Numerically or alphabetically by the value from qualifying-value, depending on the type of the first value. Numerically by number of assignments within identical values.





maxhits (optional) Maximum number of data records for each reporting period. The first data records for the defined sort sequence are always included. If nothing is specified: No restriction; all data records are included.



cache-id-attribute (optional) Name of an attribute with optional additional source specification (default: request). If the parameter is defined, a content item containing the DynaMent is created and placed in the cache after the DynaMent runs. The cache key (or content name) used is returned in the specified attribute. This value is always a generated key that the user cannot influence. Example: cache-id-attribute="session:cacheContent" writes the content name to session attribute "cacheContent". The name can be used, for instance, when the DynaMent is called again, to reuse the entry with the help of the cache-id parameter. If nothing is specified: No cache entries are created.

cache-id (optional) You can use this parameter to reuse content that was created previously with the Tagging DynaMent, to save runtime. If a content item with this name is available in the cache, the DynaMent returns that content and does not run further.

flush-proxy (optional) Determines when data saved in the proxy can be flushed to the database. Possible values:

"false": Data is flushed to the database at regular intervals.

"true": Data is flushed to the database immediately. This setting results in high system loads. You should therefore use it sparingly.

Value if nothing is specified: "false"

455


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Child Elements

The Tagging DynaMent in "getConsolidatedData" mode has one optional child element.

<rde-rd:target> (optional) Child element to restrict the target objects.












Result

The consolidated data is put in an XML structure. The <consolidation> child element is flagged with type="rule".

456


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling





457


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Reading Consolidated Data

The consolidated data is calculated for a tag assignment on an ongoing basis. The data cannot be retrieved until the attribute proxy has written the collected consolidated data to the database.

<rde-dm:tagging mode="getConsolidatedData" configuration-project="tagging" tagging-configuration="taggingConfig" consolidation-

rule="rule1" />

The result:

<consolidated-data> <consolidation type="rule"> <configuration-project>tagging </configuration-project> <tagging-configuration>taggingConfig </tagging-configuration> <name>rule1</name> <description /> <constraint /> <active>true</active> <last-active>0</last-active> <last-change>0</last-change> <multicount>true</multicount> <aggregation-type>tag</aggregation-type> <qualifyingValues /> <periods> <period active="true" count="1" unit="ever" /> <period active="true" count="1" unit="year" /> <period active="true" count="1" unit="month" /> <period active="true" count="1" unit="day" /> <period active="true" count="1" unit="hour" /> </periods> </consolidation> <periods> <period> <type>hour</type> <start>2008-11-14 02:00:00</start> <end>2008-11-14 03:00:00</end> </period> </periods> <report-data aggregate-periods="false" assignmenttime="2008-11-14 02:25:44" maxhits="-1" period-end="2008-11-14 03:00:00" period-start="2008-11-14 02:00:00" storage-project="tagging" qualifying-values="" rows="1" scaling-range="1..10" sortedby="" sortorder=""> <rows> <row> <tag-name>Sport</tag-name> <qualifying-value /> <assignments>1</assignments> <assignments-weight-sum>0 </assignments-weight-sum> <assignments-weight-average>0.00 </assignments-weight-average> <scale>12.00</scale> </row> </rows>

458


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

</report-data>

</consolidated-data>

Deleting Consolidated Tagging Data ('deleteConsolidatedData')

Purpose

You can use the Tagging DynaMent in "deleteConsolidatedData" mode to delete consolidated data from the database.

Syntax

<rde-dm:tagging mode ="deleteConsolidatedData" configuration project ="{project}" tagging-configuration ="{tagging configuration}" consolidation-rule ="{tagging consolidation rule}" assignmenttime ="{date within reporting period}"

dateformat-in ="{date format}"

</rde-dm:tagging>




Parameters

mode Mode of the Tagging DynaMent, here "deleteConsolidatedData".



consolidation-rule Name of a consolidation rule in the specified tagging/voting configuration.


"{Date + Time}": Reporting period in which the date and time are contained.


459


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"[gt|ge|lt|le] {Date + Time}": All reporting periods whose end time (lt, le) or start time (gt, ge) matches are returned, each in a separate <report-data> element.

"{Date + Time}...{Date + Time}": All reporting periods that lie within the specified period are returned, each in a separate <report-data> element.



Result

The consolidated data is deleted from the database.

Error Handling





460

DynaMent ReferencesTarget DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Target DynaMent

You can use the Target DynaMent to access (multiple) specific content items by comparing content attributes and comparison values.

The Target DynaMent is replaced at runtime by an XML result list containing the contents found.


Use the Target DynaMent to access specific content items and link constraints for content attributes in child element <rde-dm:constraint> (mode="select").

Selectively Accessing Content ('select')

Purpose

You can use the Target DynaMent in "select" mode to select content items from a project and define which of their data will be added to the result of the Target DynaMent. This mode is the default setting for the Target DynaMent.

Content is selected dependent on content attributes and comparison values, such as user attributes of the current session. The applicable constraints are defined in the <rde-dm:constraint> child element. The results of the Target DynaMent are saved in the search engine cache until the defined caching time expires.

Redundant database structures, which can be defined in the project settings, can have a major impact on the execution and result of the Target DynaMent. For more information, see the description of the db-structure parameter.

461


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:target mode ="select" project ="{projectname}" group ="{content group}" locale ="{locale string}"

locale-policy ="[none|default|any]" include-mode ="[{include-mode},{tagname};]" context-tags ="[{tagname},{context-mode};]"

context-mode ="[mixed|cdata|xml|none]" chunksize ="{number of records}"

chunk ="{chunk number}" maxhits ="{number}" sortedby ="{content attribute}" sortorder ="[asc|desc]" confirm ="[chunk|all|{1...n}]" ignore-constraints ="[no|yes|completely]" depth ="[0|1|...n]" attributepath ="{content attribute list}" db-structure ="{db structure}" cache-id-attribute ="{attribute name}" cache-id ="{cache id}"


<rde-dm:constraint> {constraint expression} </rde-dm:constraint>

</rde-dm:target>




Simple Call

<rde-dm:target tag="product-list"> <rde-dm:constraint> content.Country eq "[#user:profile.favorite#]" </rde-dm:constraint>

</rde-dm:target>

Selects all content whose Country attribute value matches the user attribute profile.favorite. Creates an XML element <product-list ...> as a result; the selected content is inserted under the <rde-rd:targetresult-item ...> child element. The content. prefix tells the processor where the content attributes should be used. The quotation marks surrounding the user attribute indicate that a string comparison will be performed. Can be used in the html-demo sample project.

462


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode (optional) Mode of the Target DynaMent, here "select". Default setting; can be omitted.

project (optional) Name of the project from which content will be selected. Value if nothing is specified: Project of the content containing the DynaMent.

group (optional) Name of a content group that is used to restrict content selection. If names of content and content groups are not unique project-wide: Value of the path name of the content group within the content group hierarchy. The path components are separated by slashes (example: demo/countries/countriesxml). If nothing is specified: No restriction to any content group.

locale (optional) Language for which content should be selected and displayed. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. The parameter determines which content attributes are evaluated: Only content that has attribute values in the defined language is selected. The locale parameter also affects the display of the content data of the selected content items. If there is no content data for the selected language in the repository, a replacement language is determined in accordance with the Locale Policy. This is usually the default project language. Value if nothing is specified: User language of the requesting session.

locale-policy (optional) Locale policy to access content data and attribute values for display: If a content item or attribute has no value for the language variant determined by the locale parameter, the value for a different variant is read. Possible settings:







463


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8




"content": Only for text type (XML, HTML, XSL, SCRIPT): The actual content data for the respective language.


Every requested information item increases the runtime if the result is not already available in the cache. Therefore, we recommend using the include-mode parameter for information that needs to be evaluated or presented to the user. Value if nothing is specified: "content,notag"

context-tags (optional) Determines which tags should be added to the result of the Target DynaMent and how. A single tag name, or multiple tag names separated by semicolons, which are transferred from each content item found to the resulting XML of the DynaMent. Notes: To be able to use context tags, you have to select at least the context-tags mode in the include-mode parameter. A separate context-mode can be specified for each individual tag name, if a value other than that of the global context-mode parameter is required. If you specify "none", then an individual context mode must be specified for each tag so that the tag will appear in the result. Supported syntax: "tagname1,context-mode1;tagname2;tagname3,context-mode3" Only the content of the first content tag is returned with the specified name. If the tag includes child elements, they will be returned as well. You can use this function, for example, to add content information or information on displaying individual content items to the resulting XML and present it to the user. Value if nothing is specified: "title,[specification from context-mode]" Value if no value is specified for the context mode parameter: "title,mixed"







464


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

chunksize (optional) Maximum number of content items that may be included in the result of the Target DynaMent as defined by the chunksize parameter. If the number of entries selected is greater than chunksize, then the remaining entries are displayed in the next chunk after sorting. Possible values: "1" to "100" Value if nothing is specified: "10"

chunk (optional) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. The resulting XML element of the Target DynaMent contains the following attributes: previouschunk, nextchunk, lastchunk, hits, chunk, and chunksize,, which can be implemented using XSL scrolling functions. Value if nothing is specified: "1"


sortedby (optional) Path name of a content attribute whose values will be used to sort the content alphanumerically in the result. You can only sort on one of the content attributes specified in the child element <rde-dm:constraint> of the call or that was entered as index for the respective project. Note: If the search is carried out using a redundant database structure and sortedby references an attribute in the database structure, the sorting is performed in the database. Of the sorted result, the first hits are returned up to the maximum number of hits (maxhits). If not, sorting is performed in RedDot LiveServer on the first hits of the unsorted search result. If nothing is specified: Sequence of content in the result is not defined.





confirm (optional) Since the results of the Target DynaMent are not checked for content constraints until delivery, the number of found content items (hits) can exceed the number of items that are actually returned. The confirm parameter defines how the content constraints will be checked for the found content items.

"chunk": Default setting. The content constraints are checked for each chunk.

"all": The content constraints are checked for all found content items. There is no difference between the number of content items found and the number of delivered content items. You should only use this setting if the maximum number of found content items is relatively small (<100).

"{1...n}": The content constraints will be checked for the specified number of content items.

Value if nothing is specified: "chunk"

465


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

ignore-constraints (optional) Setting that determines whether content constraints are considered for the display of search results (see also the constraints parameter in the Result section).



"completely": The content constraints are not checked. Content is found irrespective of whether the content constraints are met, and shown in the search result. This setting allows you to accelerate the search if you do not have to check content constraints.


depth (optional) To avoid endless loops in the Target DynaMent's result, the depth parameter limits the number of nested executions of Target and Include DynaMents. If the limit specified in depth is reached, the corresponding DynaMent is no longer executed. Value if nothing is specified: "10"


db-structure (optional) Name of a redundant database structure to be used for executing the Target DynaMent. Redundant database structures help to optimize the performance of database queries. You create them in the project settings (go to: Main Menu ->Select Project -> Edit Project Settings -> Area: Target DynaMent). If a value has been entered for the parameter, the Target DynaMent only selects content items from those content items that are part of the redundant database structure, thus satisfying the content constraint that was specified in the definition of the redundant database structure. If the redundant database structure has a content constraint, it does not need to be repeated in the Target DynaMent. In addition, the database structure is used for formulating the database query when executing the Target DynaMent. If content items that are used in the redundant DB structure are changed, the corresponding entries in the search result cache become invalid automatically.

To achieve optimum results, all the referenced attributes (<rde-rd:constraint>, sortedby) should be present in the redundant structure, and a database index should exist whose attributes are also used in the content constraint, to allow the fastest possible restriction of the results to a small set.

If nothing is specified: RedDot LiveServer can select one of the redundant database structures that has been defined in the project on its own to create the database query for the Target DynaMent. It will choose the one with the fastest expected execution time according to the analysis of the Target DynaMent constraint and that is allowed in the project settings for optimizing the Target DynaMent.

466


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

cache-id-attribute (optional) Name of an attribute with optional additional source specification (default: request). After the Target DynaMent has been executed, the search result cache key under which the result of the Target DynaMent is held in the cache is written to the specified attribute. The name can be used, for instance, when the Target DynaMent is called again, to reuse the entry with the help of the cache-id parameter.

cache-id (optional) Specifies the search result cache key under which the result of the Target DynaMent is held in the cache. This key is read from the value of the cache-id-attribute parameter. If a value is specified for the parameter and when the Target DynaMent is called, the entry to the search result cache is searched for and used (for example, when browsing).




Value if nothing is specified: "targetresult-item"




Value if nothing is specified: "targetresult"

cachingtime (optional) Interval in minutes during which the result of the Target DynaMent remains in the search result cache. Creating caching helps improve the performance of extensive searching and browsing. Note: This interval will also be evaluated during the calculation of the actual caching time of contents in the component cache, which is determined by the shortest caching time of all the components. With the specific value "-1", the cachingtime parameter is not interpreted. Value if nothing is specified: Value of the Default caching time for search results entry in the settings of the project defined under project. If nothing is specified in the project settings (go to: Main Menu ->Select Project -> Edit Project Settings -> Area: Target DynaMent) then the default value is "10". For details on caching, see the information below: Caching Results of the Target DynaMent and of the Query DynaMent.

Child Elements

The Target DynaMent has a child element called <rde-dm:constraint>. DynaMents within values of a child element are processed. Inline notation is supported (see the info box below): Syntax and inline notation in the <rde-dm:constraint> child element.

<rde-dm:constraint> The child element contains a content request that is dependent on content attributes and their comparison values, which are combined using logical operators. A constraint consists of: content attribute operator comparison value.

467


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Content attribute: Content attribute under consideration of the attribute hierarchy. The specified attribute path within the hierarchy must be separated by periods and requires the content prefix. (For example, content.category.interest). Note: To address the alias of a content attribute from a redundant DB structure, use the additional prefix rde-structure (for instance, content.rde-structure.category).

Operator: Specifies the relational operators used to compare the content attribute and the comparison value. Operators are not case-sensitive.

"eq" (equals): Checks whether the content attribute and comparison value are equal.

"ne" (not equal): Checks whether the content attribute and comparison value are not equal.

"gt" (greater than): Checks whether the content attribute is greater than the comparison value.

"ge" (greater equal): Checks whether the content attribute is greater than or equal to the comparison value.

"lt" (less than): Checks whether the content attribute is smaller than the comparison value.

"le" (less equal): Checks whether the content attribute is less than or equal to the comparison value.

"contains": Checks whether the content attribute contains the comparison value. This operator does not apply to numerical attributes, as it searches for a string.

Comparison value: Value with which the content attribute is compared. Comparison values can be strings, integers, or inline notation.

String: Enclosed in single or double quotation marks. To prevent quotation marks within a string being interpreted as control characters, precede them with a backslash (for example, "\""). The backslash itself is ignored. Use with inline notation is possible. Example: "[user:xyz#]". For multivalued attributes: For a single attribute, all values are taken into account. When several attributes are combined or when there is a prefix or suffix, only the first value of each is considered. Examples: "[#user:abc#][#user:def#]" or [#user.locale#]_de.

Integer: Syntax without quotation marks. Use with inline notation is possible. Example: [user:xyz#]. For multivalued attributes: For a single attribute, all values are taken into account. Multiple attributes can only be combined with the help of the appropriate inline function. Example: [#user:attr1#1#].concat([#user:attr2#]).

Dot notation: For downward compatibility purposes, the following syntax is allowed for attributes: "user.attr" instead of "[#user:attr#]" for strings and user.attr instead of [#user:attr#] for numerical values. Note: Also see the information below: Syntax change in child element <rde-dm:constraint>.

Value if a specified comparison value does not have a value: "-1" for numerical values, blank string "" for character strings.

468


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Logical Operators: The following logical operators can be used to link multiple constraints.

AND: AND operator for content attribute conditions

OR: OR operator for content attribute conditions

When using brackets to clarify the processing sequence, make sure that you use parentheses. The notation also differentiates between strings and integers: A string value is enclosed in single or double quotation marks, while an integer value is not.

Example: ((content.category EQ 'news') AND (content.visited GT 2)) OR content.att3 NE "[#user:attribute#]".

Notes

You can add content attributes that you use in the Target DynaMent to redundant database structures to accelerate queries (see link below).

The syntax of the content constraints in the <rde-rd:content> child element has changed. Also see the information below: Syntax and inline notation in the <rde-dm:constraint> child element.

Result

The result for a Target DynaMent is a list of the found content items. DynaMents that are enclosed in a Target DynaMent are executed. In the case of attributes with multiple values, a content item is displayed if only one of the values satisfies the corresponding constraint. The content list is enclosed by an element that is specified in the tag parameter. Each individual content item is enclosed by the tag specified in the item-tag parameter. The parameters of the tag element (default: "targetresult") consist of the repeated display of the parameters of the original Target DynaMent, augmented by the following parameters:

hits Total number of located content items

lastchunk Number of the last chunk

nextchunk Number of the next chunk

previouschunk Number of the previous chunk

The individual content items found are placed in item-tag elements (default: "targetresult-item"). In addition to the name, the resulting XML also contains further information regarding the content, such as project, content group, and content constraints.

constraints Information on whether the content constraints are met by the requesting user or not. The following values are possible:

"no-constraints": There are no content constraints for this content item.

"matched": Content constraints for this content item are met.

469


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"not-matched": Content constraints for this content item are not met. Content items with this value are only displayed in the result if the ignore-constraints="yes" parameter has been set in the requesting DynaMent.

"not-evaluated": The content constraints for this content item were not checked. The ignore-constraints="completely" parameter was set in the requesting DynaMent.

hit Sequence number of the found content for the active session within all chunks.

Error Handling

The Target DynaMent's information, warning, and error messages begin with 4 in the thousands' place. You can send the return codes with the standard parameter result-attribute. In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible:


-4201 The maximum processing depth was reached.

-4320 Project was not found.

-4501 A parsing error occurred.

-4502 The redundant database structure is unknown.

-4901 An error occurred while executing the OQL query.

470


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax and Inline Notation in the <rde-dm:constraint> Child Element

The syntax of content constraints (child element <rde-dm:constraint>) was been changed starting in Version 3.6 SP 1 of RedDot LiveServer: Comparison values can and should now only be addressed using inline notation: [#source:attribute#default#]. The direct syntax, user.attribute, is still possible, but may not be supported in future versions. In earlier versions, this direct syntax could also be enclosed in single quotation marks. Such uses will now only be interpreted correctly if you select the Allow old attribute syntax check box in the Project Settings -> Target DynaMent area. This check box is selected automatically when you import older projects.

Inline notation In contrast to the usual handling, in which the inline notation in child element <rde-dm:constraint> is evaluated before the DynaMent is processed, the child element is not processed until the database query is evaluated in this case. This delayed evaluation is required to ensure correct processing of multivalued attributes. To do this, the value combinations of the individually referenced attributes are formed and linked with OR operators in the database query. Exception: If the ne (not equal) operator is used, the attributes are linked with AND operators. Example: Content constraint: content.xxx equals "[#user:attr1#]" with multivalued attribute user:attr="a1" and "a2" is turned into the database query: content.xxx equals "a1" or content.xxx equals "a2"

Content Attributes and Redundant Database Structures

You can define redundant database structures for content attributes that are used in the Target DynaMent. Target DynaMent queries are executed more quickly when there are redundant database structures and indexes for the content attributes that are used as criteria for the Target DynaMent.

You create redundant database structures and indexes for each project in the RedDot LiveServer administration interface, in the Target DynaMent area of the Edit Project Settings dialog window (go to: Main Menu -> Select Project -> Edit Project Settings).

471


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Caching Results of the Target DynaMent and of the Query DynaMent

Target DynaMent results or Query DynaMent results are stored in the search result cache if the caching time was not set to zero. If another call of a Target DynaMent or of a Query DynaMent has exactly the same search criteria, an entry in the search result cache is used as follows:

1. At first, the list of the content items found is used again regardless of any permission constraint.

2. The check of the permission constraints that follows filters the contents for every requesting session for each chunk. If requested again by the same session, the results of checking the permissions are used again, too.

3. XML displays are created according to parameters of the DynaMent for displaying the content of the requested chunk. These displays are saved as separate cache entries in the object cache and are re-used for repeat requests.

Re-using these data usually reduces the load and improves the performance. Therefore, results of the Target DynaMent and of the Query DynaMent should normally be held in the cache. The procedure described usually results in correct deliveries from the cache but has its limitations. In particular, not updated results are returned from the search result cache, if one of the following events occur before calling a Target DynaMent or Query DynaMent again:

Attributes are changed in the same session, affecting the result of checked content constraints.

Content constraints are changed, affecting the result of previously checked content constraints (for example, by additional import).

To ensure correct delivery from the search result cache in such project situations, you can

set the caching time in the DynaMent short enough, so that the effects of deviations in the project are irrelevant, or

change the search criteria a little or equivalently so that multiple entries are used in the search result cache, or

add a separate dependency (Cache DynaMent mode="add-dependency" or OpenAPI) and mark as changed if needed (Cache DynaMent mode="notify" or OpenAPI).

For more information about redundant database structures, see the Projects/Contents documentation.

472


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Target DynaMent with <constraint> Child Element

<rde-dm:target tag="product-list"> <rde-dm:constraint> content.Country EQ "[#user:profile.favorite#]" </rde-dm:constraint>

</rde-dm:target>

The Target DynaMent is replaced by the list of found content items. The XML result structure may look like this:

<product-list lastchunk="1" hits="4" chunk="1" chunksize="10" mode="" project="html-demo" tag="product-list" item-tag="rde-rd:targetresult-item" constraint="" group="" sortedby="" sortorder="asc" filter="" cachingtime="" depth="" attributepath="" stylesheet="">

<rde-rd:targetresult-item project="html-demo" content="338.xml" hit="1" group="products">

<product rde-rd:project="html-demo" rde-rd:content="338.xml"

rde-rd:leasingtime="0"><id>10001</id> <name>Moscato d´Asti Naturale (Italy)</name>

<description> Moscato d´Asti Naturale <P>Moscato is in crisis.</P> <P>0.75 L - 25.36 fl oz bottle</P>

</description> <image>/images/10001.gif</image> <price>11.36 ?</price>

</product> </rde-rd:targetresult-item>

</product-list>

473

DynaMent ReferencesUser DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

User DynaMent

You can use the User DynaMent for many different purposes, depending on the mode. The main uses:

Active user Determine all properties (fields, attributes, roles, and group memberships) of the user loaded in the active session.

Log on and log off User activities.

Administer users Read, change, create, and delete users, for example, for user registration or user administration for your project.

User reports Create a report (XML or CSV format) of all users in the LiveServer Repository who fulfill a filter condition.


Outputting the active user's properties (mode="session")

Determining a user's logon details (mode="session-check")

Logging on users (mode="login")

Logging on users without password (mode="login-trusted")

Logging off users (mode="logout")

Verifying the existence of a user (mode="exists")

Deleting users (mode="delete")

Creating users (mode="create")

Loading users (mode="load")

Editing users (mode="update")

Editing the group assignment of users ("groups")

Outputting a list of properties of selected users, possibly as a file (mode="report")

Using the <attributes> child element to output individual user attributes (mode="report").

474


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8



Content DynaMent

CPS DynaMent

Message DynaMent

User DynaMent


Using the User DynaMent

Sessions and users in RedDot LiveServer Each session in RedDot LiveServer is assigned to a user, which is loaded from the LiveServer Repository and/or directory services after logon. The corresponding user object is available as a copy in the current session. If properties of the session user are changed, they are not updated in the LiveServer Repository and/or directory services until logoff, a session timeout, or use of the Attribute DynaMent in mode="flush". The respective connector settings are used. Anonymous sessions are assigned to a copy of the user called anonymous. Changes to the anonymous user are not updated in the LiveServer Repository or directory services.

Attribute DynaMent or User DynaMent? You use the Attribute DynaMent with source="user" to read and change user attributes in the active session, among other things. The User DynaMent is used primarily to administer users. Note: The User DynaMent is always used in active RedDot LiveServers sessions. Note that two users are always involved: the user from the current session and the user you want to administer.

Administer users: User properties become attributes If you want to use the User DynaMent to access another user's data in an active session, you have to load the other user first (mode="load"). In the process, the loaded user's properties are represented as user hierarchy attributes in the active session: Beginning with a root attribute, which is selected via the path parameter of the User DynaMent (default: rde-edit-user), the four types of user properties are stored in the following four attribute branches:

rde-fields: User fields

rde-groups: Groups

rde-roles: Roles

rde-attributes: Attributes

The user name, for example, is saved under the following attribute: "rde-edit-user.rde-fields.name"

475


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

To load the user object, you use the User DynaMent in "load" mode. The attribute structure for displaying the user object is created automatically (see example below). Now you can edit all of properties of the loaded users using the Attribute DynaMent. You can use the User DynaMent in update mode to write changes to the user data back to the LiveServer Repository or the appropriate directory service. You can use "create" mode to create a new user. In both cases, you first save the user data as attributes in the active user's attribute tree.

The path parameter lets you specify a user attribute of the current user. In "load" mode, all of the loaded user's properties are written hierarchically as attributes to this root attribute. In "create" and "update" modes, the user's properties are read from this attribute.

Identifying users Users are always identified via their login field. Therefore, specify the user name (login) of the desired user in "load" mode in the user parameter of the User DynaMent. Now, if you change the corresponding attribute in the login field, i.e., "rde-edit-user.rde-fields.login", and save it with the "update" mode, a different user whose login field corresponds to the changed attribute value will be addressed.

Password The password of a user is not loaded, but can be changed if you save a value for the respective attribute—e.g., "rde-edit-user.rde-fields.password".

User groups In load mode, user groups are organized in the tree segment rde-groups. For each group that the user belongs to an attribute is created whose value contains the path and name of the group. The name of this attribute begins with group and ends with a sequential number.

User group attributes Users inherit the attributes of their user groups when they are loaded into a session after logging on. User group attributes will neither be read nor saved for a User DynaMent in mode load, update, or create.

476


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Load and display a user, change and display the name:

<test> <rde-dm:user mode="load" user="expert" />

<rde-dm:user />

Name of user loaded: <rde-dm:attribute mode="read"

attribute="rde-edit-user.rde-fields.name"/> <rde-dm:attribute mode="write"

attribute="rde-edit-user.rde-fields.name" op="set" value="[#request:newname#momo#]"/>

<rde-dm:user mode="update" report-tag="report" /> <rde-dm:attribute mode="delete" attribute="rde-edit-user"/> Check:

<rde-dm:user mode="load" user="expert" />

New name of user loaded: <rde-dm:attribute mode="read" attribute="rde-edit-user.rde-fields.name"/>

</test>

The result:

User "expert" is loaded using the User DynaMent in "load" mode. expert's data is saved in the attribute path of the active user's attributes below attribute "rde-edit-user". They are displayed with the User DynaMent in "session" mode.

The loaded user's name, "expert", is displayed using the Attribute DynaMent and overwritten with the new name, "momo". The User DynaMent in "update" mode is used to write the changed data back to the LiveServer Repository. The attributes generated under "rde-edit-user" are no longer needed and are therefore deleted.

To make sure that expert's name was really changed, the data is loaded again and the new name is displayed.

Example: Forcing Password Change at Logon

You can force a user to change his or password at the next logon in user administration. This setting is typically used for new users, whose password for initial access was sent by e-mail and have to change their passwords for security reasons. The user logs on with the known password, but does not get a valid session right away, but a prompt to enter a new password instead. During logon to the RedDot LiveServer administration interface, the necessary dialog window is displayed automatically and the password is also changed automatically. The user is then logged on to RedDot LiveServer and the Force password change at next logon option is reset automatically.

When the Force password change at next logon option is set for a user in a RedDot LiveServer project, this must be detected when the old password is entered. The password change dialog can then be displayed before the user receives a valid session. To do this, the return code from the User DynaMent has to be analyzed in the project, and a dialog with the necessary features must be provided. The following simple example describes one possible approach.

477


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

User Logon with Force password change at next logon Option

The User DynaMent in mode="login" is used to log users on in RedDot LiveServer projects. If the Force password change at next logon check box is selected, proceed as follows:

Recognize the situation; the User DynaMent sends return code -6522.

Display a password change dialog.

Use the User DynaMent in mode="load" and mode="update" to execute the password change.

Execute logon in the background with the new password.

The example below describes this procedure in detail. It illustrates the separation between displaying the dialogs (login.htm) and the function (login.xml), which simplifies its use in your projects: You merely have to modify the display in login.html, which is kept to a minimum in the example-.

If you want to try out the example now, import the content into the provided sample project, html-demo, and call .../hs.xsl/login.htm. The example requires four content items. It begins with the display of the dialogs.

login.htm Initial content. Displays the simple HTML forms.

The session:loggedIn (*1*) attribute is analyzed to determine whether the user is logged on to the session.

If so (*2*), a logoff dialog is displayed.

If not (*3*), the request:login-result attribute is analyzed, if it was set as the return value of the User DynaMent in mode="login" by a previous call in login.xml.

If login.result does not equal -6522 (*4*), the input fields for user name and password are displayed.

If login.result equals -6522 (*5*), then the logon has already been attempted for a user for whom the Force password change at next logon check box is selected. Therefore, fields to repeat the old password and enter the new password are displayed. Since the user is not logged on to the session at this point, the user name has to be read from the request:login attribute, which was set during the logon attempt.

478


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Lastly (*6*), the submit button for the form is inserted. Hidden fields include the current session ID and, as before, the action field - which is set to one of the following values, depending on the current dialog section: logout, login, or changepwd. The action of the form itself then calls the login.xml content, which is described further below.

<form action="login.xml" method="post">  <rde-dm:attribute mode="condition" attribute="loggedIn" source="session" op="eq" value="yes"> <rde-dm:if>  <rde-dm:attribute mode="read" attribute="rde-fields.login" tag="notag" />, you are logged in. <br/> <input type="hidden" name="action" value="logout"/> Logout </rde-dm:if> <rde-dm:else>  <rde-dm:attribute mode="condition" attribute="request:login-result" op="ne" value="-6522"> <rde-dm:if>  You are not logged in. <br/> Please log in: <br/> User name <input name="login"/><br> Password <input type="password" name="password"/><br> <input type="hidden" name="action" value="login"/>

</rde-dm:if>

<rde-dm:else>  <rde-dm:attribute mode="read" attribute="request:login" tag="notag" />,

You are not logged in.<br /> You must choose a new password: <br/> Your old password <input name="oldpwd"/><br> Your new password <input type="password" name="newpwd"/><br>n <input type="hidden" name="login" value="<rde-dm:attribute mode="read" source="request" attribute="login"/>"/>

479


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<input type="hidden" name="action" value="changepwd"/> </rde-dm:else> </rde-dm:attribute> </rde-dm:else>

</rde-dm:attribute>

 <input type="hidden" name="cpssessionid" value="[#session:rde-rd:sid#]"/> <input type="submit" />

</form>

login.xml Technical logon and its control logic. The value of the request:action attribute, which is passed on as a hidden parameter in the form from login.htm, controls the process flow:

If action=changepwd (*1*), the user whose name was passed on in the request:login attribute is loaded with the User DynaMent in mode="load". The old password is specified for verification.

When the user is loaded (*2*), Attribute DynaMents write the new password and the user is updated with the User DynaMent in mode="update". The request:action attribute is set to login, to enable the subsequent login with the new password.

If the user could not be loaded (*3*), then the old password may have been incorrect, for example. The logon dialog is called again in this case.

If action=login (*4*), a logon is performed with the User DynaMent in mode="login". Depending on the result, either loggedin.xml or notloggedin.xml is shown. Because the redirect="yes" parameter is set, RedDot LiveServer implements an HTTP redirect based on the specified redirect-parameter:

The user name of the user to use for the next page in case the logon fails

The current session ID, so the next page uses the session to which the user is already logged on in case the logon is successful

If action=logout (*5*), the User DynaMent mode="logout" is used to log the user off from the current session.

<?xml version="1.0" encoding="UTF-8"?> <node> <rde-dm:attribute mode="condition" attribute="action" op="eq" value="changepwd">  <rde-dm:user mode="load" user="[#request:login#]" password="[#request:oldpwd#]" path="userdata" result-attribute="result" /> <rde-dm:attribute attribute="result" mode="condition" op="eq" source="request" value="0"> <rde-dm:if>  <rde-dm:attribute mode="write" attribute="userdata.rde-fields.password" source="user" value="[#request:newpwd#]" /> <rde-dm:attribute mode="write" attribute="userdata.rde-fields.force-password-change" source="user" value="false" /> <rde-dm:user mode="update" path="userdata" user="[#request:login#]" />  <rde-dm:attribute attribute="action" mode="write" source="request" value="login" /> <rde-dm:attribute attribute="password" mode="write" source="request" value="[#request:newpwd#]" /> </rde-dm:if> <rde-dm:else>  <rde-dm:include content="login.htm"/> </rde-dm:else> </rde-dm:attribute>

</rde-dm:attribute>

<rde-dm:attribute attribute="action" mode="condition" op="eq" source="request" value="login">

 <rde-dm:attribute attribute="login" mode="write" source="session"

value="[#request:login#]" /> <rde-dm:user mode="login"

user="[#request:login#]" password="[#request:password#]" login-content="loggedin.xml"

login-fail="notloggedin.xml" redirect="yes" redirect-

parameter="login=[#request:login#]&cpssessionid=[#session:rde-rd:sid#]"

result-attribute="login-result" />

</rde-dm:attribute>

<rde-dm:attribute attribute="action" mode="condition" op="eq" source="request" value="logout">  <rde-dm:attribute attribute="loggedIn" mode="write" source="session" value="no" /> <rde-dm:user logout-content="login.htm" mode="logout" />

</rde-dm:attribute>

</node>

481


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

loggedin.xml Helper content; sets the session:loggedIn attribute to "yes" and calls the login.htm dialog. <node> <rde-dm:attribute

mode="write" attribute="session:loggedIn" value="yes" />

<rde-dm:include content="login.htm" />

</node>

notloggedin.xml Helper content; sets the session:loggedIn attribute to "no" and calls the login.htm dialog.

<node> <rde-dm:attribute attribute="loggedIn" mode="write" source="session" value="no" /> <rde-dm:attribute attribute="login-result" mode="write" source="request" value="[#request:rdeDmResult#]" /> <rde-dm:include content="login.htm" />

</node>

Reading Data of Active Users ('session')

Purpose

In "session" mode, the User DynaMent is replaced at runtime by the data of the user working in the active session: fields, attributes, roles, and group memberships. This mode is the default setting for the User DynaMent.

Syntax

<rde-dm:user mode ="session" depth ="[0|1|...n]" path ="{attributename}" appserver ="[yes|no]"

/>




The standard parameter cachingtime cannot be used. This DynaMent sets the caching time for the respective content to "0".

482


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Simple Call

<rde-dm:user/>

All essential user fields (master data) and user attributes are output up to a depth of "10" for the active user session. The user password will not be output.

Parameters

mode Mode of the User DynaMent, here "session". Default setting, can be omitted.

depth (optional) Used to output user attributes. Depth up to which the user attributes will be displayed. If depth="0", no attributes are displayed. If no value is specified: "10".

path (optional) Optional attribute path in the user attribute hierarchy. Only attributes below the specified path are output (for example, profile). If no value is specified: User attributes are output to the depth specified in the parameter. This means that a depth of "10" is set if nothing is specified. Note: User attributes are only displayed if the depth parameter has at least the value "1".

appserver (optional) Configuration of DynaMent processing on the Web/application server.

"yes": Even DynaMents that access external URLs will be executed in the normal order on the application server, as far as this is possible.

"no": DynaMents that access external URLs will be executed subsequently on the Web server. This means that it is practically impossible to react to DynaMent errors or content results. Note: Only set this option in an existing project in those rare situations in which you actually want to have a DynaMent executed after processing is complete.

If no value is specified: The value entered in the system configuration for the reddot.idea.appserver.callurls key (default value is "yes").

tag (optional) This is the tag name of the resulting XML element that displays the results of the DynaMent.



If no value is specified: "rde-idea:user"

Result

The essential user fields (master data) and selected user attributes will be output. The user password will not be output.

483


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can output the return codes with standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".

Output user fields (master data) and user attributes up to a depth of "10" for the active user session.

<rde-dm:user/>

The result:

<rde-idea:user>... <rde-idea:login>admin</rde-idea:login> <rde-idea:name>admin</rde-idea:name> <rde-idea:language>en</rde-idea:language> <rde-idea:country /> <rde-idea:status code="1">STATUS_ACTIVE</rde-idea:status> <rde-idea:authstatus code="3">AUTH_ACCESSGRANTED</rde-idea:authstatus> <rde-idea:created code="1020153322539">Tue Apr 30 09:55:22 CEST 2002</rde-idea:created> <rde-idea:lastlogin code="1022075007676">Wed May 22 15:43:27 CEST 2002</rde-idea:lastlogin> <rde-idea:lastpasswordchange code="0">Thu Jan 01 01:00:00 CET 1970</rde-idea:lastpasswordchange>

<rde-idea:attributes>

<rde-idea:attribute name="address" type="0" passwordFlag="false" path="address">

... <rde-idea:attributes>

</rde-idea:user>

Output the active user's fields (master data) without user attributes and specify a tag:

<rde-dm:user tag="myuser" depth="0" />

The result:

<myuser> <rde-idea:login> jpublic </rde-idea:login> <rde-idea:name> John Q. Public </rde-idea:name> <rde-idea:language> en </rde-idea:language> <rde-idea:country> USA </rde-idea:country> <rde-idea:status> 3 </rde-idea:status> <rde-idea:authstatus> 1 </rde-idea:authstatus> ...

</myuser>

484


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Determining User's Logon Details ('session-check')

Purpose

The User DynaMent in "session-check" mode lets you determine the latest logon information for a user. The return code shows whether the user is currently logged on, and one of the logon types below:

Permit multiple logons

Use current session

Logoff from current session

Depending on the result, you can display a different content when the user attempts to log on again (for instance, with return code 6223, the user will see the prompt "You are already logged on to another session. Do you want to cancel this session and start a new one?").

Syntax

<rde-dm:user

mode ="session-check" user ="{username}"

password ="{user password}"

/>





Simple Call

<rde-dm:user mode="session-check" user="username" result-attribute="result" /

>

The information determined about the user is output as a return code in the "result" attribute. The returned code can be processed further (see below: "Error Handling").

485


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the User DynaMent, here "session-check".

user User name of the user.

password (optional) User's password. The password will only be checked if the parameter has been specified.

Results

No result is returned in "session-check" mode. The information determined can be output as a return code in standard parameter"result-attribute".

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following return codes and error messages are possible for mode="session-check":

Return code Meaning

6220 There is no LiveServer session on this server for the user.

6221 There is a LiveServer session on this server for the user, but the user can log on with multiple sessions.

6222 There is a LiveServer session on this server for the user, which will be used when the user logs on again.

6223 There is a LiveServer session on this server for the user, which will be terminated before the user logs on again.

-6502 Wrong user or password

486


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Logging On Users ('login')

Purpose

You can use the User DynaMent in "login" mode to log on a user to the active session from the LiveServer Repository or a directory service. No new session is created. The content called depends on whether logon succeeds or fails. Using the checkonly="yes" parameter only runs a test logon.

The DynaMent is not executed until the full content is processed. Therefore any subsequent DynaMents will not yet work with the logged on user.

Syntax

<rde-dm:user mode ="login"

user ="{username}" password ="{user password}" login-content ="{contentname}"

login-fail ="{contentname}" redirect ="[no|yes]" redirect-parameter ="{parameters}" login-url ="{url}"

login-fail-url ="{url}" relogin ="[no|yes]"

directory-service ="[{connector-name}| LiveServer Repository]"

project ="{project}" checkonly ="[no|yes]"

/> The following standard parameters are also available:




Simple Call

<rde-dm:user mode="login" user="username" password="password" login-

content="login_successful.htm" login-fail="login_failed.htm" />

If the login succeeds, the content login_successful.htm is returned; if the login fails, login_failed.htm is returned.

487


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the User DynaMent, here "login".

user User name of the user to log on.

password Password of the user to log on.

login-content (optional) Name of content in the same project to display after a successful login. If content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml). Not evaluated for redirect="yes" if the parameter login-url is also specified.

Note: If the content item from login-content is the same as the current content item in the User DynaMent, this can cause problems in such situations - for example, if the User DynaMent is executed several times. In this case, we recommend using an internal redirect to a different content item and then another redirect from there.

login-fail (optional) Name of content in the same project to display after a failed login. If content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml). Not evaluated for redirect="yes" if the parameter login-fail-url is also used.

redirect (optional)

"no": Default setting. No Redirect is sent.

"yes": Upon completion, the content specified in the parameters login-content and login-fail (or in login-url and login-fail-url) is not simply processed but replaces the original requested content in the URI, and a redirect is sent to the browser. This option means that the following page called via the User DynaMent is displayed in the browser's URL.


redirect-parameter (optional) Only for redirect="yes": Information from the URL parameters, which is sent along with the redirect URL. Multiple parameters are separated by the HTML entity & (the ampersand character "&").

login-url (optional) Only for redirect="yes": URL of a content item, which is displayed if the user logon is successful. This parameter allows you to explicitly specify the URL for a redirect. This may be useful when mapping in an external Web server that alters the URLs. The URL can be relative. An available SID in the (relative) URL is modified in accordance with the current value. The specification of this URL has precedence over the specification of a content item in the login-content parameter.

login-fail-url (optional) Only for redirect="yes": URL of a content item, which is displayed if the user logon is unsuccessful. This parameter allows you to explicitly specify the URL for a redirect. This may be useful when mapping in an external Web server that alters the URLs. The URL can be

488


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

relative. An available SID in the (relative) URL is modified in accordance with the current value. The specification of this URL takes precedence over the specification of a content item in the login-fail parameter.

relogin (optional) Defines whether the same user can log on several times in the same session. Multiple logons generate a load. They should therefore be avoided wherever possible. The following values are possible:

"no": Default setting. If the user is already logged on to the current session, no additional logon is carried out. Multiple logons to the same session are thus prevented.

"yes": Every additional logon to a session by one user is carried out, even if that user is already logged on.


directory-service (optional) The name of a directory service or the LiveServer Repository. The user is authenticated with this. Basic rule: the user is authenticated with the LiveServer Repository or against with directory service the system has identified using the fallback mechanism for selecting a directory service. For more information about directory service fallback mechanisms, see the information below. The DynaMent does not log errors that occur while the system is identifying the directory service to be used (such as Directory service not available). The user attributerde-fields.directoryServiceLink in the DynaMent result shows with which directory service the user has been authenticated. The following values are possible:

"{connector name}": The name of a connector specified in RedDot LiveServer for a directory service against which the user is authenticated.

"LiveServer Repository": The user is authenticated with the LiveServer Repository.

If no value is specified: the user is authenticated with the LiveServer Repository or with the directory service the system has identified using the fallback mechanism for selecting a directory service (see information below).

project (optional) Specifies the project whose event definitions are accessed when the events User event - before authentication and User event - after authentication are triggered. The project specified is written as a value to the rdeDefaultProjectId session attribute. Existing values are overwritten.

If no value or an empty string is specified: The project specified as the value for the rdeDefaultProjectId session attribute. If this attribute has no value, the system uses the value for the Request attribute rdeProjectID. If this attribute has no value either, the default project is used.

checkonly (optional) Specifies whether a logon is real or for test purposes only.

"no": Default setting. The logon is real.

"yes": The logon is for test purposes only. This allows you to check a user's authentication data (user name and password) without having to log on.


489


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Notes

If a user has already successfully logged on and then unsuccessfully tries to log on a second time, the following applies: The successfully logged on user remains logged on to the session. However, a message will be displayed stating that the attempt failed.

Result

If the logon is successful, the user is added to the session and the project content is returned, as specified in the login-content (or login-url) parameter. If the logon fails, the previous user retains access to the session. The content that the user sees is determined by the login-fail (or login-fail-url) parameter.

The DynaMent's return code is output in request parameter rdeDmResult and appended to the redirect URL, which means the next page can be requested after a successful or failed logon. If the return code is -6522, for example, you can define a redirect to a page for changing the password. If the logon is successful, the number of days until the password expires is specified in request parameter rdePwdDays.

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="login":

Return code Meaning


-6502 Incorrect user or password Note: If redirect="yes", this return code is appended to the URL as request parameter rdeDmResult, provided it is not "0".

-6522 Password is correct, but must be changed. The user was not logged on.

6220 User already logged on to current session, no relogon

490


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Fallback Mechanism for User Authentication

Users can log on to a directory service or the LiveServer Repository. RedDot LiveServer determines the authentication method in the following steps:

1. Using a preset directory service server (either in a User DynaMent in "login" mode, or in the API, or in the User Settings (go to Main Menu -> Administer RedDot LiveServer -> Users -> Administer -> Select User).

2. If the directory service server specified for the user is not available, the user is authenticated against the LiveServer Repository, provided this is entered as final fallback.

3. If no directory service server is specified for the user, use the directory service server specified in the project settings (go to Main Menu -> Select Project -> Edit Project Settings -> Users area).

4. If the directory service server specified for the project is not available, the fallback directory service for this server is used, or additional fallbacks.

5. If no directory service server is specified for the project, the system uses the directory service server specified as default connection (go to Main Menu -> Administer RedDot LiveServer -> Connectors -> Directory Services -> Administer).

6. If there is no directory service connection, the user is authenticated against the fallback directory service for the default connection, or against the LiveServer Repository, provided this is entered as the final fallback (go to Main Menu -> Administer RedDot LiveServer -> Connectors -> Directory Services -> Administer).

7. If no directory service connection is specified for authentication, users are authenticated on the basis of their RedDot LiveServer entries on logon.

491


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Logging On Users Without Password ('login-trusted')

Purpose

You can use the User DynaMent in "login-trusted" mode to log on a user to the active session without entering a password. This is possible for users from the LiveServer Repository, or from a directory service that does not require a password.

No new session is created. The content called depends on whether logon succeeds or fails. Using the checkonly="yes" parameter only runs a test logon.

The DynaMent is not executed until the full content is processed. Therefore any subsequent DynaMents will not yet work with the logged on user.

Syntax

<rde-dm:user mode ="login-trusted" user ="{username}" login-content ="{contentname}" login-fail ="{contentname}" redirect ="[no|yes]" redirect-parameter ="{parameters}" login-url ="{url}" login-fail-url ="{url}" relogin ="[no|yes]" directory-service ="[{connector-name}| LiveServer Repository]" project ="{project}" checkonly ="[no|yes]"

/>





Simple Call

<rde-dm:user mode="login-trusted" user="username" login-

content="login_successful.htm" login-fail="login_failed.htm" />

If the login succeeds, the content login_successful.htm is returned; if the login fails, login_failed.htm is returned.

492


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the User DynaMent, here "login-trusted".

Additional Parameters The parameters of the User DynaMent in "login" mode apply, except for the password parameter. See the relevant section and the link below for details.

Notes

See User DynaMent in "login" mode.

Results


Error Handling


See also:

Logging On Users ('login') (Page 487)

Logging Off Users ('logout')

Purpose

You can use the User DynaMent in "logout" mode to log off the current user and load the anonymous user to the active session. No new session is created. The content located in the DynaMent is not added to the component cache.

When the DynaMent is called, the result is the content whose name is specified in the logout-content parameter. This content must belong to the same project as the content containing the User DynaMent.

Please note: The DynaMent is always executed on the RedDot LiveServer's Web server components. This means that it will be executed only after processing has completed for the DynaMents that are executed on the application server components. That is why these DynaMents are processed with the logged-on user, even if they come after the User DynaMent mode="logout" in the processed content.

Nothing from the originally processed content is included in the delivered result. However, you can use request parameters to pass information on to the logout-content.

493


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:user mode ="logout" logout-content ="{contentname}"

redirect ="[no|yes]" redirect-parameter ="{parameters}" suppress-cookie-relogin="[yes|no]" logout-url ="{url}" login-cookie ="[expire|keep]" project ="{project}"

/>




The standard parameter cachingtime cannot be used. This DynaMent sets the value of the caching time for the respective content to "0."

Simple Call

<rde-dm:user mode="logout" logout-content="logout.htm" />

After logout, the content logout.htm is returned.

Parameters

mode Mode of the User DynaMent, here "logout".

logout-content (optional) Name of content in the same project to display after a successful logout. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml). Not evaluated for redirect="yes" if the parameter logout-url is also used.

Note: If the content item from logout-content is the same as the current content item in the User DynaMent, this can cause problems in such situations - for example, if the User DynaMent is executed several times. In this case, we recommend using an internal redirect to a different content item and then another redirect from there.

redirect (optional)

"no": Default setting. No Redirect is sent.

"yes": Upon completion, the content specified in the parameter logout-content (or logout-url) is not simply processed but replaces the original requested content in the URI, and a redirect is sent to the browser. This option means that the following page called via the User DynaMent is displayed in the browser's URL.


494


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

redirect-parameter (optional) Only for redirect="yes": Information from the URL parameters, which is sent along with the Redirect URL. Multiple parameters are separated by the HTML entity & (the ampersand character "&").

suppress-cookie-relogin (optional) The txNoCookieAuth=yes parameter prevents a user from logging back on to a RedDot LiveServer project automatically via an authentication cookie within a session. In particular, it is not necessary to send this parameter with external follow URLs.

"yes": Default setting. The URL parameter is sent.

no: Suppresses the automatic sending of URL parameters with the follow URL.

Value if nothing is specified: "yes":

logout-url (optional) Only for redirect="yes": URL of a content item, which is displayed if the user logon is unsuccessful. This parameter allows you to explicitly specify the URL for a redirect. This may be useful when mapping in an external Web server that alters the URLs. The URL can be relative. An available SID in the (relative) URL is modified in accordance with the current value. The specification of this URL has precedence over the specification of a content item in the logout-content parameter.

login-cookie (optional) Controls the automatic user logon when the project is accessed the next time.

Use the project settings to activate RedDot LiveServer cookies for automatic authentication of individual users (check box "Authenticate using RedDot LiveServer cookie"). This means that a user who logged out or got logged out by a session timeout will automatically be logged back in the next time the user accesses the project.

"expire": Marks the RedDot LiveServer cookie on the client as expired so that the browser can delete it. This keeps users who logged off from being automatically logged back in again the next time they access the project. Once a user logs on again, a cookie is created for the user according to the project settings. Note: A cookie, which is transferred to the client, ensures that authentication cookies are deleted.

"keep": The cookie is not deleted after the user logs off. The user is registered with the project automatically during the next logon.

Value if nothing is specified: "expire"

project (optional) Specifies the project whose event definitions are accessed when the events User event - before the session is closed and User event - after the session is closed are triggered.

If no value or an empty string is specified: The project specified as the value for the rdeDefaultProjectId session attribute. This session attribute has the value set in mode="login", unless it has been overwritten by an Attribute DynaMent. If the rdeDefaultProjectId attribute has no value, the system event definitions are used.

495


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

The current user is logged off and an anonymous user is loaded into the current session. After logout, project content specified in parameter logout-content (or logout-url) is returned.

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". For more information on the general return codes, please read the "Error Handling" section in the "RedDot DynaMents" chapter.

Verifying Existence of Users ('exists')

Purpose

You can use the User DynaMent in "exists" mode to check whether a specific user exists in the Live Server Repository or the standard directory service.

You can have the result of the check output as a return code in the standard parameter result-attribute, where it can be used further (see "Error Handling" below).

Syntax

<rde-dm:user

mode ="exists"

user ="{username}"

/>





Simple Call

<rde-dm:user mode="exists" user="username" result-attribute="result" />

The result of the check as to whether the user exists or not is output as a return code in the "result" attribute. The returned code can be processed further (see below: "Error Handling").

496


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the User DynaMent, here "exists".

user User name of the user whose existence is to be checked.

Results

No result is returned in "exists" mode. You can have the result of the check output as a return code in the standard parameter"result-attribute".

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible for mode="exists":

<rde-dm:user mode="exists" user="[#request:login#]" result-attribute="my-result"/>

<rde-dm:attribute mode="condition" tag="notag" attribute="my-result" source="request" op="eq" value="6210">

...

Checks whether the user exists. The return code is returned as a result in attribute "my-result". Additional processing steps depend on whether the code is set to 6210 (that is, the user already exists).

Return code Meaning

6200 Processing completed successfully. The user does not exist in the LiveServer Repository or in the directory service.

6210 Processing completed successfully. The user exists in the LiveServer Repository or in the directory service.

497


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Deleting Users ('delete')

Purpose

The "delete" mode of the Attribute DynaMent lets you delete a user from the LiveServer Repository.

Syntax

<rde-dm:user mode ="delete"

user ="{username}"

password ="{user password}"

/>





Simple Call

<rde-dm:user mode="delete" user="username" />

The user is deleted from the LiveServer Repository or an error code is generated.

Parameters

mode Mode of the User DynaMent, here "delete".

user User name of the user to delete.

password (optional) Password of the user to delete. The password will only be checked if the parameter has been specified.

Notes

In contrast to earlier versions, the user can now be deleted without specifying the password parameter.

498


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

No result is returned in "delete" mode. If an error occurs, an error code is generated and can be output in standard parameter "result-attribute".

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="delete":

Creating Users ('create')

Function

The "create" mode of the User DynaMent lets you create a user in the LiveServer Repository. The properties of this user (user fields, attributes, roles, and group memberships) first have to be saved as attributes in the attribute tree of the active user session – under the attribute path specified in parameter path.

To create a new user, you have to define at least a valid user name (of at least one character) in the active user's attribute tree. Use the Attribute DynaMent in write mode to write it as a value of the rde-fields.login attribute in the specified path. Use the rde-fields.password attribute to write the new user's password. A valid password must have at least five characters. If no password is specified, the user is not assigned a password and can log on without a password.

The defined attribute branches below path are:


rde-groups: Groups

rde-roles: Roles


The user name, for example, is saved under the following attribute: "rde-edit-user.rde-fields.login".

If a user with the specified name already exists in the LiveServer Repository or in the directory service specified, no user with that name is created in the LiveServer Repository and the data of the existing user are not overwritten. If a directory service is specified the user is created in the LiveServer Repository and only checked against the directory service specified.

Return code Meaning

- 6501 Incorrect password.

- 6511 User not found

- 6513 Procedure failed because the user is locked.

499


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:user

mode ="create"

path ="{attributename}" directory-service ="{connector-name}"

/>




The default parameter cachingtime cannot be used. This DynaMent sets the value of the caching time for the respective content to "0."

Simple Call

<rde-dm:user mode="create"/>

A new user is created in the LiveServer Repository. The data for this user is read from the active user's attributes below attribute "rde-edit-user".

Parameters

mode Mode of the User DynaMent, here "create".

path (optional) Attribute path in the hierarchy of the active user's attributes, below which the data of the user to be created is defined. Value if nothing is specified: "rde-edit-user"

directory-service (optional) The name of a connector specified in RedDot LiveServer for the directory service where the user is to be found. In any case, the user is created in the LiveServer repository and only checked against the directory service specified. If a user already exists in the LiveServer Repository or in the directory service specified, no user with that name is created in the LiveServer Repository and the data of the existing user are not overwritten.

If nothing is specified: LiveServer Repository.

Notes

To create a new user in the LiveServer Repository, you have to define at least a valid user name (of at least one character) in the active user's attribute tree. Use the Attribute DynaMent in write mode to write it as a value of the rde-fields.login attribute in the specified path. Use the rde-fields.password attribute to write the new user's password. A valid password must have at least five characters. If no password is specified, the user is not assigned a password and can log on without a password.

500


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Result

No result is returned in "create" mode. If successful, the new user is created in the LiveServer Repository. If a user with the specified name already exists in the LiveServer Repository or in the directory service specified, no user with that name is created and the data of the existing user are not overwritten. If an error occurs, an error code is generated and can be output in standard parameter "result-attribute".

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can send the return codes with the default parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="create":

a) Use the Attribute DynaMent to create the minimal attribute tree in the active user:

<rde-dm:attribute mode="write" attribute="rde-edit-user.rde-fields.login" op="set" value="[#request:login#]"/> <rde-dm:attribute mode="write" attribute="rde-edit-user.rde-fields.password"

op="set" value="[#request:password#]"/>

b) Create a new user with the User DynaMent:

<rde-dm:user mode="create" />

The result:

The new user is created with the user name and password read from attributes "rde-edit-user.rde-fields.login" and "rde-edit-user.rde-fields.password", respectively, or an error code is returned.

See also:

Using the User DynaMent (Page 475)Predefined Attributes for Source 'user' for Loaded Users (Page 558)


- 6504 User password contains less than 5 characters or is not correct

- 6512 User already exists

- 6513 User is currently being edited and is locked

501


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Loading Users to Active Sessions ('load')

Purpose

You can use the User DynaMent in "load" mode to load a user's properties from the LiveServer Repository or the default directory service to the active session. While the session is active, the properties (user fields, attributes, roles, and group memberships) are saved as attributes in the attribute tree of the active user session, under the attribute path specified in parameter path. This approach enables you to edit all the properties of the loaded user with the Attribute DynaMent. Note: If you want to change the attributes of the session user, use the Attribute DynaMent (see info below).



rde-groups: Groups

rde-roles: Roles


The user name, for example, is saved under the following attribute: "rde-edit-user.rde-fields.login"

If no other user is specified, the user's properties from the active session are loaded.

Editing Session User Attributes

You generally use the Attribute DynaMent with source="user" to edit attributes and properties of the user assigned to the current session as a copy, without loading the user again with the User DynaMent. Changes are updated automatically upon logoff or after a session timeout, or manually with the Attribute DynaMent in mode="flush".

Syntax

<rde-dm:user mode ="load" user ="[{username}| rdeCurrentSessionUser]" password ="{password}" path ="{attributename}" directory-service ="[{connector-name}| RedDot LiveServer Repository]" project ="{projectname}"

/>




502


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


Simple call

<rde-dm:user mode="load" user="username" />

While the current session is active, the specified user's data is saved in the active user's attributes below attribute "rde-edit-user". The user's password is not loaded.

Parameters

mode Mode of the User DynaMent, here "load".

user (optional) User to load to the active session. The following values are possible:

"{user name}": Name of the user.

"rdeCurrentSessionUser": Copy of the current session's user. Unlike with the usual procedure, a copy of the user in the current session is loaded from the LiveServer Repository, rather than the actual user. If a password is specified, this is not checked.

If no value is specified: User name of the currently active user.

password (optional) Password of the user to load to the active session. When this parameter is specified, the user is only loaded if the password is checked. If no value is specified: the user is loaded without authentication.

path (optional) Attribute path in the hierarchy of the loaded user's attributes, below which the data of the loaded user is defined. If no value is specified: "rde-edit-user"

directory-service (optional) The name of a directory service or the LiveServer Repository as a data source from which the user is read. Basic rule: The user is read from the LiveServer Repository or from the directory service that the system has identified using the fallback mechanism for selecting a directory service. The same order is used as for the logon procedure. For more information about directory service fallback mechanisms, see the information below. The DynaMent does not log errors that occur while the system is identifying the directory service to be used (such as Directory service not available). The user attribute rde-fields.directoryServiceLink in the DynaMent result shows from which directory service the user has been loaded. The following values are possible:

"{connector name}": The name of a connector specified in RedDot LiveServer for a directory service from which the user is read. If the specified directory service connector is not found, the user is not loaded. Note: The directory service connector must be configured to allow user data to be read from the directory service. That is, the Using master connection option for the Read users from directory service field must be selected in the directory service connector (Edit Directory Service Connector -> Synchronization area).

"RedDot LiveServer Repository": The user is read from the LiveServer Repository.

503


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

If no value is specified: the user is read from the LiveServer Repository or from the directory service that the system has identified using the fallback mechanism for selecting a directory service (see information below).

project (optional) Project in which the directory service to be used is identified if the directory-service parameter is not specified or has no value.

Notes

The user's password is not loaded.

Result

The specified user's data is saved in the active user's attributes below the attribute from "path". The user's password is not loaded. You can display the result or process it further, for example, using the User DynaMent in "session" mode.

Error handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="load":


- 6315 Required directory service not found

- 6501 Incorrect password.



- 6516 Required project not found, using current project

504


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Fallback Mechanism for User Authentication

Users can log on to a directory service or the LiveServer Repository. RedDot LiveServer determines the authentication method in the following steps:

1. Using a preset directory service server (either in a User DynaMent in "login" mode, or in the API, or in the User Settings (go to Main Menu -> Administer RedDot LiveServer -> Users -> Administer -> Select User).

2. If the directory service server specified for the user is not available, the user is authenticated against the LiveServer Repository, provided this is entered as final fallback.

3. If no directory service server is specified for the user, use the directory service server specified in the project settings (go to Main Menu -> Select Project -> Edit Project Settings -> Users area).

4. If the directory service server specified for the project is not available, the fallback directory service for this server is used, or additional fallbacks.

5. If no directory service server is specified for the project, the system uses the directory service server specified as default connection (go to Main Menu -> Administer RedDot LiveServer -> Connectors -> Directory Services -> Administer).

6. If there is no directory service connection, the user is authenticated against the fallback directory service for the default connection, or against the LiveServer Repository, provided this is entered as the final fallback (go to Main Menu -> Administer RedDot LiveServer -> Connectors -> Directory Services -> Administer).

7. If no directory service connection is specified for authentication, users are authenticated on the basis of their RedDot LiveServer entries on logon.

Load and display a user:

<test> <rde-dm:user mode="load" user="[#request:user#anonymous#]" /> <rde-dm:user />

</test>

The result:

The loaded user's data is displayed below attribute "rde-edit-user" in the session's active user.

See also:


505


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Updating Users ('update')

Purpose

You can use the User DynaMent in "update" mode to write a user's changed data back to the LiveServer Repository or the corresponding directory service. The properties of this user (user fields, attributes, roles, and group memberships) first have to be saved as attributes in the attribute tree of the active user session – under the attribute path specified in parameter path. Note: If you want to change the attributes of the session user, use the Attribute DynaMent (see info below).

To update a user, you have to define the user name in the active user's attribute tree. This user name is read from attribute "rde-fields.login" below path. All other attributes can be used to set new values. User attributes that are not specified are not changed.



rde-groups: Groups

rde-roles: Roles


The user name, for example, is saved under the following attribute: "rde-edit-user.rde-fields.login".

Editing Session User Attributes

You generally use the Attribute DynaMent with source="user" to edit attributes and properties of the user assigned to the current session as a copy, without loading the user again with the User DynaMent. Changes are updated automatically upon logoff or after a session timeout, or manually with the Attribute DynaMent in mode="flush".

Syntax

<rde-dm:user mode ="update"

path ="{attributename}" directory-service ="{connector-name}

property-types ="{list of property-types}"

/>




506


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


Simple Call

<rde-dm:user mode="update" />

The user data that is read from the active user's attributes below the attribute "rde-edit-user" is updated. Attributes that are not specified there are not changed.

Parameters

mode Mode of the User DynaMent, here "update".

path (optional) Attribute path in the hierarchy of the active user's attributes, below which the data of the user to be updated is defined. If no value is specified: "rde-edit-user"

directory-service (optional) The name of a connector specified in RedDot LiveServer to the directory service where the user data is to be updated. If no value is specified: The directory service is read from the current user.

property-types (optional) Additional properties to be updated.

"groups": The group assignments of the user are updated.

If no value is specified: No additional properties.

Notes

We recommend using the User DynaMent in "load" mode to load the user data to the current session and then changing the loaded data.

Results

No result is returned in "update" mode. If an error occurs, an error code is generated and can be output in standard parameter "result-attribute".

507


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="update":

If you enter a user name in the Request parameter, you should also change the "profile.level" attribute.

With the Attribute DynaMent, the user name to be updated is set in the current user's attribute tree:

<rde-dm:attribute mode="write" attribute="rde-edit-user.rde-fields.login" op="set"

value="[#request:login#]"/>

The attribute to be changed "profile.level" is set:

<rde-dm:attribute mode="write" attribute="rde-edit-user. rde-attributes.profile.level" op="set"

value="[#request:profile.level#]"/>

The modified user data is written with the User DynaMent:

<rde-dm:user mode="update" />

The result:

The user name of the user to edit is read from attribute"rde-edit-user.rde-fields.login". The changed value for attribute"profile.level" is also read and written to the LiveServer Repository, or an error code is returned.

See also:



- 6503 User logon not correct

- 6504 User password contains less than 5 characters or is not correct



- 6521 Attribute path for data not found.

508


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Editing Group Assignment of Users ('groups')

Purpose

The "groups" mode of the User DynaMent lets you modify the assignment of user groups for users in the LiveServer Repository.

Syntax

<rde-dm:user mode ="groups" type ="[loaded-user|user-filter]" path ="{attributename}"

op ="[update|remove-all]" asynchronous ="[false|true]" >

<rde-rd:group mode ="[add|remove]" check-path ="[false|true]" > <![CDATA[{group path}]]>

</rde-rd:group>

<rde-rd:user-filter mode ="standard|redundant-structure" db-structure ="structure name"> <rde-rd:username></rde-rd:username> <rde-rd:name></rde-rd:name> <rde-rd:status></rde-rd:status> <rde-rd:language></rde-rd:language> <rde-rd:group></rde-rd:group> <rde-rd:role></rde-rd:role> <rde-rd:role-param></rde-rd:role-param> <rde-rd:created-from></rde-rd:created-from> <rde-rd:created-to></rde-rd:created-to> <rde-rd:last-logon-from></rde-rd:last-logon-from> <rde-rd:last-logon-to></rde-rd:last-logon-to> <rde-rd:password-expires></rde-rd:password-expires> <rde-rd:attributes> <rde-rd:attribute path ="..." op ="[eq|ne|lt|gt|le|ge|containsany]"> </rde-rd:attribute> </rde-rd:attributes> </rde-rd:user-filter>

</rde-dm:user>




509


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


Simple Call

See the various examples below.

Parameters

mode Mode of the User DynaMent, here "groups".

type (optional) Determines the users for which the group assignments are to be changed:

"loaded-user": The group assignments are modified for the users who were previously loaded using the User DynaMent in "load" mode. The attributes under the {path}.rde-groups attribute tree are modified according to the default settings. The default value for {path} is the same as in "load" mode: rde-edit-user. The changes are not saved in the LiveServer Repository until a mode="update" property-types="groups" User DynaMent has been called.

"user-filter": The group assignments are modified for all users in the LiveServer Repository who match the filter criteria specified in the <rde-rd:user-filter> child element. The changes are updated directly in the LiveServer Repository. A log file with the following name is created in the default log directory: {Project}-UserDynaMentGroups-{time stamp}-{user}.

Value if nothing is specified: "loaded-user".

path (optional; only for type="loaded-user") Attribute path in the hierarchy of the user's attributes, below which the group assignments are modified. Value if nothing is specified: "rde-edit-user".

op (optional) Determines how the group assignments are modified:

"update": The group assignments are modified according to the method specified in the <rde-rd:group> child element.

"remove-all": All group assignments are removed. The <rde-rd:group> child element is ignored.

Value if nothing is specified: "update".

510


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

asynchronous (optional; only for the <rde-rd:user-filter> child element) Determines whether the changes to the group assignments are made.

"false": The changes are made immediately. This process may take some time for many users.

"true": Content is processed immediately, but the changes to the group assignments are made asynchronously. This setting is suitable if several users need to be modified. The asynchronous process is displayed as a current job in the RedDot LiveServer administration interface with the name UserDynaMentGroups-{project}-{content} (under Asynchronous Jobs -> Administer Current Jobs).


Child Elements

The User DynaMent has two additional child elements in "groups" mode. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:group> (optional) In the child element, the paths for user groups are created, for which the assignment is to be edited. The child element can be used more than once.

mode Determines how the assignment is modified:

"add": The assignment of the specified user groups is added.

"remove": The assignment of the specified user groups is removed.


check-path (optional; only for mode="add") Determines whether to check the existence of user groups:

"false": The existence of groups in the LiveServer Repository will not be checked.

"true": The existence of groups in the LiveServer Repository will be checked.


<![CDATA[{group path}]]> Entering a group path.

<rde-rd:user-filter> (optional; only for type="user-filter") This child element can contain additional elements for users whose data you want to output. The child element and the other elements may only appear one time. If none of the possible elements are specified: No filter. The syntax is the same as for the User DynaMent child element of the same name in "report" mode. See the description there.

Result

The group assignments are modified according to the specifications. If a user is assigned to a group and one of its parent groups, the parent group is not assigned.

511


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following return codes and error messages are possible for mode="groups":

See also:

Loading Users to Active Sessions ('load') (Page 502)Updating Users ('update') (Page 506)Reading Properties of Selected Users ('report') (Page 514)


-6623 This user group does not exist in the LiveServer Repository.

-6624 Invalid value for the op parameter.

512


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Examples of Calls

Removing all group assignments for loaded users:

<groups> <rde-dm:user mode="load" user="expert"/> <rde-dm:user mode="groups" type="loaded-user" op="remove-all"/> <rde-dm:user mode="update" property-types="groups"/>

</groups>

Adding loaded users to the Regular Users user group:

<groups1> <rde-dm:user mode="load" user="expert"/> <rde-dm:user mode="groups" type="loaded-user" op="update"> <rde-rd:group mode="add" check-path="yes">Regular Users</rde-rd:group> </rde-dm:user> <rde-dm:user mode="update" property-types="groups"/>

</groups1>

Removing loaded users from the Regular Users user group:

<groups2> <rde-dm:user mode="load" user="expert"/> <rde-dm:user mode="groups" type="loaded-user" op="update"> <rde-rd:group mode="remove">Regular Users</rde-rd:group> </rde-dm:user> <rde-dm:user mode="update" property-types="groups"/>

</groups2>

Adding filtered users to the Regular Users user group and removing them from the Administrators group:

<groups3> <rde-dm:user mode="groups" type="user-filter" op="update" asynchronous="yes"> <rde-rd:group mode="add">Regular Users</rde-rd:group> <rde-rd:group mode="remove">Administrators</rde-rd:group> <rde-rd:user-filter> <rde-rd:username>Exper*</rde-rd:username> </rde-dm:user>

</groups3>

513


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Properties of Selected Users ('report')

Purpose

In "report" mode, the User DynaMent is replaced at runtime by a list of properties relating to previously selected users, namely fields, attributes, and role and group membership.

To select the users whose properties you wish to output, use the "user" parameter or the child element <rde-rd:user-filter>; the latter offers a wider range of options. Use the <attributes> child element to restrict the output of user attributes to those you explicitly specify.

The data can be output to the screen or to a file (CSV, XML). In the case of large reports involving many users it is advisable to send the output to a file to avoid excessive system load.

Syntax

<rde-dm:user mode ="report" depth ="[0|1|...n]" buffersize ="[1|2|4|8...]" chunk ="{chunk number}" chunksize ="{number of records}" sortedby ="{username|name}" sortorder ="[asc|desc]" user ="{usernames}" path ="{attributename}" delim ="{separator}" resulttype ="[csv|xml]" filename ="{filename}"

encoding ="{encoding}" item-tag ="[{tagname}|notag]" >

<attributes>

<attribute>{userattribute}</attribute> ...

</attributes>

<rde-rd:user-filter mode ="standard|redundant-structure" db-structure ="structure name">

<rde-rd:username></rde-rd:username> <rde-rd:name></rde-rd:name> <rde-rd:status></rde-rd:status> <rde-rd:language></rde-rd:language>

<rde-rd:group></rde-rd:group> <rde-rd:role></rde-rd:role>

<rde-rd:role-param></rde-rd:role-param> <rde-rd:created-from></rde-rd:created-from>

<rde-rd:created-to></rde-rd:created-to> <rde-rd:last-logon-from></rde-rd:last-logon-from> <rde-rd:last-logon-to></rde-rd:last-logon-to>

<rde-rd:password-expires></rde-rd:password-expires> <rde-rd:attributes>

<rde-rd:attribute path ="..." alias ="..."

op ="[eq|ne|lt|gt|le|ge|containsany]">

514


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

</rde-rd:attribute> </rde-rd:attributes>

</rde-rd:user-filter>

</rde-dm:user>




The standard parameter cachingtime cannot be used. This DynaMent sets the value of the caching time for the respective content to "0".

Simple Call

<rde-dm:user mode="report" filename="c:/user.report.txt"/>

All user data in the system is saved in file user.report.txt.

Parameters

mode Mode of the User DynaMent, here "report".

depth (optional) Used to output user attributes. Depth up to which the user attributes will be displayed. If depth="0", no attributes are displayed. Value if nothing is specified: "10".

buffersize (optional) Only used if no output file is specified in the filename parameter. Note: If the chunk and chunksize parameters are specified, this parameter is ignored. Limits the buffer size available for displaying contents. Examples: buffersize="1" equals 1 KB; buffersize="4" equals 4 KB. Based on the memory available, you should not set this value too high, because it might slow the system down. Value if nothing is specified: "32", for 32 KB.

chunk (optional, only effective when used together with chunksize) Sequential number of the chunk whose results are to be returned. Chunks are subsections of the overall result list, which are usually displayed across a number of different pages. Value if nothing is specified: "-1"; chunking is not used.

chunksize (optional, only effective when used together with chunk) The chunksize parameter specifies the maximum number of users in the result of the User DynaMent. If the number of users found is greater than chunksize, then the remaining entries are displayed in the next chunk after sorting. Value if nothing is specified: "-1"; chunking is not used.

sortedby (optional, only effective when used together with chunk and chunksize) User field used to sort the user records alphanumerically. Here are some examples:

515


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

"username": User name for logging on to RedDot LiveServer

"name": User name

If nothing is specified: "username"





user (optional; alternative to the child element, <rde-rd:user-filter>) Specifies the user names for which data is to be output. You can use wildcards: The asterisk (*) replaces an indefinite number of characters, whereas the question mark (?) replaces precisely one character. Note: If this parameter is specified, information contained in the child element <rde-rd:user-filter> will not be evaluated. Value if nothing is specified and without the child element <rde-rd:user-filter>: "*" for all users.

path (optional) Optional attribute path in the user attribute hierarchy. Only attributes below the specified path are output (for example, profile). If nothing is specified: User attributes are output to the depth specified in the parameter. This means that a depth of "10" is set if nothing is specified. Note: User attributes are only displayed if the depth parameter has at least the value "1".

delim (optional, only for resulttype="csv") Delimiter between the individual columns. Value if nothing is specified: ";"

resulttype (optional) Specifies the type of output.

"csv": Output as CSV file.

"xml": Output as XML file.

Value if nothing is specified: "csv"

In XML files, the following characters are modified in attribute names: Space: Replaced with underscore. Digit as first character in attribute name: An "a" precedes the number.

filename (optional) Valid file name for data output to a file. If nothing is specified: Output not in a file.

encoding (optional, only if parameter filename is used) Specifies the encoding method used to write the data to the file (for example, ISO-8859-1 or UTF-8). If nothing is specified: Value of parameter reddot.encoding.default from the system configuration.

item-tag (optional, only for resulttype="xml") Tag name of the XML element that surrounds each user data record in the result.

516


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8


"notag": User records in the result are listed without the surrounding XML elements.

Value if nothing is specified: "rde-idea:user-item"

tag (optional, only for resulttype="xml") This is the tag name of the XML element that displays the result of the DynaMent.



Value if nothing is specified: "rde-idea:user"

Child Elements

The User DynaMent has two additional child elements in "report" mode. DynaMents within values of a child element are processed. Inline notation is supported.

<attributes> (optional) In this child element, you can enter user attribute paths for specific user attributes between the <attribute> elements. This allows you to limit the output of attributes in the result file to the specified attributes. If the <attributes> child element is set, the path and depth parameters are ignored.

<rde-rd:user-filter> (optional) This child element can contain additional elements in which you can specify filters for users whose data you want to output. The child element and the other elements may only appear one time. If none of the possible elements are specified: No filter. Note: The information in the child element will be evaluated only if the user parameter has not been specified.

mode (optional) Determines which filter constraints are used:

"standard": All filter constraints specified in the child elements are used. Redundant database structures are not evaluated.

"redundant-structure": The redundant database structure specified in parameter "db-structure" is used. The child elements <rde-rd:username>, <rde-rd:name>, and <rde-rd:attributes> are also evaluated (also see example below). Value if nothing is specified: "standard"

db-structure (optional, only for mode="redundant-structure") Specifies a redundant DB structure for user attributes created previously in the user interface (using: Administer RedDot LiveServer -> Configuration -> Administer User Configuration -> Area: User Search).

<rde-rd:username> (optional) Specification of user names; should always be specified. You can use wildcards: The asterisk (*) replaces an indefinite number of characters, whereas the question mark (?) replaces precisely one character.

517


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-rd:name> (optional) Specification of names. You can use wildcards: The asterisk (*) replaces an indefinite number of characters, whereas the question mark (?) replaces precisely one character.

<rde-rd:status> (optional, only for mode="standard") User status: "0" for inactive, "1" for active, "2" for blocked.

<rde-rd:language> (optional, only for mode="standard") Locale for the user's language that conforms to RFC 4646.

<rde-rd:group> (optional, only for mode="standard") Absolute path of a user group. You can use wildcards: The asterisk (*) replaces an indefinite number of characters, whereas the question mark (?) replaces precisely one character. Examples: Entering "Administrators.*" selects all child groups of the "Administrators" parent group. "Admin*" selects all groups whose paths begin with "Admin", including all child groups.

<rde-rd:role> (optional, only for mode="standard") User role; you must specify the exact role desired.

<rde-rd:role-param> (optional, only for mode="standard") Another parameter for the user role, such as project name. You must specify the exact parameter.

<rde-rd:created-from> (optional, only for mode="standard") User created since; date specified as inline function in the following format: [#request:from#].getDateAsLong(<date format>)

<rde-rd:created-to> (optional, only for mode="standard") User created to; date specified as inline function in the following format: [#request:from#].getDateAsLong(<date format>)

<rde-rd:last-logon-from> (optional, only for mode="standard") Last logon of user since; date specified as inline function in the following format: [#request:from#].getDateAsLong(<date format>)

<rde-rd:last-logon-to> (optional, only for mode="standard") Last logon of user to; date specified as inline function in the following format: [#request:from#].getDateAsLong(<date format>)

<rde-rd:password-expires> (optional, only for mode="standard") Password expired... days; Enter a value (0 to n) representing the minimum number of days since the expiration of a user password. "0" means that the password will expire on the current day.

<rde-rd:attributes> (optional, only for mode="standard") List of user attributes in individual <rde-rd:attribute> elements.

<rde-rd:attribute> (optional) Single user attribute. Only one <rde-rd:attribute> element can be specified in the "standard" mode of child element <rde-rd:user-filter>. Several elements can be specified in "redundant-structure" mode.

path (optional, alternative for parameter alias) Path of the user attribute.

alias (optional, alternative for parameter path) Alias of an attribute from a redundant DB structure for user attributes that was edited using an inline function.

518


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

op (optional, only for mode="redundant-structure") Logical operator of a constraint that compares the value of the user attribute with a specified value or semicolon-separated list of values. The user data is only output if the constraint is fulfilled. The following values are possible:

"eq": equal to

"ne": not equal to

"lt": less than

"gt": greater than

"le": less than or equal

"ge": greater than or equal

"containsany": contains

Value if nothing is specified: "eq"

Result

Returns a list of all the user data present in the system together with the selected user attributes for the users matching the filter criteria. If an output file is specified in the filename parameter, only this file is used for output.

Error Handling

The information, warning, and error messages for the User DynaMent begin with 6 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". For more information on the general return codes, please read the Error Handling section in the RedDot DynaMents chapter.

For more information about inline functions that you can use in the <rde-rd:user-filter> child element, see the separate section.

See also:

Inline Functions for Parameter Values (Page 29)Inline Functions as Reference (Page 569)

Example: Reading User Data and Attributes for Selected Users

<rde-dm:user mode="report" user="a*"

filename="c:/user.report.txt"/>

Result: In this example, all user attributes up to a depth of "10" and all the user data that exists in the system are output for users whose names starts with "A". The data is output to a CSV file (user.report.txt) in the specified directory.

519


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Reading User Data and Attributes for a Specific User

<rde-dm:user mode="report" user="beginner" resulttype="xml"/>

Result: All user attributes up to a depth of "10" and all the user data for "beginner" that exists in the system are output to the screen in the form of an XML file.

Example: Child element <attributes>

<rde-dm:user mode="report" resulttype="xml"> <attributes>

<attribute>address.street</attribute> <attribute>profile.level</attribute>

</attributes>

</rde-dm:user>

Result:

... <rde-idea:user-item login="admin">

<rde-idea:login>admin</rde-idea:login> <rde-idea:name>admin</rde-idea:name> <rde-idea:language>de</rde-idea:language> <rde-idea:country></rde-idea:country> <rde-idea:status code="1">STATUS_ACTIVE</rde-idea:status> <rde-idea:authstatus code="3">AUTH_ACCESSGRANTED</rde-

idea:authstatus> <rde-idea:created code="1028724392545">Wed Aug 07 14:46:32 GMT+02:00

2002</rde-idea:created> <rde-idea:lastlogin code="1028797798126">Thu Aug 08 11:09:58

GMT+02:00 2002</rde-idea:lastlogin> <rde-idea:lastpasswordchange code="0">Thu Jan 01 01:00:00 GMT+01:00

1970</rde-idea:lastpasswordchange> <rde-idea:autheticateldap></rde-idea:autheticateldap> <rde-idea:attributesldap></rde-idea:attributesldap> <rde-idea:cisasfallback>false</rde-idea:cisasfallback> <rde-idea:writetoldap>false</rde-idea:writetoldap> <rde-idea:updateinldap>false</rde-idea:updateinldap> <rde-idea:aftersynchrdelete>false</rde-idea:aftersynchrdelete> <rde-idea:delete>false</rde-idea:delete> <rde-idea:onlyadmindelete>false</rde-idea:onlyadmindelete> <rde-idea:synchrostatus>false</rde-idea:synchrostatus> <address>

<street>admin Str. 3</street> </address> <profile>

<level>6</level> </profile>

</rde-idea:user-item>

...

520


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Alongside the general user data for the "admin" user, the two user attributes "address.street" and "profile.level" are output.

Examples: Child Element <rde-rd:user-filter>:

<rde-dm:user mode="report" resulttype="xml"> <rde-rd:user-filter> <rde-rd:username>*</rde-rd:username> <rde-rd:last-logon-from> [#request:llf#].getDateAsLong("dd.MM.yyyy") </rde-rd:last-logon-from> </rde-rd:user-filter>

</rde-dm:user>

Result: This lists the user data of all the users who have logged on since the given date.

<rde-dm:user mode="report" resulttype="xml"> <rde-rd:user-filter>

<rde-rd:username>a*</rde-rd:username> <rde-rd:attributes> <rde-rd:attribute path= "[#request:attrPath#profile.level#]"

/> </rde-rd:attributes>

</rde-rd:user-filter>

</rde-dm:user>

Result: This lists the user data of all the users whose user names begin with "a" and who have the Request attribute "attrPath" or default attribute "profile.level."

521


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example: Redundant Database Structures in Child Element <user-filter>

<rde-dm:user mode="report" resulttype="xml" chunksize="10" chunk="1" report-tag="dm-report"> <rde-rd:user-filter mode="redundant-structure" db-structure="UserAttrStructure01"> <rde-rd:username>User*</rde-rd:username> <rde-rd:attributes> <rde-rd:attribute path="profile.level"

op="gt">3</rde-rd:attribute> <rde-rd:attribute path="profile.category"

op="eq">advanced</rde-rd:attribute> </rde-rd:attributes> </rde-rd:user-filter>

</rde-dm:user>

Result: User data that fulfills the following conditions is output:

The user name starts with "User".

The two user attributes "profile.level" and "profile.category" are

contained in the redundant database structure "UserAttrStructure01".

Attribute "profile.level" has a value greater than 3.

Attribute "profile.category" is set to "advanced".

522

DynaMent ReferencesWebComponent DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

WebComponent DynaMent

The WebComponent DynaMent enables you to access the Web components of RedDot LiveServer. In particular, the WebComponent DynaMent lets you integrate Web components and their Web modules in content.

The first time a Web module of a Web component is addressed within a session, RedDot LiveServer creates an instance of that Web module for the requesting session.


Integrating Web components in content (mode="include")

Reporting information about the current instances of Web modules in an active session (mode="session")

Removing instances of a Web module from a session (mode="remove")

Integrating CSS style sheets from a Web component (mode="include-css").

For more information about Web Components and Web Modules, see the Projects/Contents documentation.

Integrating Web Components ('include')

Function

The "include" mode of the WebComponent DynaMent integrates an instance of a Web Module in a content item in RedDot LiveServer. The result of the DynaMent is determined by the integrated Web Module. To enable this, the WebComponent DynaMent performs the following steps automatically:

1. Locate the Web Component and Web Module If the Web Component or Web Module is not found, or is not flagged as active, an error message appears.

2. Write the parameter values The parameter values of the Web Component and its Web Module, which are specified in the rde-dm:param child elements, are written each time the WebComponent DynaMent is called. This process is similar to that for calling an Attribute DynaMent. If certain parameter values are not specified, the default values from the definition of the Web Component or Web Module are used.

3. Create the Web Module instance RedDot LiveServer administers the Web Module instance automatically as an attribute of the current session. Several different instances with different names can be created for the same Web Module within a session.

4. Call the Web Module The Web Module is called by an Include DynaMent that is generated automatically at runtime. It integrates the controller content of the Web Module in the current content item.

523


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:webcomponent mode ="include"

project ="{project name}" component="{web component name}" module ="{web module name}" instance ="{instance name}" depth ="[0|1|...n]" >

<rde-dm:param name="{web component parameter name-1}" >

{param-1 value, optionally in CDATA } </rde-dm:param >

... <rde-dm:param name="{web component parameter name-n}" >

{param-n value, optionally in CDATA } </rde-dm:param >

</rde-dm:webcomponent >




Simple call

<rde-dm:webcomponent mode="include" component="component name"

instance="test" />

Parameters

mode Mode of the WebComponent DynaMent, here "include".

project (optional) Name of the project containing the Web Component. If nothing is specified: Current project

component Name of the Web Component.

module (optional) Name of the Web Module. If nothing is specified: The standard Web Module of the Web Component.

instance Definable name that identifies an instance of the Web Module within the session. The instance is created the first time it is used. Each instance has its own scope in which information concerning its status is administered.

524


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

depth (optional) To avoid endless loops in the WebComponent DynaMent's result, the depth parameter limits the number of nested executions of WebComponent DynaMents. If the limit specified in depth is reached, the corresponding DynaMent is no longer executed. Value if nothing is specified: "10"

Child Elements

The WebComponent DynaMent also has a child element called <rde-dm:param>. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-dm:param> (optional) You can use this child element to specify parameters and their values of the Web Module. These values are evaluated each time the WebComponent DynaMent is called. Notes: If any one parameter is defined in the DynaMent, this parameter value or the default value from the inline notation is used, even when the resulting value is blank. Only if a parameter of a Web Module is not specified at all, the default value specified in the Web Module is used. If no default value is available in the Web Module, the default value of the identically named parameter from the Web Component is used. The parameters are evaluated in the sequence in which they are defined in the Web Module, not in the sequence of the DynaMent. If a parameter is specified that is not defined in either the Web Module or the Web Component, it is ignored and a warning message is displayed (return code 30152).

Result

An Include DynaMent is generated automatically at runtime and inserts the controller content of the Web Module in the current content item. The result is determined by the integrated Web Module.

Error Handling

The WebComponent DynaMent's information, warning, and error messages begin with 30 in the thousands' place. You can send the return codes with the default parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following messages are possible:


-30520 Web Component not found

-30521 Web Component not active

-30550 Web Module not found

-30551 Web Module not active

-30552 Access constraint of a parameter not met

-30553 Access constraint of the Web Module not met

-30554 Action not found

30152 Parameter set but not defined for Web Component/Module

525


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Reading Instances of Current Sessions ('session')

Purpose

In "session" mode, the WebComponent DynaMent delivers information about the Web modules that are used in the active session. This mode is particularly useful for project managers, allowing them to monitor the development phase.

Syntax

<rde-dm:webcomponent mode ="session"

instance ="{instance name}" />




Simple Call

<rde-dm:webcomponent mode="session" instance="instance name" />

Parameters

mode Mode of the WebComponent DynaMent, here "session".

instance Definable name that identifies an instance of the Web module within the session. The instance is created the first time it is used. Each instance has its own scope in which information concerning its status is administered.

Results

Additional information about the instance of the Web module is returned.

526


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The WebComponent DynaMent's information, warning, and error messages begin with 30 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:

Remove Instances from Session ('remove')

Purpose

In "remove" mode, the WebComponent DynaMent removes an instance of a Web module you have specified from the current session, provided it exists.

Syntax

<rde-dm:webcomponent mode ="remove"

instance ="{instance name}" />




Simple Call

<rde-dm:webcomponent mode="remove" instance="instance name" />

Return code Meaning

-30520 Web component not found


-30550 Web module not found

-30551 Web module not active

527


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Parameters

mode Mode of the WebComponent DynaMent, here "remove".

instance Definable name that identifies an instance of the Web module within the session. The instance is created the first time it is used. Each instance has its own scope in which information concerning its status is administered.

Results

The instance of the Web module is removed from the active session.

Error Handling

The WebComponent DynaMent's information, warning, and error messages begin with 30 in the thousands' place. You can output the return codes with standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:

Integrating CSS Style Sheets from Web Components ('include-css').

Purpose

The "include-css" mode integrates a CSS style sheet from a Web component or Web module in a content item in RedDot LiveServer. The WebComponent DynaMent generates an HTML link element that references a CSS style sheet of a Web component.

Note: The "include-css" mode of the WebComponent DynaMent can only be used in the <head> area of an HTML content item.

The following cases are treated differently:

Integrating the standard CSS style sheet of a Web component The component parameter is specified in the DynaMent. The automatically generated standard CSS style sheet from the Web component (if any) is integrated.

Integrating a variant of the CSS style sheet from a Web component The component and variant parameters are specified in the DynaMent. The specified variant of the standard CSS style sheet from the Web component (if any) is integrated.

Return code Meaning

-30520 Web component not found


-30550 Web module not found

-30551 Web module not active

30151 Instance not found

528


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Integrating the standard CSS style sheet from a Web module The component and module parameters are specified in the DynaMent. The automatically generated standard CSS style sheet from the Web module (if any) is integrated.

Integrating a variant of the CSS style sheet from a Web module The component, module, and variant parameters are specified in the DynaMent. The specified variant of the standard CSS style sheet from the Web module (if any) is integrated.

Syntax

<rde-dm:webcomponent mode ="include-css" project ="{project name}" component="{web component name}" module ="{web module name}"

variant ="{variant name}" />




Simple Call

<rde-dm:webcomponent mode="include-css" component="component name" />

Parameters

mode Mode of the WebComponent DynaMent, here "include-css".

project (optional) Name of the project containing the Web Component. If no value is specified: Current project

component Name of the Web Component.

module (optional) Name of the Web module. If no value is specified: No Web module is used

variant (optional) Name of a variant of a CSS style sheet. Note on naming conventions for variants: The name of the automatically generated CSS style sheet is cmp<component name>Style1.css at Web Component level and mod<module name>Style1.css at Web Module level. The variant name must be specified as the name

529


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

component between Style and the file extension. Example for specifying a CSS style sheet named cmpTestStyleMy_Variant.css: <rde-dm:webcomponent... variant="My_Variant"... />.

If no value is specified: "1" (automatically generated default name for variants)

Notes

The "include-css" mode of the WebComponent DynaMent can only be used in the <head> area of an HTML content item.

Result

The DynaMent generates an HTML link element that references a CSS style sheet. It has the following basic structure:

<link rel="stylesheet" type="text/css" href="/cps/rde/xchg /#RDE-REQUEST:rdeSessionID/#/<projectname> /#RDE-REQUEST:rdeXslID/#/<css-name>" title="<web component name>_

<web module name>_<variant>" />

The value of the title attribute is composed dynamically, dependent on the values specified in the DynaMent.

Error handling

The WebComponent DynaMent's information, warning, and error messages begin with 30 in the thousands' place. You can send the return codes with the standard parameter "result-attribute". In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible:


-30570 CSS content not found

530

DynaMent ReferencesWebService DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

WebService DynaMent

The WebService DynaMent is only available with the appropriate license, which activates the WebService connectors and the WebService DynaMent.

The WebService DynaMent makes it possible to call a Web service via a WebService connector.


Calling a Web service using various methods

Receiving attachments via a Web service and processing them

For more information about connectors for Web services, see the Connectors documentation.

Calling Web Services

Purpose

The WebService DynaMent makes it possible to call a Web service via a Web service connector. When you call a Web service using the SOAP protocol, it is done chiefly by exchanging SOAP envelopes with the target server.

For each WebService DynaMent there is one child element with the name <rde-rd:soap-message>, in which the SOAP message is specified.

When a Web service has been successfully called, the connector is checked for result attributes for the operation called. If this is the case, the respective attributes in the request attributes are added and can then be requested via, for example, <rde-dm:attribute mode="read" or mode="condition"/>.

To receive content items as attachments, you need the attachment-attribute parameter. To send content items as attachments, use the additional child element <rde-rd:attachment>.

You can also use the <rde-rd:import> child element to add metadata to a content item.

Where nothing else has been specified, the processing of WebService DynaMents takes place in the application server components of RedDot LiveServer. This is done so that you can react to the WebService DynaMent results with further DynaMents.

531


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Syntax

<rde-dm:webservice name ="{connector name}" timeout ="{timeout in seconds}" cache-id ="{cache-id}" attachment-attribute ="{attribute name}" attachment-name-prefix ="{prefix name}" > <rde-rd:soap-message type ="[envelope|prepared|operation]" prepared-envelope ="{envelope name}" operation ="{operation name}" soapaction ="{soapaction}" > ...

</rde-rd:soap-message >

<rde-rd:attachment type ="[embedded|content|named]" mime-type ="{mime type}" content-id ="{content-id}" content ="{content name}" project ="{projectname}" ' locale ="{locale string}" encoding ="{encoding}" ref ="{reference}" > Inhalt bei type="embedded"...

</rde-rd:attachment>


</rde-rd:import>

</rde-dm:webservice

>




Parameters

name Name of a connector for a Web service defined in RedDot LiveServer.

timeout (optional) Interval in seconds after which the connection to the Web service server is terminated. If the server does not deliver the called content within this period, an error message is displayed. If nothing is specified: The Web service connector's timeout settings are valid. If no timeout is specified, the system default value of 10 seconds will apply.

cache-id (optional) Creates a cache entry (scope="request") in the object cache. Specify a content name. This will be the last element of the content key used to store the read

532


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

content (as RedDot LiveServer content) in the object cache. The content item contains the content data in the default language of the project to which the content is assigned. The cache-id is used as name for the content in RedDot LiveServer. If nothing is specified: No cache entries are created.

attachment-attribute (optional) Specification of a Request attribute in which the received attachment content IDs should be written as values. While the request is running, the attachments will be available under their corresponding content IDs (see also the following section: "Receiving and Editing Attachments"). If nothing is specified: No attachments will be available.

attachment-name-prefix (optional) A prefix placed in front of the attachment content IDs to uniquely identify the content IDs in all the various Web services.


Child Elements

The WebService DynaMent has three child elements. The <rde-rd:soap-message> child element is mandatory, <rde-rd:attachment> and <rde-rd:import> are optional. DynaMents within values of a child element are processed. Inline notation is supported.

<rde-rd:soap-message> Child element in which the SOAP message is specified. Note: DynaMents within a child element are processed; inline notation is supported.

type (optional) Method for calling a Web service. The following options are available:

"envelope": Uses an envelope transmitted by the <rde-rd:soap-message> element for calling a Web service. With the help of this DynaMent method, you can create a call of any complexity for creating the envelope itself.

"prepared": Uses an envelope prepared in the Web service connector. This contains the placeholder that can be called or replaced with the child elements of <rde-rd:soap-message>. The prepared envelope is selected using the attribute prepared-envelope: <rde-rd:soap-message type="prepared" prepared-envelope="search"> You only need to specify the relevant parameters for a call. The other parameters from the prepared envelope take their respective default values, if they are specified in the placeholder; otherwise they remain blank. Note: In all parameters of a prepared envelope, XML entities are replaced by default. To disable this replacement for individual parameters in special cases, assign the replace-entities="false" attribute to these parameters. Syntax: ...

533


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-rd:soap-message type="prepared" prepared-envelope="xy"> <parameter replace-entities="false">...</parameter> </rde-rd:soap-message>

...

"operation": Creates the appropriate envelope for the WSDL file operation specified in the Web service connector. The operation is selected via the "operation" attribute: <rde-rd:soap-message type="operation" operation="googleSearch">. All child elements of <rde-rd:soap-message> are considered to be parameters for the operation. In this case, you also have to pass on all the associated parameters. This variant may have its limitations.

Value if nothing is specified: "envelope"

prepared-envelope Use only for type="prepared": Name of the envelope specified in the Web service connector.

operation Use only for type="operation": Name of a WSDL file operation specified in the Web service connector.

soapaction (optional) Some Web services require the specification of the "soapaction", which is set in an HTTP header when an HTTP request is made (see example below).

<rde-rd:attachment> (optional) One or more child element, each of which creates an attachment and then passes it to the respective Web service call.

type (optional) Determines what content will be used as the attachment. The following options are available:

"embedded": The content will be specified directly in the DynaMent call.

"content": The content originates from the LiveServer Repository. To identify the content item precisely, the following parameters are used: "content," "project," and "locale".

"named": The content specified in the value of the ref parameter will be sent as an attachment. The content is a temporary file that was, for example, received via a Web service.


mime-type (optional) The specification of a MIME type that is used by the recipient to process the file that was received.


If type="embedded": "text/plain"

If type="content" or "named": There is an attempt to extract the MIME type from the content. For HTML content: "text/html"; for XML/XSL content: "text/xml"; for Script: "text/plain". If the content type cannot be determined: "application/octet-stream".

534


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

content-id (optional) Specification of an ID for identifying the attachment, if the attachment is to be sent as a reference. If nothing is specified: The ID automatically generated by AXIS.

content Only required for use with type="content": Name of the content item to be sent. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).

project (optional) Only for type="content": Name of the project from which the content originated. If nothing is specified: The name of the project in which the WebService DynaMent is located.

locale (optional) Only for type="content": Language to be used. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. If nothing is specified: Language specified in the language parameter, or the requesting user's language.

language (optional) Deprecated. Should no longer be used. Is evaluated if the locale parameter is missing, to ensure downward compatibility. Only for type="content": Language to be used. Use the RFC 4646 language codes as they are entered in the project settings of the relevant project, for example de or en-US. If nothing is specified: Language of the requesting user.

encoding (optional) Only for text type (XML, XSL, HTML, SCRIPT): Indicates how content is to be encoded for transmission. If nothing is specified: Operating system-specific default value.

ref Only required for use with type="named": Content name of the content item to be sent. If names of content and content groups are not unique project-wide: Value of the path name of the content item within the content group hierarchy. The path components are separated by slashes (example: modules/news/news.xml).


Result

The server response is a SOAP envelope (XML structure), which will be nested in the document in the place of the DynaMent. The result then can be displayed by using the appropriate XSL or called by using an XPath expression.

535


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Error Handling

The WebService DynaMent's information, warning, and error messages begin with 25 in the thousands' place. You can send the return codes with the default parameter "result-attribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible:


See also:

Using the Results (Page 19)XPath Statements in Parameters (Page 26)


-25320 One or more connector exceptions have occurred.

-25321 Cannot initialize the desired Web service.

-25326 Not all of the call's required parameters have been specified.

-25327 A valid envelope does not exist in the connector with the specified name 'prepared-envelope'.

-25328 Connection has timed out.

-25330 Missing <rde-rd:soap-message> element.

-25331 Parameter ‘type’ information missing in the <rde-rd:soap-message> element

-25332 Parameter ‘operation’ information missing in the <rde-rd:soap-message> element

-25333 Parameter ‘prep-envelope’ information missing in the <rde-rd:soap-message> element

-25520 This encoding is not supported.

-25521 Preparation of the attachment has failed (see the log file for details).

-25522 The server called did not return an envelope.

-25523 Result parameters could not be read. (could not be found/identified, etc.)

-25524 Could not identify a result parameter in the returned envelope.

-25525 The returned envelope contains a fault element. Points to a server-side error while processing the request.


25400 The connector is not active.

536


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Mapping MIME Types to RedDot LiveServer Content Types

When you import content to the LiveServer Repository, the MIME type and file extension of the content you are importing are automatically mapped to a RedDot LiveServer content type. This requires that the MIME type and the mapping have been declared to RedDot LiveServer. Both are read from the mimetype.txt file (located in the <RedDot Web application path>/WEB-INF/etc/ directory), which contains a wide range of mappings. If a MIME type is not listed in the file, you can add it.

If a MIME type is missing, the system attempts to identify the content type in RedDot LiveServer from the media type information given. A MIME type consists of the following information: media type and a sub type, separated by a forward slash (example: text/html).

Calling a Google search with your own envelope (type="envelope").

<rde-dm:webservice name="GoogleSearch"> <rde-rd:soap-message type="envelope"> <SOAP-ENV:Envelope xmlns:SOAP-ENV=

"http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC=

"http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi=

"http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd=

"http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Body> <m:doGoogleSearch xmlns:m="urn:GoogleSearch" SOAP-ENV:encodingStyle=

"http://schemas.xmlsoap.org/soap/encoding/"> <key xsi:type="xsd:string"> 7PgkYC1QFHIsB7xpj+pfGk+u+wMJNDhX</key> <q xsi:type="xsd:string">reddot</q> <start xsi:type="xsd:int">0</start> <maxResults xsi:type= "xsd:int">10</maxResults> <filter xsi:type= "xsd:boolean">false</filter> <restrict xsi:type="xsd:string"/> <safeSearch xsi:type= "xsd:boolean">false</safeSearch> <lr xsi:type="xsd:string"/> <ie xsi:type="xsd:string"/> <oe xsi:type="xsd:string"/> </m:doGoogleSearch> </SOAP-ENV:Body> </SOAP-ENV:Envelope> </rde-rd:soap-message>

</rde-dm:webservice>

537


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Calling a Google search with a prepared envelope (type="prepared"). In this example all of the parameters are predefined except "q".

<rde-dm:webservice name="GoogleSearch"> <rde-rd:soap-message type="prepared"

prepared-envelope="search"> <q>reddot</q>

</rde-rd:soap-message>


The parameter can also be read using an Attribute DynaMent:

<rde-dm:webservice name="GoogleSearch"> <rde-rd:soap-message type="prepared"

prepared-envelope="search"> <rde-dm:attribute mode="read" source="request"

attribute="query" tag="q"/> </rde-rd:soap-message>


The third variant addresses the operation via the WSDL file (type="operation"):

<rde-dm:webservice name="GoogleSearch"> <rde-rd:soap-message type="operation"

operation="doGoogleSearch"> <key xsi:type="xsd:string"> 7PgkYC1QFHIsB7xpj+pfGk+u+wMJNDhX</key> <q xsi:type="xsd:string">reddot</q> <start xsi:type="xsd:int">0</start> <maxResults xsi:type="xsd:int">10</maxResults> <filter xsi:type="xsd:boolean">false</filter> <restrict xsi:type="xsd:string"/> <safeSearch xsi:type= "xsd:boolean">false</safeSearch>

<lr xsi:type="xsd:string"/> <ie xsi:type="xsd:string"/> <oe xsi:type="xsd:string"/>



538


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Using the "soapaction" parameter:

<rde-dm:webservice name="MorseCode"

report-tag="report"> <rde-rd:soap-message type="prepared"

prepared-envelope="GetMorseCode"

soapaction="GetMorseCode">

<msg>RedDot</msg>



Sending attachments in child element<rde-rd:attachment>:

<rde-dm:webservice name="Import" timeout="120" report-tag="report"> <rde-rd:soap-message prepared-envelope="singleContentImport" type="prepared"> <rde-dm:attribute mode="read" tag="sessionID" attribute="session" source="request"/> <name>abcdef2.xml</name> <type>XML</type> <attachment>12345</attachment> </rde-rd:soap-message> <rde-rd:attachment content="cont-countries.xml" content-id="12345" type="content"/>


539


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Sending attachments that have been received via the WebService DynaMent:

 <rde-dm:webservice name="DemoService" attachment-attribute="attachments" attachment-name-prefix="att_" report-tag="report"> <rde-rd:soap-message prepared-envelope="getAttachments" type="prepared"/> </rde-dm:webservice>  <rde-dm:webservice name="DemoService" timeout="120" report-tag="report"> <rde-rd:soap-message prepared-envelope="sendAttachments" type="prepared"/> </rde-dm:webservice>  <rde-dm:attribute mode="for-each" tag="notag" attribute="attachments" source="request" alias="attachment" type="children"> <rde-rd:attachment type="named"> <rde-dm:attribute mode="read" tag="ref" attribute="attachment" source="context" op="parent"/> </rde-rd:attachment>

</rde-dm:attribute>

Receiving and Processing Attachments

This section provides details on receiving and processing attachments using the WebService DynaMent.

To receive content items as attachments with the WebService DynaMent, you definitely need theattachment-attribute parameter, and optionally the attachment-name-prefix parameter (also see the previous section, "Calling a Web Service").

Receiving Attachments

Attachments usually consist of a header (such as content type or MIME type) and the data. To make this information available as attribute values of the attachment-attribute, a child attribute is created for every attachment (corresponding to the content ID), which receives these values. The attribute itself has the number of attachments received as a value. You can access the individual attachments and their headers with an Attribute DynaMent in for-each mode.

For the actual content of the attachment, a temporary content item is created, which is assigned a unique name and stored in the object cache. You can use the processing methods below to access this content.

540


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Sample call: <rde-dm:webservice name="DemoService" attachment-attribute="attachments" attachment-name-prefix="att_" report-tag="report">

[...] </rde-dm:webservice>

 <rde-dm:attribute mode="for-each" attribute="attachments" source="request" alias="attachment" type="children"> <rde-dm:attribute mode="read" attribute="attachment.Content-Type" source="context"/>

 <rde-dm:include content="[#context:attachment#]"/>  <rde-dm:reference content="[#context:attachment#]" scope="session" mode="set-

scope"/> 

<rde-dm:attribute mode="for-each" attribute="attachment" source="context" alias="attachmentHeader" type="children"> <rde-dm:attribute mode="read" attribute="attachmentHeader" source="context" value="name"/> <rde-dm:attribute mode="read" attribute="attachmentHeader" source="context" value="value"/> </rde-dm:attribute> </rde-dm:attribute>

</rde-dm:attribute>

For two of the files returned by the Web service (test1.xml and test2.xml), the above call results in this Request attribute structure:

Request: -attachments : 2 -att_CID223233445 : <name of content item in object cache> -Content-Type : text/xml -LSContentType : XML -att_CID234233234 : <name of content item in object cache> -Content-Type : text/xml

-LSContentType : XML

The file names are not usually included in the attachment headers. You can determine them using the SOAP envelopes returned by the Web service call (which vary from Web service to Web service).

The content type entry corresponds to the MIME type as specified in the attachment header. The LSContent type is the resulting conversion to RedDot LiveServer content types (XML, BLOB, HTML, XSL,...)

Processing Attachments

Inserting with the Include DynaMent

<rde-dm:include content="[#<ContentID>#]"/> The content ID can be specified via inline notation.

Creating a Link/Reference to the attachment (content), particularly for non-text MIME types via the Reference/Link DynaMent. The attachment is initially valid only within the request. Its validity must be increased to the duration of the session (scope="session"), to ensure the attachment is

541


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

available for other links. It is also useful to specify a timeout (in seconds), to ensure attachments do not use server resources longer than is necessary. <rde-dm:reference content="[#context:attachment#]" scope="session"

mode="set-scope" timeout="300" /> To address the attachment later, its content ID should be transferred to a session attribute. <rde-dm:attribute mode="write" attribute="sessionAttachment"

source="session" value="[#context:attachment#]"/> The Reference DynaMent creates a link to the content using the xchg or xbcr Weblet. They request the content from the cache and then deliver the content stored there. Note: The names of the attachment from the Web service response are used as the name of the attachment. These names may not be suited to URLs and in terms of technical relevance. You can therefore change the names using the Reference DynaMent mode="set-cache-id" if necessary.

Deleting Attachments from the Cache Early (scope=session) To delete an attachment from the object cache before the validity of the session expires, use the Content DynaMent in notify-cache mode, with an attachment parameter for referencing the attachment in the cache.

<rde-dm:content mode="notify-cache" attachment="[#context:attachment#]"/>

Creating a Content Item Processing with the Content DynaMent <rde-dm:content mode="import" content="1BLOB.gif" ref-type="named" ref="[#context:attachment#]" importtask="Test" importdef="Test2" type="blob" locale="en" encoding="ISO-8859-1" archive="false" release="true" overwrite="true" overwrite-group="true" fulltext-search="false" delete-after-import="false" report-

tag="ContentImport_Report"/>

See also:

Calling Web Services (Page 531)Setting the Validity of Entries in the Object Cache ('set-scope') (Page 306)Editing Content Names in the Object Cache ('set-cache-id') (Page 308)Removing Content from the Cache ('notify-cache') (Page 129)

For more information about using Web services to receive and process attachments, see the Users/Administration documentation.

542

DynaMent ReferencesWrapper DynaMent

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Wrapper DynaMent

The Wrapper DynaMent is used to enclose (wrap) a content item and then call it again in a different environment.

This section contains the following information:

How to use the Wrapper DynaMent to call content in a new environment

What a detailed example of a news wrapper looks like

Calling Content in New Environments

Purpose

The Wrapper DynaMent is used to enclose (wrap) a content item and then call it again in a different environment. The same content is rendered using two different style sheets. The DynaMent automatically creates a link using a new page. The Wrapper DynaMent can be compared to a dynamic link routing or a call to a Web page in a frame environment. The link in the first page that is used to call the next content item consists of the XML, the corresponding XSL and the wrapper call in an additional Link DynaMent.

Syntax

<rde-dm:wrapper-template />

The standard parameters cannot be used.

Notes

To use the Wrapper DynaMent, you will need the following construction:

An XML document A (XML-A) with a container and Includes/references to the content that is to be wrapped.

An XML document B (XML-B) which, for example, represents a news item with title, teaser and text elements.

An XSL document A (XSL-A) which acts on XML-A. The title and teaser, for instance, are output for each Include/reference element in the container while a link is inserted in place of the text element. The Link DynaMent contains a reference to the wrapper that is called in XML-C.

These three documents result in a single page which contains multiple sections with a title, text and link.

AN XML document C (XML-C) contains the actual wrapper call. The wrapper acts on the XML-B content and searches for an XSL style sheet that can be applied to XML-B.

An XSL document B (XSL-B) is the appropriate style sheet for XML-B and may, for instance, cause the title, teaser, and text of news items to be displayed on a separate page for each news item.

These two documents each result in the pages, which are called via the links on the first page.

543


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Example of a News Wrapper

The following example consists of the following five files:

XML file with news container via Includes (cont_news)

XML file for the individual news items (news_1)

XSL file for a container with the Link DynaMent and wrapper reference (hs-cont-news)

XML file with the wrapper call itself (newswrapper)

XSL file for the complete individual news item (hs-news)

The file names used in the example below are given in parentheses. The direct references to the wrapper are printed in bold.

cont_news (xml) <rde-dm:container type="include" id="cont-news" tag="cont-news"> <rde-dm:include project="testcr" content="news_1"/> <rde-dm:include project="testcr" content="news_2"/>

</rde-dm:container>

news_1 (xml) <news> <title>Europe By Air Network Adds Another Airline</title> <teaser>The popular network offers a system of $99 ...</teaser> <text>The popular Europe By Air Network offers a system of $99 ....</text> <rde-dm:reference project="demo" content="plane_jpg" tag="image"/> <rde-dm:reference project="demo" content="news_1" tag="link"/> <rde-dm:reference project="demo" content="arrow_community_blue_gif" tag="link_image"/>

</news>

hs-cont-news (xsl) <xsl:template match="//cont-news"> <P> <small>

<rde-dm:reddot method="html" alt="Click here to add a new content" mode="container" show="yes"/> </small> </P> <xsl:for-each select="news">

<rde-dm:reddot method="html" alt="Click here to edit the content" mode="edit"/>

<table width="410" border="0" cellspacing="0" cellpadding="0"> <tr> <td width="15"/> <td align="left"/> <td width="15"/>

</tr> <tr> <td width="15"/> <td width="380" align="left" valign="top" class="Text">

<table border="0" cellspacing="0" cellpadding="0" align="left">

<tr> <td align="left" width="105" height="71">

544


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-dm:image method="html" tag="image" border="0"/> </td> <td width="8"/> </tr> </table> <span class="Headline"> <xsl:value-of select="title"/> </span> <br/> <xsl:value-of select="teaser"/> <rde-dm:link method="html" wrapper="newswrapper"> <br/> <rde-dm:link-param name="back" value="{$ioeXmlID}"/>more... </rde-dm:link> <a href="/upandaway/11_25.html"> <img src="/{$ioePrefix}/xbcr/{$ioeSessionID}/{$ioeProjectID}/

arrow_magazine_white_gif" width="16" height="16" align="RIGHT" border="0"/>

</a> </td> <td width="15"/>

</tr> </table>

</xsl:for-each>

</xsl:template>

newswrapper (xml) <master-news>

<rde-dm:wrapper-template/>

</master-news>

hs-news (xsl) <xsl:template match="//news"> <rde-dm:reddot method="html" alt="Click here to edit the content" mode="edit"/> <table width="410" border="0" cellspacing="0" cellpadding="0">

<tr> <td width="15"/> <td align="left"/> <td width="15"/>

</tr> <tr>

<td width="15"/> <td width="380" align="left" valign="top" class="Text"> <table border="0" cellspacing="0" cellpadding="0" align="left"> <tr> <td align="left" WIDTH="105" HEIGHT="71"> <rde-dm:image method="html" tag="image" border="0"/> </td> <td width="8"/> </tr> </table> <span class="Headline"> <xsl:value-of select="title"/> </span> <br/> <i> <xsl:value-of select="teaser"/> </i> <xsl:value-of select="text"/> <rde-dm:link method="html" xml="{$back}"> Back... </ioe-dm:link>

</td>

545


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<td width="15"/> </tr>

</table>

</xsl:template>

546

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Appendix

The appendix to this handbook contains lists with predefined attributes and placeholders, standard functions included, and other information for your reference.

Topics covered in this chapter include:

Predefined Attributes and Placeholders (Page 548)Inline Functions as Reference (Page 569)

547

AppendixPredefined Attributes and Placeholders

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Predefined Attributes and Placeholders

RedDot LiveServer uses a series of attributes with predefined names for its internal operations. You can use these attributes in your projects as well but, as a rule, they cannot be overwritten.

Predefined attributes exist, above all, for the following object types:

Request (source="request")

Session (source="session")

Content (source="content")

User (source="user")

System (source="system").

In addition, you will find information about the following topics in this appendix:

The placeholders replaced by RedDot LiveServer right before publication

The standard parameters provided by RedDot LiveServer for rendering with XSL

"rde" and "rde-rd" Prefixes

Most predefined attribute names start with one of these prefixes:

"rde"

"rde-rd:"

Please do not use these prefixes in the names of your own attributes.

For more information about the attributes of the various object types, see the separate sections.

See also:

Variable Parameter Values (Page 20)Inline Notation for Parameter Values (Page 20)Multiple Sources: The 'source' Parameter (Page 22)

Predefined Attributes for source='request'

The "request" source has a number of attributes that are preset to specific functions.

Note: RedDot LiveServer uses the reserved attribute names of the source "request" to access specific Weblet information. These attributes are set depending on a request; they are not available for every request. Every Weblet can implement the prepareRequest(..) method, which is called by RedDot

548


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

LiveServer before it is processed by the handleRequest(..) Weblet method. When delivering content, in particular the Exchange Weblet (Alias: "xchg") initializes variables, above all those of the source="request", which are very important for processing content.

cpssessionid Alternative for addition in the URL path: Specifies the ID of the RedDot LiveServer session to use for the active request. The attribute is not entered in the dependency list for the component cache, but it is displayed in the Used in the preview for debugging mode.

rde-rd:content-type MIME type string of the body of HttpServletRequest. Generated via the HttpServletRequest.getContentType() method of the Servlet API.

rde-rd:dynament-result Return code of the last processed DynaMent.

rde-rd:httpHeader-{Http-Protocol-Header-Name} All fields of the HttpServletRequests are read transferred to the source="request" with name prefix "rde-rd:httpHeader-", where they are available in the Attribute DynaMent.

rde-rd:httpHeader-method The HTTP method of the HttpServletRequest is read and transferred to the source="request" with its value (GET, POST), where it is available in the Attribute DynaMent.

rde-rd:path-info Part of a URL string between the Servlet path and the Query string. Generated using the HttpServletRequest.getPathInfo() method of the Servlet API.

rde-rd:query-string The part of the request URL following the path. Generated using the HttpServletRequest.getQueryString() method of the Servlet API.

rdeAbsolutePrefix String composed of the rdeContextRoot and rdeServletMapping variables, separated by a slash "/".

rdeContentFixedRendering For handling XML content during rendering. If you specify rdeContentFixedRendering="yes", content-fixed XSL engines are used during rendering. In this process, the XML content is not recalculated, but instead is submitted to the XSL-bound rending engine.

rdeContentProjectId Name of the project containing the processed content. You can use this value, for example, to determine the project name of content integrated using an Include DynaMent. RedDot LiveServer writes this attribute automatically, and enters it in the dependency list of the component cache. It is only displayed, however, if log category 50 is active.

rdeContextPath Part of the URL for the current request that refers to the context path. The context path is always the first part of a URI. It starts but does not end with the "/" character; any URL encoding is not decoded. For the root context, the empty string "" is used. Generated using the HttpServletRequest.getContextPath() method of the Servlet API.

rdeContextRoot The value for the context root of the RedDot LiveServer Web application in the Servlet container, as set in the reddot.idea.appserver.contextroot key of the system configuration. Value if nothing is specified: "" (empty string)

549


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

rdeCurrentLocale Language of the processed content. This parameter is only available during processing. It can be read, but not written. RedDot LiveServer writes this attribute automatically, and enters it in the dependency list of the component cache. It is only displayed, however, if log category 50 is active.

rdeCurrentProjectId Project name of the currently processed request sent to the Exchange Weblet. The current project name can be different from the one contained in the initializing URL if, for example, a PSX component from a different project is required to deliver the page. Is set in the Exchange Weblet and is thus available for processing content. RedDot LiveServer writes this attribute automatically, and enters it in the dependency list of the component cache. It is only displayed, however, if log category 50 is active.

rdeCurrentXmlId Name of the currently requested content. Note that if DynaMents are used for processing, a different content item than the one requested may be returned. This change is not usually reflected in the specified rdeCurrentXmlId attribute automatically. Is set in the Exchange Weblet and is thus available for processing content. RedDot LiveServer writes this attribute automatically, and enters it in the dependency list of the component cache. It is only displayed, however, if log category 50 is active.

rdeCurrentXslId Name of the currently requested style sheet used to render content requested via the exchange Weblet. You can select a different XSL style sheet for use during processing by entering the name of the desired XSL content (style sheet's XSL content type) in the attribute's value—for example, via the Attribute DynaMent. Is set in the Exchange Weblet and is thus available for processing content. RedDot LiveServer writes this attribute automatically, and enters it in the dependency list of the component cache. It is only displayed, however, if log category 50 is active.

rdeHttpServer Protocol and server name including the port, to be used as a URL prefix when passing from http protocol to https protocol (SSL). The string is composed of the following parts:

1. "http://"

2. Value of the reddot.nodename key defined in the system configuration. entry configured in the startup.conf file ("LOCAL" is converted to "localhost").

3. If available, value for the reddot.server.port key defined in the system configuration, separated by a ":"

rdeHttpsServer Protocol and server name including the port, to be used as a URL prefix when passing from http protocol to https protocol (SSL). The string is composed of the following parts:

1. "https://"

2. Value of the reddot.https.server key defined in the system configuration. entry configured in the startup.conf file ("LOCAL" is converted to "localhost").

3. If available, value for the reddot.https.port key defined in the system configuration, separated by a ":"

rdeInternalCaller Identifies the calling location of the Weblet, usually the "MasterServlet".

550


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

rdeLocale Optional parameter with which you can specify the language of the content to be returned by a live mode request (see also rdeSessionLocale). If the rdeLocale parameter is not specified or written, the language of the user in the current session will be used. The rdeLocale attribute remains empty. If a content item is not available in the specified language, it will be delivered in the language specified in the Locale-Policy. In some DynaMents, the request attribute rdeLocale is replaced by the DynaMent parameter locale while the DynaMent is running. The locale parameter is used in the Query, Target, and Include DynaMents, among others.

rdeLocaleAttr Special attribute for switching languages. When specified as the URL parameter of a live mode request, RedDot LiveServer uses the parameter value to set the user attribute "rde.locale" of the user of the current session. This means that the current and subsequent session requests will be answered in the specified language, if nothing else is specified (see also the rdeLocale attribute).

rdePageKey The key used to enter the current page as a component of the component cache, excluding the language ID, which is added later. Is set in the Exchange Weblet and is thus available for processing content.

rdePathparam-{Path-Parameter} All path parameters of a URL path segment including their values and the name prefix "rdePathparam-" are transferred to the source="request". They are thus available to the Attribute DynaMent.

rdePrefix Value for the rdeAbsolutePrefix variables, excluding their leading slash "/".

rdeProjectID Project name of the current request sent to the Exchange Weblet. Unlike the rdeCurrentProjectID attribute, rdeProjectID always stands for the project name requested by the initializing URL. Is set in the Exchange Weblet once per external request and is thus available for processing content.

rdeRequestRelId Sequential number of the current request in the current session.

rdeResponseCdataMode Handling of CDATA sections during rendering. RedDot LiveServer writes this attribute automatically, and enters it in the dependency list of the component cache. It is only displayed, however, if log category 50 is active. The following values are possible:

"hide": Default setting; CDATA sections are not used for rendering.

"render": CDATA sections are used for rendering unchanged.

rdeResponseCharset Defines the "charset=" parameter value of the content type header field, if its value has been set. Otherwise, a charset is selected that matches the locale of the current session.

rdeResponseMimetype Defines the delivered MIME type of the header field content type, provided its value has been set. Otherwise the standard "text/html" is selected, or the MIME type that was assigned when RedDot LiveServer was uploaded is selected for BLOB type content. Example of defining the MIME type for a CSS content item: <rde-dm:attribute mode="write" attribute="request:rdeResponseMimetype"

551


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

op="set" value="text/css"/> The following is an example of a call for BLOB type content, used to force the browser download dialog where the content is displayed to open: /cps/rde/xbcr/demo/100a.jpg?rdeResponseMimetype=force-download/liveserver

rdeResponseStatus Sets the HTTP status of the page delivered by RedDot LiveServer. LiveServer overwrites this status if a serious error occurs. A description of possible status values is available in RFC 2616 at http://www.rfc.net/rfc2616.html#s6.1.1

rdeServletMapping The value for the Servlet Mapping of the RedDot LiveServer MasterServlets in the Servlet-Container, as set in the reddot.idea.masterservlet.pathprefix key of the system configuration. Value if nothing is specified: "rde".

rdeServletPath Part of the URL of the current request that stands for the name or path of the Servlet called; any URL encoding is already decoded. Generated using the HttpServletRequest.getServletPath() method of the Servlet API.

rdeServletServer Is determined using the Servlet API method HttpServletRequest.getServerName(); the value for getServerPort() is appended, separated by a colon, if a port is specified in the URL.

rdeSessionID ID of the RedDot LiveServer session used for the current request. Is set in the Exchange Weblet and is thus available for processing content. The attribute is not entered in the dependency list for the component cache, but it is displayed in the Used in the preview for debugging mode.

rdeSessionLocale Optional parameter with which you can specify the language of the content to be delivered for the current request as well as all other requests of the current session. Entering a locale with the rdeLocale request parameter overwrites the rdeSessionLocale entry for the current request. If the rdeSessionLocale parameter is not specified or written, the language of the user in the requesting session will be used. If a content item is not available in the specified language, it will be delivered in the language specified in the Locale-Policy.

rdeUrlParamSessionID ID of the RedDot LiveServer session used for the current request. Based on the client browser's cookie capability. The value is blank if all of the following are true:

The client supports cookies, which means the rdeClientCookies="yes" parameter is set in the corresponding session

The session ID is written as a cookie in the project

The session ID is delivered as a cookie

If the client does not support cookies, the value is cpssessionid=rdeSessionID. This enables you to construct URLs that only pass the session ID on as a parameter if it cannot be delivered as a cookie. Is available when processing content and throughout the entire request. The attribute is not entered in the dependency list for the component cache, but it is displayed in the Used in the preview for debugging mode.

552


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

rdeUrlPathSessionID ID of the RedDot LiveServer session used for the current request. Based on the client browser's cookie capability. The value is blank if all of the following are true:

The client supports cookies, which means the rdeClientCookies="yes" parameter is set in the corresponding session

The session ID is written as a cookie in the project

The session ID is delivered as a cookie

If the client does not support cookies, it is composed of the value itself, a slash "/", and the rdeSessionID attribute. This enables you to construct URLs that only pass the session ID on as a path component if it cannot be delivered as a cookie. Is available when processing content and throughout the entire request. The attribute is not entered in the dependency list for the component cache, but it is displayed in the Used in the preview for debugging mode.

rdeWeblet Alias name of the currently called Weblet, as defined in the system configuration. Is set in the Exchange Weblet and is thus available for processing content.

rdeXmlID Name of the currently requested content. Unlike the rdeCurrentXmlId attribute, rdeXmlID always stands for the content name requested by the initializing URL. Is set in the Exchange Weblet once per external request and is thus available for processing content.

rdeXslID Name of the currently requested style sheet. Unlike the rdeCurrentXslId attribute, rdeXslID always stands for the style sheet name requested by the initializing URL. Is set in the Exchange Weblet once per external request and is thus available for processing content.

rdeXslXmlSeparator This placeholder generates a separator, "/-", in projects that do not have name uniqueness throughout projects. If a project has name uniqueness, the placeholder is blank. You can use this attribute, for example, in expressions to generate URLs for requests to RedDot LiveServer that have to be correct in projects both with and without name uniqueness.

Predefined Attributes for source='session'

The "session" source has a number of attributes that are preset with specific functionalities.

rdeAdminSessionId For internal use only. Session ID for switching from the preview to the RedDot LiveServer administration interface.

rdeClientCookies Provides information about the client browser's cookie capability: "yes": Client browser supports cookies "no": Client browser does not support cookies " ": Result of the check uncertain.

553


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

rdeCurrentLocale Language of the session This parameter is set during authentication. It can be read, but not written.

rdeDefaultProjectId Determines the project whose event definitions and attribute assignments are accessed after a session timeout and during logoff. The attribute is written automatically by a User DynaMent in "login" mode. It can be read and written by the Attribute DynaMent.

rdeErrorInfoCurrent URL of the last request for this session Exception: Not set for requests to the standard Weblet for delivering BLOB content (alias: "xbcr").

rdeErrorInfoFirst URL of the first request for this session. Exception: Not set for requests to the standard Weblet for delivering BLOB content (alias: "xbcr").

rdeErrorInfoHome URL of the default document (rendered with the default style sheet) for the current project. Exception: Not set for requests to the standard Weblet for delivering BLOB content (alias: "xbcr").

rdeErrorInfoLast URL of the last request for this session that resulted in a page delivery. Exception: Not set for requests to the standard Weblet for delivering BLOB content (alias: "xbcr").

rdeErrorInfoPrefix String composed of the application ID and name of the master servlet, with slash "/" as separator: Default: “cps/rde”

rdeErrorInfoProject Project name of the last request

rdeErrorInfoSid ID of the RedDot LiveServer session used for the last request

rdeErrorInfoXml Name of the last content item requested

rdeErrorInfoXSL Name of the last style sheet requested

rdePreviewSessionId For internal use only. Session ID for switching from the administration interface to the RedDot LiveServer preview.

rdeTimeout Specifies the period without user activity (in minutes) after which the current user session is deleted and the user logged off from the system. This attribute can be read and written by the Attribute DynaMent. It is not saved after the session.

rde-rd:idea.masterservlet.currenturl URL of the last request for this session. Exception: Not set for requests to the standard Weblet for delivering BLOB content (alias: "xbcr"). The attribute is not entered in the dependency list for the component cache, but it is displayed in the Used in the preview for debugging mode.

554


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

rde-rd:idea.masterservlet.homeurl The homeurl should contain a URL that allows the end users of a RedDot LiveServer project to return to the start page of their current project. Set to initial as call for the default document of the default project via the Exchange Weblet, rendered with the default style sheet. Every time the Exchange Weblet is called via the MasterServlet of RedDot LiveServer, that is, when a page is delivered to the end user, the project name in the homeurl is set to the current project. Also available as a value for the <%HOME%> placeholder in the error message pages located in the ...\var\html directory.

rde-rd:idea.masterservlet.lasturl The last independent URL request for this session that resulted in delivery of content. Is determined from the "Referer" header field of the current request. Also available as a value for the <%LAST%> placeholder in the error message pages located in the ...\var\html directory.

rde-rd:idea.masterservlet.repeaturl Similar to rde-rd:idea.masterservlet.currenturl, but with two differences: any existing rdeLocaleAttr URL parameters are removed and the value ends with "?" or "&" so that URL parameters may be suffixed.

rde-rd:remote-address Address of the client that last sent a request to RedDot LiveServer with this RedDot LiveServer session. Set in the MasterServlet of RedDot LiveServer at every request.

rdeServerAlias Alias of the current server, which has been assigned in the system configuration file (key: reddot.liveserver.alias). The attribute can be read but not written by the Attribute DynaMent.

rde-rd:sid Session ID of this RedDot LiveServer session. The attribute can be read but not written by the Attribute DynaMent. The attribute is not entered in the dependency list for the component cache, but it is displayed in the Used in the preview for debugging mode.

Predefined Attributes for source='content'

The "content" source has a number of attributes that are preset with specific functionality.

rde-fields Parent attribute that encapsulates several attributes provided by RedDot LiveServer automatically. These attributes can be read, but not written, using the Attribute DynaMent. The provided attributes mirror properties of the repository user object. One attribute is provided for each property for which a getter method is documented with exactly one primitive parameter in the CoaContent class of the Open API. The name of these attributes is taken from the name of the getter method: The "get" prefix is omitted and the subsequent letter is converted to lower case.

Example: Method: long::getCachingTime() becomes attribute: rde-fields.cachingTime

555


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

The list of attributes may be changed and/or extended in future versions of the Open API. For more information, see the Open API documentation. You can also display and change many of the properties in the Edit Content dialog window. The following attributes are provided:

cachingTime: Caching time in minutes.

contentType: Numeric code of the content type. Possible values: 0 (XML), 1 (XSL), 2 (BLOB), 4 (Script), 7 (HTML).

creationTime: Creation time of the content, specified in milliseconds since 1970-01-01.

creator: Name of the user who created the content.

description: Description of the content.

fullTextSearch: Determines whether the search engine will index the content (possible values: "true" or "false").

groupAlias: Alias name for the content group of the content.

groupName: Name for the content group of the content.

groupPath: Path for the content group of the content.

inheritEvents: Determines whether the content will inherit events (possible values: "true" or "false").

lastEditor: Name of the user who last edited the content.

lastEditTime: Time the content was last changed, measured in milliseconds since 1970-01-01.

name: Name of the content.

path: Path of the content (group path and name, separated with "/")

status: Release status of the current content; possible values: -1 (Released), -2 (Draft). This value is always -1, because only released content is selected for delivery in projects.

syncId: Internal version identifier of the content in the LiveServer Repository. The version ID is displayed in system time in milliseconds when the content was last released.

validFrom: Time from which the content is valid, specified in milliseconds since 1970-01-01.

validTo: Time to which the content is valid, specified in milliseconds since 1970-01-01.

rdeRepository.rdeContentInfo Only used for content that is read from an external repository (see Repository DynaMent, mode="read"): Default name of the attribute under which information is saved about the content read from the repository. This information is added as child attributes.

rdeRepository.rdeMetainfo Only used for content that is read from an external repository (see Repository DynaMent, mode="read"): Default name of the attribute under which metadata is saved for the content read from the repository.

556


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Predefined Attributes for source='user'

The "user" source has a number of attributes that are preset to specific functionalities. These attributes enable you to read user information:

rde-fields Parent attribute that encapsulates several attributes that RedDot LiveServer provides automatically. These attributes can be read and (in some cases) written using the Attribute DynaMent. The provided attributes mirror properties of the repository user object. One attribute is provided for each property for which a getter method is documented with exactly one primitive parameter in the CoaUser class of the Open API. The name of these attributes is taken from the name of the getter method: The "get" prefix is omitted and the subsequent letter is converted to lower case. If a corresponding setter method is documented in the CoaUser class, then you can also use the Attribute DynaMent to write the attribute.

Example: Method: long::getCreationTime() becomes attribute: rde-fields.creationTime

Note: The values of this object always refer to the copy of the user object that was created for the active RedDot LiveServer session. As a result, the values can differ from the corresponding values in the repository. These changed values are updated in the repository after logoff or a session timeout.

The list of attributes may be changed and/or extended in future versions of the Open API. For more information, see the Open API documentation. You can also display and change many of the properties in the Edit User dialog window. The following attributes are provided:

authenticationStatus (read): Logon status of the current session's user. Possible values: 0 (AUTH_INVALIDLOGIN), 1 (AUTH_NEWSESSION), 2 (AUTH_ACCESSDENIED), 3 (AUTH_ACCESSGRANTED)

authenticationSystem (read/write): Name of the preferred directory service (or "LiveServer Repository") for authentication.

cookieStatusFlags (read/write): The user's cookie settings, encoded in a number mask.

creationTime (read): Creation time of the user object, specified in milliseconds since 1970-01-01.

directoryServiceAlias (read/write): Name of the directory service (or "LiveServer Repository") used to authenticate the user.

forceCPSAuthenticationAsFallback (read/write): Setting that determines whether or not to use the LiveServer Repository for authentication if the preferred directory service is not available. Possible values: "true" and "false".

forceNewPasswordOnLogin (read/write): Setting that determines whether the user has to change his or her password after the next logon. Possible values: "true" and "false".

illegalLogins (read): Number of failed logon attempts since the last logon. The value of this attribute is always zero, because the user of the active session is always logged on.

language (read/write): User's preferred language. Format: Language tag as defined by RFC 4646.

lastLoginTime (read): Time of the user's last logon to RedDot LiveServer, measured in milliseconds since 2007-01-01.

lastPasswordChangedTime (read): Time the user's password was last changed, measured in milliseconds since 2007-01-01.

557


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

login (read): User's logon name.

name (read/write): Name of the user.

passwordDigest (read): Password digest saved in the LiveServer Repository.

passwordValidDays (read): Number of days for which the user's password is valid.

sessionMultiplicity (read/write): Setting for the logon type. Defines whether a user is allowed multiple sessions on RedDot LiveServer and what to do in case of doubt. Possible values: -2 (MULTIPLICITYTYPE_UNKNOWN), -1 (MULTIPLICITYTYPE_DEFAULT), 0 (MULTIPLICITYTYPE_SEVERAL), 1 (MULTIPLICITYTYPE_SINGLENEW), 2 (MULTIPLICITYTYPE_SINGLEOLD)

sessionTimeout (read/write): Default value of the active user's session timeout for RedDot LiveServer, in minutes.

status (read/write): Status of the current user. Possible values: 0 (STATUS_INACTIVE), 1 (STATUS_ACTIVE), 2 (STATUS_DISABLED).

rde-groupattributes (read) Parent attribute in which the attributes of the user groups to which the user belongs are recorded automatically during logon. These attributes then serve as reference values; they cannot be written.

rde-groups (read) Specifies the user groups to which the user is assigned. All the names of a user's assigned groups are saved as values of this multivalued attribute.

rde-roles (read) Specifies the roles to which the user is assigned. All the names of a user's assigned roles are saved as values of this multivalued attribute. If a role is valid for a project, the project name is added to the role name, along with a hyphen.

Predefined Attributes for Source 'user' for Loaded Users

When users are loaded into a session using the User DynaMent, there are several attributes in source "user" that already have assigned functions.

To access the data of another user via the User DynaMent in an active session, this data must first be stored hierarchically in the form of user attributes of the active session, using the User DynaMent with mode="load" . Beginning with a root attribute, which is selected via the path parameter of the User DynaMent (default: rde-edit-user), the four types of user properties are stored in the following four attribute branches:


rde-groups: Groups

rde-roles: Roles


rde-attributes Attributes of the loaded user. An attribute is provided for each attribute of the loaded user.

rde-fields Information regarding the loaded user's fields. The following attributes are provided beneath rde-fields. If the user originated in the LiveServer Repository, changes to the values of

558


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

these attributes can be written back with the User DynaMent in mode="update". When the user was read from a directory service, the settings and assignments defined in the respective directory service connector apply.

authenticationStatus: Logon status of the current session's user. Possible values: 0 (AUTH_INVALIDLOGIN), 1 (AUTH_NEWSESSION), 2 (AUTH_ACCESSDENIED), 3 (AUTH_ACCESSGRANTED)

authenticationSystem:Name of the preferred directory service (or "LiveServer Repository") for authentication.

cisFallbackAuthentication: Setting that determines whether or not to use the LiveServer Repository for authentication if the preferred directory service is not available. Possible values: "true" and "false".

cookieStatus: The user's cookie settings, encoded in a number mask.

created: Creation time of the user object, specified in milliseconds since 1970-01-01.

directoryServiceLink: Name of the directory service (or "LiveServer Repository") used to authenticate the user.

force-password-change: Setting that determines whether the user has to change his or her password after the next logon. Possible values: "true" and "false".

illegalLogins: Number of failed logon attempts since the last logon.

lastChange: Time the user object was last changed, measured in milliseconds since 2007-01-01.

lastLogin: Time of the user's last logon to RedDot LiveServer, measured in milliseconds since 2007-01-01.

lastPasswordChange: Time the user's password was last changed, measured in milliseconds since 2007-01-01.

lastPersistentChange: Time the user object was last changed in the repository, measured in milliseconds since 2007-01-01.

localeString: User's preferred language. Format: Language tag as defined by RFC 4646.

login: User's logon name.

multiplicityType: Setting for the logon type. Defines whether a user is allowed multiple sessions on RedDot LiveServer and what to do in case of doubt. Possible values: -2 (MULTIPLICITYTYPE_UNKNOWN), -1 (MULTIPLICITYTYPE_DEFAULT), 0 (MULTIPLICITYTYPE_SEVERAL), 1 (MULTIPLICITYTYPE_SINGLENEW), 2 (MULTIPLICITYTYPE_SINGLEOLD)

name: Name of the user.

password (write only): User's password. The password cannot be read from the LiveServer Repository because it is not saved there. You can set a value to change the password with the User DynaMent in mode="update". If the user was read from a directory service, you cannot use this method to change the password (at least in the majority of cases).

passwordValidDay: Number of days for which the user's password is valid.

559


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

passwordValidStatus: Number of days for which the user's password will be valid unchanged.

sessionLockTimeOut: Default value for the maximum idle time, after which the user has to log on to the administration interface again, in minutes.

sessionTimeOut: Default value of the active user's session timeout for RedDot LiveServer, in minutes.

status: Status of the current user. Possible values: 0 (STATUS_INACTIVE), 1 (STATUS_ACTIVE), 2 (STATUS_DISABLED).

rde-groups Specifies the groups to which the loaded user is assigned. For each group that the user belongs to, an attribute is created whose value contains the path and name of the group. The name of this attribute begins with group and ends with a sequential number.

rde-roles Specifies the roles to which a user is assigned. For each role that the user belongs to, an attribute is created whose value contains the path and name of the role. The name of this attribute begins with "role" and ends with a sequential number.

See also:

Using the User DynaMent (Page 475)Loading Users to Active Sessions ('load') (Page 502)Updating Users ('update') (Page 506)Creating Users ('create') (Page 499)

Predefined Attributes for source='system'

The "system" source has a number of attributes that are preset with specific functionalities.

cps.log No special function; an attribute of this name can be neither read nor written.

cps.log.categories Activates/deactivates log recording. Possible values: "all" = all categories activated; "none" = all categories deactivated; "standard" = use default settings from the system configuration. Note: This attribute can only be written and not read.

cps.log.categories.{category number} Activates/deactivates log recording for the respective category. This attribute can be read and written. Possible values: "on" = activated; "off" = deactivated. You can find the numbers for the various categories in the Set Log Configuration dialog window (Main Menu -> Administer RedDot LiveServer -> Configuration -> Log Configuration -> Configure).

cps.log.level Lets you specify a level for writing log entries. This attribute can be read and written. Possible values: Any integer between "0" and "5". The numbers correspond to those in the reddot.logging.level key in the system configuration (e.g., "5" = "debug").

560


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

modulesdir Placeholder for the WEB-INF\modules directory under the RedDot Web application (for example: ...tomcat\webapps\cps\WEB-INF\modules). Subfolders to this directory are used to store Jar files for Web components. Note: This attribute can only be read and not written.

rdeAbsolutePrefix String composed of the rdeContextRoot and rdeServletMapping variables, separated by a slash "/".

rdeContextRoot The value for the context root of the RedDot LiveServer Web application in the Servlet container, as set in the reddot.idea.appserver.contextroot key of the system configuration. Value if nothing is specified: "" (empty string)

rdeHttpServer Protocol and server name including the port, to be used as a URL prefix when passing from http protocol to https protocol (SSL). The string is composed of the following parts:

1. "http://"

2. Value of the reddot.nodename key defined in the system configuration. entry configured in the startup.conf file ("LOCAL" is converted to "localhost").

3. If available, value for the reddot.server.port key defined in the system configuration, separated by a ":"

rdeHttpsServer Protocol and server name including the port, to be used as a URL prefix when passing from http protocol to https protocol (SSL). The string is composed of the following parts:

1. "https://"

2. Value of the reddot.https.server key defined in the system configuration. entry configured in the startup.conf file ("LOCAL" is converted to "localhost").

3. If available, value for the reddot.https.port key defined in the system configuration, separated by a ":"

rdeServletMapping The value for the Servlet Mapping of the RedDot LiveServer MasterServlets in the Servlet-Container, as set in the reddot.idea.masterservlet.pathprefix key of the system configuration. Value if nothing is specified: "rde".

webappdir Placeholder for the RedDot Web application directory (for example: ...\tomcat\webapps\cps). Note: This attribute can only be read and not written.

Predefined Placeholders

The placeholders described here help you avoid having to store large numbers of unnecessary variants in the component cache.

Attribute placeholders A simple example: You want to greet your customers by name; therefore, you add the following Attribute DynaMent to your content:

561


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<rde-dm:attribute mode="read"

attribute="name" />

During processing, the value of the user attribute "name" is inserted into the content and the rendered content saved in the component cache. But, of course, your customers have various names. Which means that you would have to create a variant for every customer in the component cache. And this would require large amounts of memory and result in an ineffective use of cache.

The solution is to use an attribute placeholder for the names instead of the names themselves. Then all that is required in the component cache is a variant (in this example), which contains the placeholder. Because placeholders are replaced only shortly before publication, in other words, after reading the cache, they produce the same results with a single cache variant. You insert placeholders as follows:

<rde-dm:attribute mode="reference"

attribute="name" />

The mode="reference" creates the following placeholder (which you can insert without a DynaMent):

#RDE-USER:name/#

Other placeholders are used to insert system variables and those specifically requested, such as path, session ID, and project name variables. This eliminates the need to create cache variants for all the value combinations.

PSX module placeholders You can also use placeholders for entire page areas. Example: You present a page containing general news applicable for many users, but also containing an area with information dedicated specifically to an individual user. You could solve this problem with the Include DynaMent:

<table> <tr><td> <rde-dm:include content="top-news.htm" /> </td></tr> <tr><td> <rde-dm:include content="user-news.htm" /> </td></tr>

</table>

The complete page needs to contain individual content from the user news area, which means you need to create an individual cache variant for each user. In this case it would be better to replace the user news area with a placeholder. Then the surrounding page only needs a single cache variant. The placeholder then represents a rendered HTML section of the user news, and will be inserted once you specify the desired style sheet in the Include DynaMent:

<table> <tr><td> <rde-dm:include content="top-news.htm" /> </td></tr> <tr><td> <rde-dm:include content="user-news.htm" stylesheet="ht-news.xsl" /> </td></tr>

</table>

562


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

When the page is called, the surrounding page is read from the component cache. Once that is complete the placeholder is replaced and RedDot LiveServer internally requests the rendered components {project}/ht-news.xsl/user-news.htm and inserts them in place of the placeholders. These rendered components, which are called via placeholders, are called PSX modules, because the placeholders contain the names to the respective project, style sheet, and XML (content). PSX modules are nothing more than the rendered content areas of pages, which, like complete pages, are inserted by way of a normal request to the RedDot LiveServer xchg Weblet via placeholders.

Weblet module placeholders Weblet module placeholders let you go a step further, replacing placeholders with the results of a Java call (using the handleRequest(...) method of a Weblet) instead of making another call to the RedDot LiveServer. In this case, it means performance advantages for high-load applications, because you are not relying on the automatic functions of the RedDot LiveServer. You insert a Weblet module placeholder by means of an Include DynaMent by specifying the name of the desired Weblet. Optionally you can also specify request parameters with content="...". When using Weblet modules to call Weblets, you use the WebletAdapter.callWeblet(...), which is described in the Open API documentation. The following example makes use of a fictional news Weblet, which in actual use would require you to replace its name with the name of the desired Weblet alias.

<table> <tr><td> <rde-dm:include content="top-news.htm" /> </td></tr> <tr><td> <rde-dm:include weblet="news-weblet" content="id=user-news.htm" /> </td></tr>

</table>

Inline Function: replacePlaceholders

You can use the inline function replacePlaceholders to replace all placeholders with their values. Example:

Set a registry entry: rdeMyPlaceholder = "#RDE-REQUEST:rdeAbsolutePrefix/#/ #RDE:REQUEST:rdeWeblet}/#/ #RDE-REQUEST:rdeUrlPathSessionId/#

Reference a registry entry with: "#RDE-FUNCTION:replacePlaceholders: #RDE-REGISTRY:rdeMyPlaceholder/#/#"

563


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

See also:

Referencing Attributes ('reference') (Page 75)Integrating Internal or External Content (Page 160)Including Weblet Module Placeholders (Page 177)Predefined Attributes for source='request' (Page 548)Predefined Attributes for source='session' (Page 553)Predefined Attributes for source='user' (Page 557)Predefined Attributes for source='system' (Page 560)

Syntax of Preassigned Placeholders

This section first describes the general syntax of the preassigned placeholders. The possible placeholders are then listed for your reference.

Placeholders

always begin with the string "#RDE-"

followed by one of the following area/object type IDs:

FUNCTION Inline functions

PSX Rendered components (PSX modules)

SESSION Attributes of the active session

SYSTEM Attributes of the RedDot LiveServer runtime environment

REGISTRY Attributes of the RedDot LiveServer registry

REQUEST Attributes of the current request

URL URLs of RedDot LiveServer

USER User attributes

WEB Weblet modules for calling a Weblet directly

supplemented with the following:

Use ":" to separate other specifications identifying objects, such as attribute names and Weblet names.

Use "#" (optional) to separate information pertaining to default values if the respective object value is empty or missing (not with "RDE-FUNCTION:", "RDE-PSX:", "RDE-URL", or "RDE-WEB:")

564


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Use "#" (optional) to separate information pertaining to an inline function with parameters, which will be applied to the returned values (see inline-function parameter of the Attribute DynaMent mode="reference"). Note: If an inline function but no default value is specified, the separator "#" must appear twice: The first represents the place of the missing/empty default value.

"RDE-WEB:": Prefixes optional parameter information with "/$$parameter:??"

Always end with the string "/#"

Placeholders can be nested. Example: #RDE-FUNCTION:trim().substring(1,3):#RDE-REQUEST:test/#/#

Note: The "#" character cannot be used in either attribute names or default values.

Placeholders for Reference

#RDE-FUNCTION:{functions}:{value}/# Placeholder for an inline function. {functions}: Inline functions with arguments. {value}: First parameter of the inline function. The placeholder is replaced by the result of the executed inline function. Example: #RDE-FUNCTION:trim().substring(1,3): test/#/#

#RDE-PSX:{project}{style sheet}{content}//$$parameter:??{{parameter}={value}} /# Placeholder for a rendered component (PSX module). The parameters are inserted by the Include DynaMent if its style sheet="..." parameter has been specified. The placeholder is replaced with the rendered components identified by the parameter. The value of the rendered components (where available) is read from cache, or it will be determined by another automatic, internal request to the Exchange Weblet. Example: #RDE-PSX:demo/hs-login-psx.xsl/login.xml//$$parameter:??cachingtime=30/#

#RDE-REGISTRY:{Attribute}/# Placeholder for an attribute of the RedDot LiveServer registry. The name of the Registry attribute is specified as {attribute}. The placeholder is replaced by the value of the respective Registry attribute. Example: #RDE-REGISTRY:reddot.xmaps.default.project/#

#RDE-REQUEST:{Attribute}/# Placeholder for a Request attribute of the current request. The name of the Request attribute is specified as {attribute}. The placeholder is replaced with the value of the respective Request attribute of the current request. Example from the python script for event definitions for the event "Content event - on load": /#RDE-REQUEST:rdePrefix/#/xchg/#RDE-REQUEST:rdeSessionID/#/#RDE-

REQUEST:rdeProjectID/#/#RDE-REQUEST:rdeXslID/#

#RDE-SESSION:{Attribute}/# Placeholder for a Session attribute of the requesting session. The name of the Session attribute is specified as {attribute}. The placeholder is replaced with the value of the respective Session attribute of the current session. Example: #RDE-SESSION:rdeClientCookies/#

565


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

#RDE-SYSTEM:{Attribute}/# Placeholder for an attribute of the RedDot LiveServer runtime. The name of the Runtime attribute is specified as {attribute}. The placeholder is replaced by the value of the respective runtime environment attribute. Example: #RDE-SYSTEM:cps.log.level/#

#RDE-URL:{URL}/# Placeholder for path components in URLs in RedDot LiveServer. This placeholder helps simplify the handling of URLs for the xchg and xfw Weblets. The placeholder is replaced with the necessary path components automatically for the respective Weblet (rdeAbsolutePrefix, rdeWeblet, rdeSessionID, rdeProjectID, rdeXslID, rdeXmlID). The placeholder lets you skip supplementing URLs with these path components, since missing components are added automatically to the calling URL. You only have to specify the components if they differ from the call of the current page, for example, when changing projects or Weblets. Example: "#RDE-URL:content1.html/#"

#RDE-USER:{Attribute}/# Placeholder for a User attribute. The User attribute's path name is specified as {attribute}. The placeholder is replaced with the value of the respective User attribute of the user of the current session. Example: #RDE-USER:profile.favorite#0/#

#RDE-WEB:{weblet-alias}/$$parameter:??{query-string}/# Placeholder for calling a Weblet. The parameters are inserted by the Include DynaMent if its weblet="..." parameter has been specified. The placeholder is replaced by the result of the called Weblet. To be more precise, it is replaced by the string that the called Weblet wrote in the transmitted WebletResponse using the method WebletResponse.setWebModuleResultString( String ). Example: #RDE-WEB:mediator/$$parameter:??baseURL=www.reddot.com//#

Inline Function: replacePlaceholders

You can use the inline function replacePlaceholders to replace all placeholders with their values. Example:

Set a registry entry: rdeMyPlaceholder = "#RDE-REQUEST:rdeAbsolutePrefix/#/ #RDE:REQUEST:rdeWeblet}/#/ #RDE-REQUEST:rdeUrlPathSessionId/#

Reference a registry entry with: "#RDE-FUNCTION:replacePlaceholders: #RDE-REGISTRY:rdeMyPlaceholder/#/#"

566


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

See also:

Referencing Attributes ('reference') (Page 75)Integrating Internal or External Content (Page 160)Including Weblet Module Placeholders (Page 177)Predefined Attributes for source='request' (Page 548)Predefined Attributes for source='session' (Page 553)Predefined Attributes for source='user' (Page 557)Predefined Attributes for source='system' (Page 560)

Predefined XSL Parameters

In RedDot LiveServer, the content delivered via the Exchange Weblet is rendered using an XSL engine only if the requesting URL contains the name of the XSL content item as a style sheet. Prior to rendering, XSL engines receive XSL parameters that allow individual control of the rendering process, even if a prepared XSL engine from the rendering engine pool is being used.

The role of the XSL parameters is outlined below in conjunction with the steps of the rendering process:

1. First, the XSL content is processed (just like any other content). XSL contents can also contain DynaMents.

2. Next, RedDot LiveServer prepares an XSL engine, which receives the processed XSL as a transformation template. This XSL engine is added to the rendering engine pool. The engine is not confined to an individual session but is used universally if permitted by the attributes of the dependency list. You can view a list of pool entries currently not in use under Administer RedDot LiveServer -> Monitoring -> Cache -> Show Rendering Engine Pool.

3. Before the actual rendering starts, the XSL engine is removed from the pool and receives parameters. The parameters allow you to control the rendering process without having to change the XSL transformation template. In the next section, we will outline how to use XSL parameters in RedDot LiveServer.

4. Now the actual rendering starts.

5. Once rendering is complete, the respective XSL engine is returned to the pool.

All attributes of the current request are passed to the XSL engine as XSL parameters. The parameters must be declared in standard XSL notation in the XSL style sheet before they can be used. See the following syntax:

<xsl:param name="{parameter-name}" />

The XSL syntax is also used to access the parameters, for example, {$rdeSessionID}.

If an XSL style sheet from RedDot LiveServer is used for rendering, all the attributes of the current request will be passed to the XSL engine. To be able to access the request attributes in XSL, you must declare them as global XSL parameters in the style sheet. RedDot LiveServer automatically adds the following declarations:

<xsl:param name="rdeContextRoot" />

<xsl:param name="rdeHttpServer" />

<xsl:param name="rdeHttpsServer" />

567


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

<xsl:param name="rdePrefix" />

<xsl:param name="rdeProjectID" />

<xsl:param name="rdeRedDot" />

<xsl:param name="rdeSessionID" />

<xsl:param name="rdeWeblet" />

<xsl:param name="rdeXmlID" />

<xsl:param name="rdeXslID" />

The meaning of the parameter corresponds to the meaning of the respective predefined attribute of the source="request". You can add further declarations to access other attributes of the current request in the style sheet.

See also:

Using Attributes in XSL Files ('xslparam') (Page 95)Predefined Attributes for source='request' (Page 548)

568

AppendixInline Functions as Reference

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Inline Functions as Reference

The next section describes the inline functions as reference included with this software. You can write your own inline functions in Java to complement those already available.

See also:

Inline Functions for Parameter Values (Page 29)Inline Function: Integrating Your Own Classes (Page 30)

Inline Functions as Reference

All inline functions automatically receive the value to be evaluated as a standard parameter. This value is either the result of the inline notation directly preceding this inline function or the return value of the previous inline function. Examples:

Value to be processed from the inline notation: [#request:txLogin#].trim()

Value to be processed from the previous inline function: [#request:txLogin#].trim().toLowerCase()

applyRule(java.lang.String rule) Applies the attribute rule specified in the rule parameter to the value to be evaluated and returns the result. If the application of the rule results in an error, the original value is returned. The applyRule inline function can only be used during processing and not when placeholders are replaced.

Return The value to be evaluated, which may have been changed by the rule.

asInteger() Removes all white spaces before and after the value to be evaluated and displays the value as an integer. If the value to be evaluated is not an integer, it is displayed as zero (0). White-space characters are spaces, tabs, lines, form feeds, and carriage returns.

Return Displays the integer of the value that is to be processed as a string or where this is not possible, displays "0".

asInteger(int defaultValue) Removes all white spaces before and after the value to be evaluated and displays the value as an integer. If the value to be evaluated is not an integer, it is displayed by the value for defaultValue. White-space characters are spaces, tabs, lines, form feeds, and carriage returns.

569


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Return Displays the integer of the value that is to be processed as a string or where this is not possible, displays the defaultValue as a string.

asString() Encloses the value to be evaluated with double quotes ("), provided these do not yet exist (as " characters or " entities).

Return The value enclosed in quotes.

concat(int intConcat) Adds the string display of the integer intConcat to the value to be evaluated and returns a result.

Return The composite string.

concat(String value) Adds the string specified in value to the value to be evaluated and returns the result.

Return The composite string.

convertEntitiesToText() Replaces entities found in the value to be evaluated with their respective values and returns the result. It replaces the entities defined in the configurable RedDot LiveServer Doctype file. The default Doctype file includes definitions for all commonly used HTML entities, such as ä for "ä" (a-Umlaut). The file is installed in this path: .../var/xml/doctype.txt. You can change this file or use a parameter in the system configuration (key: reddot.xmaps.xml.doctype.file) to specify a different file.

Return The string with the entities replaced by their respective values.

convertTextToEntities() Replaces all characters found in the value to be evaluated that correspond to an entity with the respective entity and returns the result. It replaces those characters that are values for an entity, as defined in the configurable RedDot LiveServer Doctype file. The default Doctype file includes definitions for all commonly used HTML entities, such as ä for "ä" (a-Umlaut). The file is installed in this path: .../var/xml/doctype.txt. You can change this file or use a parameter in the system configuration (key: reddot.xmaps.xml.doctype.file) to specify a different file.

Return The string with the characters replaced by their respective entities.

570


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

decode(String charSet) Applies the standard procedure URLDecoder.decode and the specified character set (parameter: charSet) to the value to be evaluated and returns the result.

Return The decoded value.

encode(String charSet) Applies the standard procedure URLEncoder.encode and specified character set (parameter: charSet) to the value to be evaluated and returns the result.

Return The encoded value.

encodeMailHeader(String charSet, String encodingMode) Applies the specified character set (parameter: charSet) and encoding procedure (parameter: encodingMode) to the value to be evaluated and returns the result. Possible values for the encodingMode parameter are "B" and "Q". "B": Base64 encoding; "Q": quoted-printable encoding.

Example: <rde-dm:attribute mode="write" attribute="subject" source="request" value="testäöü"/> <rde-rd:subject>[#request:subject#defaultSubject#].encodeMailHeader(UTF-8,

Q)</rde-rd:subject>

Return The encoded value.

endsWith(java.lang.String strPostfix) Checks whether the value to be evaluated ends with the string strPostfix and returns true or false.

Return Returns true if the value ends with the string strPostfix, otherwise false.

getDateAsLong(java.lang.String pattern) Transforms the value to process into a date, according to the defined pattern, and returns the number of milliseconds since January 1, 1970 as a large integer in string format.

The date pattern is evaluated according to the java.text.SimpleDateFormat documentation. If the value to be evaluated cannot be transformed into a date, an empty string is returned.

Return The number of milliseconds since January 1, 1970, in string format or as an empty string.

getDateFromLong(java.lang.String pattern) Transforms the value to be evaluated into an integer according to the given pattern. Evaluates the integer as milliseconds that have elapsed since January 1, 1970, and calculates the date in the form of a string based on the date pattern.

571


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Return The displayed date or an empty string.

getDateHeaderValue() If response header fields require a date, this function returns the value to write. The current time is shifted (in minutes) by the value to process. The value must be a character string that represents a number.

Return The displayed date for the response header fields in the format: EEE, dd MMM yy HH:mm:ss z.

getDateHeaderValue(String value, int moveMinutes) If response header fields require a date, this function returns the value to write. The current time is shifted (in minutes) by the value in moveMinutes. The result is independent of the value to be processed.

Return The displayed date for the response header fields in the format: EEE, dd MMM yy HH:mm:ss z.

getFormattedDate(java.lang.String patternFrom, java.lang.String patternTo) Transforms the value to be evaluated according to the patternFrom date pattern and reformats it according to the patternTo date pattern.

If the value to be evaluated cannot be transformed into a date, an empty string is returned.


getSystemDate(java.lang.String pattern) Returns the current system date in string format based on the date pattern. The result is independent of the value to be processed.


getSystemDate(java.lang.String pattern, int intMoveDays) Returns the current system date according to the date pattern in string format, +/- the number of days specified in intMoveDays. The result is independent of the value to be processed.


getSystemDateAsLong() Returns the current system date as the number of milliseconds that have elapsed since January 1, 1970, in string format. The result is independent of the value to be processed.


572


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

getSystemDateAsLong(int intMoveDays) Returns the current system date as a number of milliseconds since January 1, 1970, in string format, +/- the number of days specified in intMoveDays. The result is independent of the value to be processed.


removeUrlParameter(java.lang.String paramName, int prepareParamAppend) Removes from the value to be evaluated, which is usually interpreted as a URL, all URL parameters with the name paramName with their values and returns the result. If prepareParamAppend equals 1, the result has "?" or "&" in final position, so an additional URL parameter can follow directly.

Return The processed value including replacements.

replace(java.lang.String strFrom, java.lang.String strTo) Replaces all instances of string strFrom in the evaluated value with the string strTo and returns the result.


replacePlaceholders(java.lang.String value) Replaces all specified placeholders from RedDot LiveServer by its values and returns the results in the edited value.


split(java.lang.String strSeparator, int tokenNumber) Searches the value to be evaluated for a separator specified in the strSeparator string, splits the value to be evaluated that is found between the separators into tokens, and returns the token specified as tokenNumber. Tokens are counted from "1". If negative numbers are specified, then the tokens are counted backwards, starting with "-1". The characters of the string separator are not included in the tokens. If the specified token cannot be determined, an empty string is returned.

Return The desired token or empty string.

startsWith(java.lang.String strPrefix) Checks whether the value to be evaluated ends with the string strPrefix and returns true or false.

Return Returns true if the value begins with the string strPrefix, otherwise false.

573


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

substring(int beginIndex) Returns the rest of the value to be evaluated beginning with the character position beginIndex. Counting starts at zero.

Example: Assume URL parameter strTest has the value abcdefg. [#request:strTest#].substring( 3 ) -> defg

Return The desired portion of the value to be evaluated.

substring(int beginIndex, int endIndex) Returns the portion of the value to be evaluated from the character position beginIndex up to the character position endIndex (exclusive). Counting of the character positions starts at zero.

Example: Assume URL parameter strTest has the value abcdefg. [#request:strTest#].substring( 3, 5 ) -> de

Return The desired portion of the value to be evaluated.

toArray() Splits the value to be evaluated into substrings at each semicolon, and removes all white-space characters from the beginning and end of the value to be evaluated.

Return The value to be evaluated, split into substrings.

toArray(String separator, String delimiters, String doTrim) Splits the value to be evaluated into substrings at every separator specified in String separator. The characters in String separator, which are enclosed by the delimiters specified in String delimiters, are not interpreted as separators. doTrim removes all white-space characters from the beginning and the end of the value to be evaluated.

Return The value to be evaluated, split into substrings.

toFileUri(String value) Creates an URI in the file:[path] form from the value to be evaluated. It is, for example, used for class paths of hot deployment configurations in transport packages to ensure correct URLs in different systems. The URL depends on the operating system.

Example: [#system:webappdir#].toFileUri()WEB-INF/modules/test.jar becomes

Under Linux: file:///home/[user]/tomcat/webapps/cps/WEB-INF/modules/test.jar

Under Windows: file:c:\tomcat\webapps\cps\WEB-INF/modules/test.jar.

574


Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Return An URI in the file:[path] form from the value to be evaluated.

toLowerCase() Changes all letters of the value to be evaluated into their corresponding lower-case letters.

Return The value converted to lower case letters.

toString() The value to be evaluated is of the String Array type. If it is a value list, all values are evaluated. Concatenates all the values in the string array in a string, separating them with semicolons, and returns them in the result.

Example: Assume URL parameter strTest has three values: a, b, and c. [#request:strTest#].toString() -> a; b; c

Return The values, separated by semicolons, as a string.

toString(String separator) The value to be evaluated is of the String Array type. If it is a value list, all values are evaluated. Concatenates all the values in the string array in a string, separating them with the String separator string, and returns them in the result.

Return The values, separated by the String separator, as a string.

toUpperCase() Changes all letters of the value to be evaluated into their corresponding upper-case letters.

Return The value in all caps.

trim() Removes all white-space characters from the beginning and end of the value to be evaluated. White-space characters are spaces, tabs, lines, form feeds, and carriage returns.

Return The value trimmed of white spaces.

See also:

Inline Functions for Parameter Values (Page 29)Inline Function: Integrating Your Own Classes (Page 30)

575

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Index

A

application integrationIolet DynaMent .............................188Portal DynaMent ..........................252Portlet DynaMent ......................... 259

attachmentsMessage DynaMent ...................... 235WebService DynaMent .................531

Attribute DynaMentattributes

copying ..................................... 80moving ..................................... 83renaming .................................. 78

datachecking ................................... 61deleting .................................... 88reading ..................................... 40reading multivalued .................. 69referencing ............................... 75saving ....................................... 93writing ...................................... 49

general ........................................... 40in XSL files ..................................... 95modes

condition .................................. 61copy ......................................... 80delete ....................................... 88flush ......................................... 93flushcookies ............................. 91for-each .................................... 69move ........................................ 83read .......................................... 40reference .................................. 75remove ..................................... 86rename ..................................... 78write ......................................... 49xslparam .................................. 95

valuesdeleting from value list ............. 86

writing cookies ............................... 91

attribute placeholders .......................564

attributeschecking constraints ...................... 61copying .......................................... 80deleting ......................................... 88in XSL ............................................. 95moving ........................................... 83placeholders ................................561

attributes (continued)reading .......................................... 40

multivalued .............................. 69subattributes ............................ 69

referencing .................................... 75renaming ....................................... 78source ........................................... 22values

deleting from value list ............. 86writing ........................................... 49

explicitly .................................. 93to cookies ................................ 91

B

breakProcess DynaMent ....................... 267

C

Cache DynaMentcontent

removing from cache .............. 107general .......................................... 97modes

add-dependency .................... 103notify ...................................... 107set-id ...................................... 100set-scope ................................. 97

cache entriesdependencies .............................. 103removing ..................................... 107renaming ..................................... 100validity ........................................... 97

cachingtimestandard parameter ....................... 31

categoriesin repositories ...................... 391, 393

chartsReporting DynaMent .................... 334

check resultrecording ..................................... 120

child elementsContent DynaMent ....................... 110Iolet DynaMent ............................ 188Message DynaMent ..................... 235MetaData DynaMent .................... 243Script DynaMent .......................... 402

576

Index

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

child elements (continued)Target DynaMent ..........................461User DynaMent .............................514

CMSDynaMents ..................................... 17

constraintsAttribute DynaMent ........................ 61importing .....................................141Target DynaMent ..........................461

contentas source ....................................... 22attributes

importing ................................141Cache DynaMent ............................ 97checking ......................................120checking into repository ...............382checking out from repository ........387constraints

importing ................................141Content DynaMent

general ...................................110creating in repository ................... 357deleting in repository ................... 378delivering metadata .....................243general ........................................... 38Import DynaMent ......................... 140Include DynaMent ........................160inserting ......................................160MetaData DynaMent .....................243preset attributes ..........................555Process DynaMent .......................264reading from the repository ..........342Reference DynaMent ....................301removing locks .............................389updating in repository ..................368WebComponent DynaMent ...........523

content attributesimporting .....................................141inline notation ............................... 20

content classesin repositories ...................... 391, 393

Content DynaMentcontent

deleting ..................................126importing ................................110removing data ........................127removing from cache ..............129

general .........................................110modes

delete .....................................126import ....................................110

Content DynaMent (continued)modes (continued)

notify-cache ........................... 129remove-data ........................... 127validate .................................. 120

content importImport DynaMent ......................... 141

content versionsincluding ..................................... 180

contextas source ....................................... 22

continueProcess DynaMent ....................... 269

cookiesas source ....................................... 22Attribute DynaMent ........................ 91deleting ......................................... 49linking ........................................... 49writing ..................................... 49, 91

CPS DynaMentgeneral ........................................ 131modes

ID ........................................... 131

cps.log.categories ............................. 560

cps.log.level ...................................... 560

cpssessionid ..................................... 548

D

databaseRDB DynaMent ............. 289, 293, 295

delete listsimporting ..................................... 154

diagramsReporting DynaMent .................... 334

DynaMentsdefinition ....................................... 15general .......................................... 14processing ..................................... 17structure ........................................ 16syntax ............................................ 16tasks ............................................. 38

E

editinggeneral .......................................... 38RedDot DynaMent ........................ 298

577

Index

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

e-mailMessage DynaMent ...................... 235

error handling ...................................... 36general ........................................... 33

external data sourcesRDB DynaMent .............................289

F

folder entriesin repository .................................395

folderscreating in repository ................... 363deleting in repository ................... 380updating in repository ..................374

formatting rulesAttribute DynaMent

read .......................................... 40write ......................................... 49

forwardProcess DynaMent .......................264

full-text search ...................................270Query DynaMent ..........................271search queries .............................287

G

groupsas source ....................................... 22

H

handbookconventions ................................... 12general ........................................... 11structure ........................................ 12syntax ............................................ 12

I

IDCPS DynaMent .............................131

Image DynaMentgeneral .........................................135images

with links ................................138inserting images ..........................135with Link DynaMent ...................... 138

Import DynaMentcontent import .............................141general .........................................140

Import DynaMent (continued)importing ..................................... 150

delete lists ............................. 154tagging ........................................ 155

Include DynaMentdisplaying differences .................. 184general ........................................ 160including content ......................... 160including content versions ........... 180including Weblet modules ........... 177integrating PSX modules .............. 160modes

diff ......................................... 184include ................................... 160include-version ...................... 180

indexesinline notation ............................... 20

inline functionsgeneral .......................................... 29integrating classes ......................... 30placeholders ................................ 561reference ..................................... 569

inline notationgeneral .......................................... 20inline functions ........................ 29, 30

integrationCPS DynaMent ............................. 131general .......................................... 38Iolet DynaMent ............................ 188Message DynaMent ..................... 235Portal DynaMent .......................... 252RDB DynaMent ............................. 289Reporting DynaMent .................... 313Repository DynaMent ................... 341Script DynaMent .......................... 402WebService DynaMent ................. 531

integrationsLivelink DynaMent ....................... 205Portlet DynaMent ......................... 259Tagging DynaMent ....................... 407

Ioletcalling .......................................... 188Iolet DynaMent ............................ 188

Iolet DynaMentgeneral ........................................ 188querying an Iolet .......................... 188

578

Index

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

L

Link DynaMentgeneral .........................................195in Image DynaMent ...................... 138using

with parameters ...................... 198without parameters ................195

Link-Param DynaMentgeneral .........................................202using ............................................202

live reportsrequesting ....................................316

Livelink DynaMentgeneral .........................................205modes

create .....................................215delete .....................................222navigate .................................224read ........................................207xmlsearch ...............................227

log entriesinline notation ............................... 20

logginginline notation ............................... 20

M

manualsymbols ......................................... 13

Message DynaMentgeneral .........................................235sending e-mail .............................235

metadata ...........................................150importing .....................................150

MetaData DynaMentdelivering content data ................243general .........................................243listing versions .............................250modes

list-versions ............................250

MIME typesduring import ...............................531for import .....................................310

N

navigation informationfrom Livelink ................................224

O

objectscreating in Livelink ....................... 215deleting from Livelink .................. 222reading from Livelink ................... 207

P

page layoutgeneral .......................................... 38Image DynaMent .......................... 135Link DynaMent ............................. 195Link-Param DynaMent .................. 202Wrapper DynaMent ...................... 543

parametersattributes ....................................... 20CMS placeholders .......................... 20fixed values ................................... 20general .......................................... 31inline notation ............................... 20source ........................................... 22XSL .............................................. 567

passwordsforcing change ............................. 477

personalizationAttribute DynaMent ........................ 40general .......................................... 38Query DynaMent .......................... 270Target DynaMent .......................... 461User DynaMent ............................ 474

placeholdersattributes ....................................... 75general ........................................ 561PSX module ................................. 160syntax .......................................... 564Weblet modules ........................... 177

Portal DynaMentgeneral ........................................ 252modes

include ................................... 252remove ................................... 257session .................................. 255

portalinstanceas source ....................................... 22

Portlet DynaMentgeneral ........................................ 259modes

include ................................... 259maximize ............................... 261remove ................................... 262

579

Index

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

Process DynaMentbreak ...........................................267continue ......................................269forward ........................................264general .........................................264redirect ........................................265

processing ........................................... 17

process-modestandard parameter ....................... 31

PSX modulesInclude DynaMent ........................160placeholders ........................ 561, 564

Q

Query DynaMentgeneral .........................................270listing Verity indexes ....................286modes

list ..........................................286search queries

creating ..................................271entering ..................................287

searchable parameter ..................284

R

RDB DynaMentdatabase

querying ......................... 289, 295updating .................................293

general .........................................289modes

query ......................................289statements .............................295update ....................................293

rdeAbsolutePrefix ..............................548

rde-attributes ....................................558

rdeClientCookies ...............................553

rdeContentFixedRendering .................548

rdeContentProjectId ...........................548

rdeContextPath ..................................548

rdeContextRoot ..................................548

rdeCurrentLocale ....................... 548, 553

rdeCurrentProjectId ...........................548

rdeCurrentXmlId ................................548

rdeCurrentXslId ..................................548

rdeDefaultProjectId ........................... 553

rde-dmimport .................................. 150, 154

rdeErrorInfoCurrent ............................ 553

rdeErrorInfoFirst ................................ 553

rdeErrorInfoHome .............................. 553

rdeErrorInfoLast ................................. 553

rdeErrorInfoPrefix .............................. 553

rdeErrorInfoProject ............................ 553

rdeErrorInfoSid .................................. 553

rdeErrorInfoXml ................................. 553

rdeErrorInfoXsl .................................. 553

rde-fields .................................. 555, 558

RDE-FUNCTION .................................. 564

rde-groupattributes ........................... 557

rde-groups ................................ 557, 558

rdeHttpServer .................................... 548

rdeHttpsServer .................................. 548

rde-idstandard parameter ....................... 31

rdeInternalCaller ............................... 548

rdeLocale .......................................... 548

rdeLocaleAttr ..................................... 548

rdePageKey ....................................... 548

rdePathparam ................................... 548

rdePrefix ........................................... 548

rdeProjectID ...................................... 548

RDE-PSX ............................................ 564

rde-rdcontent-type ................................ 548dynament-result .......................... 548httpHeader- ................................. 548httpHeader-method ..................... 548idea.masterservlet.currenturl ....... 553idea.masterservlet.homeurl ......... 553idea.masterservlet.lasturl ............ 553idea.masterservlet.repeaturl ........ 553path-info ...................................... 548query-string ................................. 548remote-address ........................... 553

580

Index

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

rde-rd (continued)sid ...............................................553

RDE-REGISTRY ....................................564

rdeRepository.rdeContentInfo ............555

rdeRepository.rdeMetainfo ................555

RDE-REQUEST ....................................564

rdeRequestRelId ................................548

rdeResponseCdataMode ................... 548

rdeResponseCharset ......................... 548

rdeResponseMimetype ...................... 548

rdeResponseStatus ...........................548

rde-roles ............................................558

rdeServerAlias ...................................553

rdeServletMapping ............................548

rdeServletPath ...................................548

rdeServletServer ................................548

RDE-SESSION .....................................564

rdeSessionID .....................................548

rdeSessionLocale ..............................548

RDE-SYSTEM ......................................564

rdeTimeout ........................................553

RDE-URL ............................................564

rdeUrlParamSessionID .......................548

rdeUrlPathSessionID ..........................548

RDE-USER ..........................................564

rdeWeblet ..........................................548

rdeXmlID ...........................................548

rdeXslID .............................................548

rdeXslXmlSeparator ...........................548

RedDot DynaMentEdit RedDot ..................................298modes

edit .........................................298template .................................299

Template RedDot ..........................299

redirectProcess DynaMent .......................265

redundant database structures ..........461

Reference DynaMentgeneral ........................................ 301modes

read-multipart ........................ 310set-cache-id ........................... 308

set-scope ..................................... 306using ........................................... 301

reference listsimporting ............................. 150, 154

registryas source ....................................... 22

reportingcontent data ................................ 243standard reports .......................... 328user data ..................................... 514user properties ............................ 482

Reporting DynaMentdiagrams ..................................... 334general ........................................ 313modes

acknowledge .......................... 314browser .................................. 313report ..................................... 316

report-tagstandard parameter ....................... 31

Repository DynaMentgeneral ........................................ 341modes

cancel-checkout ..................... 389checkin .................................. 382checkout ................................ 387create ..................................... 357create-folder ........................... 363delete ..................................... 378delete-folder .......................... 380list .......................................... 395list-classes ............................. 391list-classes-folder ................... 393query ...................................... 348read ....................................... 342update ................................... 368update-folder ......................... 374

requestsas source ....................................... 22predefined attributes ................... 548

responseas source ....................................... 22

result-attributestandard parameter ....................... 31

581

Index

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

resultsusing .............................................. 19

return codes ........................................ 36error handling ................................ 36

rolesstandard parameter ....................... 31

rulesAttribute DynaMent

read .......................................... 40write ......................................... 49

S

Script DynaMentexecuting scripts ..........................402general .........................................402

scriptsScript DynaMent ...........................402

searchlimiting search area ...................... 284limiting to content groups ............287limiting to content types ...............287Query DynaMent ..........................270search queries

creating ..................................271entering ..................................287

searchable parameter ..................284with Query DynaMent ................... 271with Repository DynaMent ............348

search engine indexeslisting ...........................................286

sessionpredefined attributes ................... 553

sessionsas source ....................................... 22

SMTP connectionMessage DynaMent ...................... 235

sourceattributes ....................................... 22content

attributes ................................555inline notation ............................... 20meaning ......................................... 22requests

attributes ................................548session

attributes ................................553system

attributes ................................560

source (continued)users

attributes ....................... 557, 558

standard parameters ........................... 31

structureDynaMents .................................... 16

symbols .............................................. 13

systemas source ....................................... 22predefined attributes ................... 560

T

tagginggeneral ........................................ 408imports ........................................ 155

Tagging DynaMentgeneral ................................ 407, 408modes

assignTags ............................. 420ConsolidateData ..................... 447defineTags ............................. 409deleteConsolidatedData ......... 459deleteTags ............................. 415getAssignedTags .................... 436getAssignments ...................... 429getConsolidatedData .............. 453getTags .................................. 412getTargets .............................. 440renameTag ............................. 419suggestTags ........................... 427unassignTags ......................... 424

Target DynaMentconstraints

linking .................................... 461general ........................................ 461redundant database structures .... 461using ........................................... 461

tasksDynaMents .................................... 38

Template EditorDynaMents .................................... 17

U

user behaviorUser DynaMent ............................ 474

User DynaMentdata

selected users ........................ 514

582

Index

Red

Dot

Liv

eSer

ver

9.0

Dyn

aMen

ts11

/200

8

User DynaMent (continued)general .........................................474modes

create .....................................499delete .....................................498exist .......................................496groups ....................................509load ........................................502login .......................................487login-trusted ...........................492logout .....................................493report .....................................514session ...................................482session-check ......................... 485update ....................................506

propertiescurrent user ............................482

using ............................................475

usersas source ....................................... 22data

checking .................................496creating ..................................499deleting ..................................498editing ....................................506reading ...................................514

determining logon information .....485loading ........................................502

modifying groups ....................509logging off (User DynaMent) .........493logging on (User DynaMent) . 487, 492predefined attributes ................... 557preset attributes ..........................558properties

reading ...................................482

V

validation ..........................................120

validation rulesAttribute DynaMent

read .......................................... 40write ......................................... 49

Verity indexeslisting ...........................................286

Verity search engineentering search queries ................287Query DynaMent ..........................271

versionsincluding ......................................180

votinggeneral ........................................ 408imports ........................................ 155

W

Web serviceWebService DynaMent ................. 531

WebComponent DynaMentgeneral ........................................ 523modes

include ................................... 523include-css ............................. 528remove ................................... 527session .................................. 526

Weblet modulesincluding ..................................... 177placeholders ........................ 561, 564

WebService DynaMentcalling a Web service ................... 531general ........................................ 531

Wrapper DynaMentexample ....................................... 544general ........................................ 543using ........................................... 543

X

XML contentReference DynaMent .................... 301Wrapper DynaMent ...................... 543

XPathas source ....................................... 22Content DynaMent ....................... 110expressions ................................... 26inline notation ............................... 20parameter rde-id ............................ 31using ....................................... 19, 26

XSLRedDot DynaMent

general ................................... 298

XSL parameterspredefined ................................... 567

XSL style sheetsImage DynaMent .......................... 135Link DynaMent ............................. 195Link-Param DynaMent .................. 202RedDot DynaMent ........................ 298

583

Documents

Open Text Web Solutions Delivery Server 9.0 Dynaments English (A4)