Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Australia
General Information: RedDot Solutions Australia Pty Ltd Level 12, 65 Berry Street North Sydney NSW 2060 Australia Tel: Fax: E-Mail: Web: +61 2 9925 1100 +61 2 9475 1487 info@reddotsolutions.com.au www.reddotsolutions.com.au Customer Care: Tel.: +61 2 9925 1150 E-Mail: support@reddotsolutions.com.au Extranet: www.reddotcommunity.com Education: Tel.: +61 2 9925 1100 E-Mail: education@reddotsolutions.com.au Web: www.reddotsolutions.com.au/ customer_services_education.htm
North America
General Information: Open Text Inc. RedDot Web Solutions Group One Battery Park Plaza 25th Floor New York, NY 10004 USA Tel: Tel: Fax: E-Mail: Web: 1-866-REDDOTS 1-212-425-3988 1-212-425-3987 info@reddot.com www.reddot.com Customer Care: Tel: 1-866-REDDOTS Tel: 1-212-425-3988 E-Mail: customercare@reddot.com Extranet: www.reddotcommunity.com Education: Tel: 1-866-REDDOTS Tel: 1-212-425-3988 E-Mail: education@reddot.com Web: www.reddot.com/training.htm
United Kingdom
General Information: RedDot Solutions Limited Mulberry Business Park Hummingbird Building Fishponds Road WOKINGHAM Berkshire RG41 2GY United Kingdom Tel: Fax: E-Mail: Web: +44 (0)118 9360680 +44 (0)118 9360688 info@reddot.co.uk www.reddot.co.uk Customer Care: Tel: +44 (0)118 9360690 E-Mail: support@reddot.co.uk Extranet: www.reddotcommunity.co.uk/
Copyright
2008 RedDot Solutions. All rights reserved. RedDot Documentation 11/2008 - RedDotLiveServer 9.0 If you have any comments or suggestions about this documentation, please send an e-mail to documentation@reddot.de. 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.
11/2008
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
DynaMents
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
Contents
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
DynaMents
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
Contents
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
DynaMents
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
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
DynaMents
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
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
DynaMents
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
Contents
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
DynaMents
10
11/2008
DynaMents
For more information on the actual use of DynaMents in projects, see the RedDot LiveServer Quick Start documentation.
11
Conventions
11/2008
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
DynaMents
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: <childelement>.
12
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 tips on how to make better use of certain functions.
13
11/2008
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?
DynaMents
14
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.
DynaMents
15
DynaMent Structure
11/2008
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.
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
Processing DynaMents
11/2008
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.
RedDot LiveServer 9.0
DynaMents
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
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.
11/2008
Processing Steps Using the Include DynaMent as an Example Original entry in a RedDot CMS template:
<rde-dm:include tag="login" content="<%target%>" />
Result in RedDot LiveServer after processing the content and executing the DynaMent:
<login> content of the file "login.html" </login>
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>/WEBINF/additions/xml/templateeditor/.
18
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)
DynaMents
19
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.
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.
RedDot LiveServer 9.0
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
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.
11/2008
DynaMents
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
11/2008
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).
DynaMents
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".
XPath
11/2008
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).
DynaMents
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 sessionuntil 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.
RedDot LiveServer 9.0
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
11/2008
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".
DynaMents
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.
RedDot LiveServer 9.0
24
11/2008
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
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.
DynaMents
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
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}#{defaultvalue}#]
Explanation: node-id Identifies the DynaMent, on whose results the XPath expression should apply. This nodeid 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
RedDot LiveServer 9.0 DynaMents
26
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.
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
11/2008
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>
DynaMents
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#???#]" valueseparator=";"/> <rde-dm:attribute mode="for-each" attribute="test" source="request" > ... </rde-dm:attribute> RedDot LiveServer 9.0
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
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().
DynaMents
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)
RedDot LiveServer 9.0
29
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.
DynaMents
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
Standard Parameters
11/2008
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:
DynaMents
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
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: processmode="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.
11/2008
DynaMents
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
Error Handling
11/2008
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.
DynaMents
33
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>
DynaMents
11/2008
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 <rderd: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
11/2008
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 componentseven when the DynaMents are ordered sequentially in the content.
DynaMents
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
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: DynaMent Attribute DynaMent Target DynaMent Query DynaMent User DynaMent Thousands place 3 4 5 6 7 8 9 10 11 12 13 DynaMent Message DynaMent Portal DynaMent CPS DynaMent WebService DynaMent Content DynaMent Repository DynaMent Reporting DynaMent Process DynaMent WebComponent DynaMent Livelink DynaMent Cache DynaMent Portlet DynaMent Tagging DynaMent Thousands place 19 23 24 25 26 27 28 29 30 31 32 33 35
DynaMents
Include DynaMent MetaData DynaMent RDB DynaMent Iolet DynaMent Script DynaMent Link DynaMent Image DynaMent
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.
RedDot LiveServer 9.0
5 = Error, probably caused by errors in RedDot LiveServer. 9 = Very critical error, probably caused by a system error.
36
11/2008
Within these groupings, specific meanings are defined for each DynaMent. In general they follow the divisions outlined below: Code 1 2 10 20 100 110 11x 402 403 404 501 Description Processing finished with confirmation Processing finished with confirmation; message available Processing stopped; user has none of the requested roles Processing complete with one security rule breach. Processing finished successfully; result negative Processing finished successfully; result positive Processing finished successfully, results have value x Value of the attribute parameter is not an XML name. Use the tag parameter Value of the tag parameter is not an XML name Value of the item-tag parameter is not an XML name Object not found Object not foundno results No session required for processing No user for processing General error General errorno results Defined conditions were not fulfilled Processing was not successful, result negative Processing unsuccessfully completed, results have value xx Missing parameter Missing parameter - no result Wrong parameter Wrong parameter - No result Incorrect parameter 'mode' Incorrect parameter 'mode' - no result Incorrect parameter 'project' - no result The object is locked
DynaMents
502 503 510 -1 -2 -30 -100 -1xx -301 -302 -311 -312 -313 -314 -320 -513
37
11/2008
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 customercreated 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.
DynaMents
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
11/2008
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.
DynaMents
39
Attribute DynaMent
11/2008
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")
DynaMents
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)
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
Syntax
11/2008 <rde-dm:attribute mode attribute source ="read" ="{attributename}" ="[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]"
/> DynaMents
Simple Call
<rde-dm:attribute mode="read" attribute="address.name" />
Parameters
mode
41
11/2008
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.
DynaMents
If no value is specified:
RedDot LiveServer 9.0
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
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.
DynaMents
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 valueseparator 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
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
43
11/2008
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.
DynaMents
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
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)
11/2008
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.
DynaMents 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).
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.
45
11/2008
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.
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 "resultattribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="read": Return code
DynaMents
Description The project was not found General error when executing a rule Rule was not found Execution of the rule failed The alias specified in source="context" was not recognized. Rule completed with Info type message Rule completed with Warning type message Rule completed with Error type message
For more information about the "source" parameter, see the separate section. See also: Multiple Sources: The 'source' Parameter (Page 22) 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:
RedDot LiveServer 9.0
Inline Notation for Parameter Values (Page 20) Inline Functions for Parameter Values (Page 29) Inline Function: Integrating Your Own Classes (Page 30)
46
11/2008
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.
DynaMents
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.
RedDot LiveServer 9.0
Example:
<rde-dm:attribute mode="read" attribute="content:rank" />
47
11/2008
Attribute Paths for Portal Instance Attributes The attribute path for a portal instance attribute is constructed as follows:
<portal application>:<instance>.<scope>.<attribute name>
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
DynaMents
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" />
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" />
48
11/2008
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" />
49
Syntax
11/2008 <rde-dm:attribute mode attribute source ="write" ="{attributename}" ="[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}" >
DynaMents
50
Simple Call
11/2008 <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>
Parameters
mode
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: "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. "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. Note: Cookies cannot have multiple values.
DynaMents
Examples:
51
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:
DynaMents
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:
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.
RedDot LiveServer 9.0 "length": The number of attribute values from the value parameter is written to the attribute specified under attribute.
52
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
11/2008
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":
DynaMents
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).
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.
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 valueseparator. 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
DynaMents
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) RedDot LiveServer 9.0
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
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.
runtime (optional)
11/2008
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.
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.
RedDot LiveServer 9.0
55
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
11/2008
Repository or a directory service. This setting is equivalent to selecting the Do not store value check box in the dialogs for editing attributes. Value if nothing is specified: "false".
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": DynaMents
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
RedDot LiveServer 9.0
The Attribute DynaMent in "write" mode has an optional child element called <rdedm: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
11/2008
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 valueseparator 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 "resultattribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="write":
DynaMents
Return code -3320 -3321 -3322 -3332 -3501 -3502 -3503 3603 3605 3607
Description The project was not found The specified attribute could not be reached (for example, content not found) The specified attribute is read-only. General error when writing an attribute General error when executing a rule Rule was not found. Execution of the rule failed Rule completed with Info type message Rule completed with Warning type message Rule completed with Error type message
For more information about the "source" parameter, see the separate section. See also: Multiple Sources: The 'source' Parameter (Page 22)
RedDot LiveServer 9.0
For more information about the "cookie" parameter, see the separate section. See also: Saving User Attributes in Cookies ('flushcookies') (Page 91)
57
11/2008
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" />
Attribute Paths for Portal Instance Attributes The attribute path for a portal instance attribute is constructed as follows:
<portal application>:<instance>.<scope>.<attribute name> DynaMents
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
The value of the level attribute is replaced by the value in the result.
58
11/2008
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" itemtag="item"/> DynaMents
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= "'
RedDot LiveServer 9.0
59
The result:
<input> <item>123</item> <item>456</item> <item>' 789'</item> <item>'abc</item> <item>"def"</item> <item>g,hi"</item> </input> 11/2008 RedDot LiveServer 9.0 DynaMents
60
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 <rdedm: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>
DynaMents
61
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.
DynaMents 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.
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. "cookie": Value of a cookie. "context": Only valid in an Attribute DynaMent when in "for-each" mode. Attribute used in a for-each loop.
62
DynaMents
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
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
11/2008
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.
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
DynaMents
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).
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.
64
"no": Add to the dependency list 11/2008 "yes": Do not add to the dependency list.
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.
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
DynaMents
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.
RedDot LiveServer 9.0
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
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)
Notes
DynaMents
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 "resultattribute". In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible for mode="condition":
RedDot LiveServer 9.0
Description Project was not found. Parsing of a constraint child failed. The alias specified in source="context" was not recognized. 66
For more information about the "source" parameter, see the separate section.
11/2008
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.
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.
DynaMents
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
11/2008
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" />
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.
DynaMents
68
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]" />
DynaMents
Parameters
mode
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
11/2008
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.
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 foreach 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
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"
RedDot LiveServer 9.0 sortorder (optional, only effective when used together with sortedby) Sort order for the entries: "asc" or "ascending": ascending order "desc" or "descending": Descending
11/2008
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).
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. DynaMents
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.
RedDot LiveServer 9.0 "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.
71
11/2008
If no value is specified: The setting from entry reddot.xmaps.locale.default.[content type] of the system configuration is used.
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: 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.
DynaMents
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": Return code -3351 Description Attribute name is already in use
For more information about the "source" parameter, see the separate section. See also: Multiple Sources: The 'source' Parameter (Page 22)
RedDot LiveServer 9.0
72
11/2008
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" />
Attribute Paths for Portal Instance Attributes The attribute path for a portal instance attribute is constructed as follows:
<portal application>:<instance>.<scope>.<attribute name> DynaMents
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
<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
Result in XML:
11/2008 <companies> <company>RedDot Solutions</company> <company>Microsoft</company> <company>SAP</company> </companies>
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
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 attribute source ="reference" ="{attributename}" ="[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}"
DynaMents
Parameters
mode
75
"system": Attributes of the RedDot LiveServer runtime environment. 11/2008 "group": Attributes of the specified user group. "registry": Attributes of the RedDot LiveServer registry. "response": Attributes from the header fields of the HTTP response. "cookie": Value of a cookie.
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).
DynaMents 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.
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
76
"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
11/2008
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 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.
DynaMents 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.
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 "resultattribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents". For more information about the "source" parameter, see the separate section. See also: Multiple Sources: The 'source' Parameter (Page 22) Predefined Placeholders (Page 561) Syntax of Preassigned Placeholders (Page 564)
77
11/2008
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" />
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
Simple Call
11/2008 <rde-dm:attribute mode="rename" attribute="address.name" name="surname" />
Parameters
mode
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: "user": Attributes of the current user. "session": Attributes of the active session. "request": Attributes of the current request. DynaMents "content": Attributes of the specified content item. "system": Attributes of the RedDot LiveServer runtime environment. "response": Attributes from the header fields of the HTTP response.
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.
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.
79
name 11/2008
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 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 "resultattribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".
DynaMents
Syntax
<rde-dm:attribute mode attribute source ="copy" ="{attributename}" ="[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
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
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: "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. "cookie": Value of a cookie.
81
11/2008
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.
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. 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) DynaMents
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
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.
11/2008
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 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 "resultattribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".
DynaMents
Syntax
<rde-dm:attribute mode attribute source ="move" ="{attributename}" ="[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
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
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: "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. "response": Attributes from the header fields of the HTTP response.
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.
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
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
11/2008
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)
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
Results
11/2008
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 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 "resultattribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".
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;...}" />
Simple Call
<rde-dm:attribute mode="remove" source="user" attribute="favorites" value="a;b" />
86
Parameters
11/2008 mode
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.
source (optional) Source of the attribute that is to be addressed. The following options are available: "user": Attributes of the current user. "session": Attributes of the active session. "request": Attributes of the current request. DynaMents "content": Attributes of the specified content item. "system": Attributes of the RedDot LiveServer runtime environment. "response": Attributes from the header fields of the HTTP response.
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.
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.
87
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.
11/2008
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 "resultattribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".
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]" />
88
Parameters
11/2008 mode
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.
source (optional) Source of the attribute that is to be addressed. 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. "response": Attributes from the header fields of the HTTP response. "portalinstance": Attributes of a portal instance from the active session. Can only be used for op="remove".
DynaMents
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.
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. RedDot LiveServer 9.0 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
"delete": The attribute and all its child attributes are deleted from the LiveServer 11/2008
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 "resultattribute". For more information on the general return codes, please read the "Error Handling" section in the "RedDot DynaMents" chapter.
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
90
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.
DynaMents
Syntax
<rde-dm:attribute mode ="flushcookies" cookieduration ="{maximum age of cookies}" />
91
Parameters
11/2008 mode
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 "resultattribute". For more information on the general return codes, please read the Error Handling section in the chapter About RedDot DynaMents.
DynaMents
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.
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}" /> DynaMents
Parameters
mode
Defines from which object attributes are written to the LiveServer Repository:
"user": Active session user "attribute-proxy": Proxy for attribute access RedDot LiveServer 9.0
93
11/2008
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": Attributes of the specified content item. 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).
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.
Notes
DynaMents
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
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 "resultattribute". For more information on the general return codes, please read the "Error Handling" section in the chapter "About RedDot DynaMents".
94
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} />
Parameters
mode
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 "resultattribute". For more information on the general return codes, please read the Error Handling section in the chapter About RedDot DynaMents.
RedDot LiveServer 9.0
95
11/2008
Example of a call:
<rde-dm:attribute mode="xslparam" attribute="test"/>
The result:
<xsl:param name="test"/>
See also: Predefined XSL Parameters (Page 567) Predefined Attributes for source='request' (Page 548)
DynaMents
96
Cache DynaMent
11/2008
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").
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 cache scope timeout ="set-scope" ="object" ="{session|request|server}" ="{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
Simple Call
11/2008 <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
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)
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:
RedDot LiveServer 9.0 "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
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")
DynaMents
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: Return code -32320 Description The project was not found.
See also: Calling Web Services (Page 531) Receiving and Processing Attachments (Page 540)
RedDot LiveServer 9.0
99
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}" /> DynaMents <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>
100
Parameters
11/2008 mode
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"
DynaMents
Child Elements The Cache DynaMent has the child elements called <rde-rd:entry> and <rde-rd:newentry>. DynaMents within values of a child element are processed. Inline notation is supported.
<rde-rd:entry>
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
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
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.
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 given to the object that was put in the cache using the Open API. entry-id (only for use with type="entry-id")
11/2008
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).
<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.
DynaMents
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: Return code 32275 Description The cache entry already exists. Cache ID has not been renamed.
See also: Calling Web Services (Page 531) Receiving and Processing Attachments (Page 540)
RedDot LiveServer 9.0
102
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.
DynaMents
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> type ="[content|name|entry-id]" content ="{content}" project ="{project}" name ="{name}" entry-id ="{complete key}" /> </rde-dm:cache> RedDot LiveServer 9.0
103
Parameters
mode
Child Elements The Cache DynaMent has the child elements called <rde-rd:entry> and <rderd: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.
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.
RedDot LiveServer 9.0
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
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 given to the object that was put in the cache using the Open API. entry-id (only for use with type="entry-id")
11/2008
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).
<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.
DynaMents
Result For the entry specified, dependencies in the specified cache are entered.
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: Return code -32320 Description The project was not found.
105
11/2008
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-idattribute="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="cachedep.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="cachedep.xml"/> </rde-dm:cache>
DynaMents
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
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 type ="[content|name|entry-id]" content ="{content}" project ="{project}" name ="{name}" entry-id ="{complete key}" /> </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
107
Child Elements
11/2008
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.
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. 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 DynaMents
parameter. The cache entry and all cache entries that were declared dependent on it by mode="add-dependency" are marked as invalid. 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 given to 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).
RedDot LiveServer 9.0
108
Result
11/2008
The entry specified is marked as changed. The dependent cache entries are marked as invalid and removed from the cache.
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: Return code -32320 Description The project was not found.
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-idattribute="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="cachedep.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="cachedep.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
Content DynaMent
11/2008
You use the Content DynaMent to import content to the LiveServer Repository during runtime, or to delete content. Read more about the following actions: 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.
DynaMents
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.
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
The Content DynaMent can be used with child elements in "import" mode. The <rderd: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 <rderd:import> child element to add metadata to a content item.
11/2008
Syntax
<rde-dm:content mode content project type locale ref-type ref synchronized retries timeout importtask importdef ="import" ="{project:content name}" ="{project}" ="[html|xml|xsl|blob|script]" ="{locale string}" ="[embedded|file|named]" ="{reference name}" ="[no|yes]" ="{number of retries}" ="{timeout for synchronize}" ="{importtask name}" ="{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>
DynaMents
111
Simple Call
11/2008 <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
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)
DynaMents
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)
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/). RedDot LiveServer 9.0 "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
11/2008
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/WEBINF/. 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. DynaMents
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, ISO8859-1). Ignored if reftype="embedded". 113
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)
11/2008
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".
DynaMents 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 reftype="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.
RedDot LiveServer 9.0 <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
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 "rderd"; otherwise it would be executed already when the content is read with the Content DynaMent (see the example below).
mode (optional)
11/2008
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.
DynaMents
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
Error Handling
11/2008
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: Return code -26320 -26501 -26502 -26503 -26504 -26507 -26508 -26509 Description The project was not found. No import job found No import definition found Incorrect locale specified General error The XPath expression is missing or invalid The mode="set" and "add" are only available for xml content Synchronization failed (softlock not granted)
DynaMents
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. For more information on using XPath expressions, see the separate sections. 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.
116
11/2008
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>
DynaMents
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
11/2008
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>
DynaMents
118
11/2008
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>
DynaMents
119
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>
DynaMents
120
Simple Call
11/2008 <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
Name of the validation service connector assigned in RedDot LiveServer. Several connectors can be specified, separated by semicolons.
ref-type
The content item is determined from the following parameters: project (optional),
DynaMents 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 <rderd: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".
RedDot LiveServer 9.0 ref (optional) Required entry only for: 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
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]")
11/2008
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]")
DynaMents
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
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.
RedDot LiveServer 9.0
122
Child Elements There are two child elements in "validate" mode. Child element <rde-rd:xpathexpressions> can be used once within a Content DynaMent, but can contain several <rderd:xpath-expr> elements. The <rde-rd:content> child element can be used multiple
DynaMents
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.
RedDot LiveServer 9.0
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
11/2008
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: Return code -26320 -26510 -26511 -26512 -26513 -26514
DynaMents
Description The project was not found Invalid type specification No "rde-rd:content" element found Invalid XML Invalid source for attribute Attribute not found Invalid URL in "ref" parameter Content cannot be loaded Validation service connector not found
For more information about validation service connectors, see the Connectors documentation.
124
11/2008
content01.xml:
<root-elem> <entry> <![CDATA[ <html> <body> <p>Hello World!</p> </body> </html> ]]> </entry> </root-elem>
DynaMents
Therefore, the entry for the validation service is the HTML snippet in the CDATA section of content01.xml in the above example.
125
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 content project version /> ="delete" ="{project:content name}" ="{project}" ="[final|draft|{version}]"
Simple Call
<rde-dm:content mode="delete" content="html-demo:news.htm" />
Parameters
mode
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
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 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: Return code -26320 -26321 Description The project was not found. The specified version was not found.
DynaMents
Syntax
<rde-dm:content mode ="remove-data" content ="{project:content name}" project ="{project}" locale ="{locale string}" archive ="[true|false]" />
127
Simple Call
<rde-dm:content mode="remove-data" content="html-demo:news.htm" />
Parameters
mode
DynaMents
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.
Result
RedDot LiveServer 9.0
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
Error Handling
11/2008
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: Return code -26320 -26503 -26504 Description The project was not found. Incorrect locale specified General error
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 content project queue attachment /> ="notify-cache" ="{project:content name}" ="{project name}" ="[no|yes]" ="{attachment name}"
Simple Call
<rde-dm:content mode="notify-cache" content="html-demo:news.htm" />
129
Parameters
11/2008 mode
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. Value if nothing is specified: "no"
DynaMents 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: Return code -26320 Description The project was not found.
130
CPS DynaMent
11/2008
The CPS DynaMent provides access to various system functions in RedDot LiveServer. Read more about the following actions: Generate unique system-wide IDs (mode="id")
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
DynaMents
You can, however, use these DynaMents to cache a complex page by inserting them into special content that you include via the Include DynaMent.
Syntax
<rde-dm:cps mode name type op value project id-attribute /> RedDot LiveServer 9.0 ="id" ="{name}" ="[sequence|guid]" ="[next|get|set]" ="{value}" ="[{projectname}|cps]" = "{source:attributename}"
131
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
DynaMents mode
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
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)
11/2008
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. DynaMents "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
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:
RedDot LiveServer 9.0
133
11/2008
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>
DynaMents
134
Image DynaMent
11/2008
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. Read more about the following actions: 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.
DynaMents
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
Parameters
11/2008 method
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".
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
11/2008
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"/>
Result in HTML:
<img scr="/imenu/xbcr/SID-3F57FBCE-56ADD8BF/master/banner_magazine_jpg" alt="ad banner">
DynaMents
Image DynaMent with 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"/>
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"> RedDot LiveServer 9.0
137
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> DynaMents
Parameters
method
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
Error Handling
11/2008
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: Entry in the XML file:
<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>
139
Import DynaMent
11/2008
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:tagassignment> 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. For more information, see: Importing Content ('import') (Page 110)
DynaMents
140
Importing/Deleting Metadata
11/2008
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
DynaMents
="[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 attribute op
="[condition|write]" ={attributename} ="{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
</properties> 11/2008 <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.
DynaMents
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-valueseparator 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
142
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
11/2008
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. DynaMents "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
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)
11/2008
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) DynaMents
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.
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.
144
"false": Default setting. Changes to the attribute are saved to the LiveServer 11/2008
Value if nothing is specified: "false". 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)
nor useful.
resolve-entities (optional)
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 RedDot LiveServer 9.0
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
11/2008
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) DynaMents
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
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.
DynaMents
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
11/2008
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>
DynaMents
</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.
148
11/2008
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)
DynaMents
149
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.
DynaMents
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>
150
Parameters/Child Elements
11/2008 <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)
DynaMents
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) RedDot LiveServer 9.0
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
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
11/2008
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
DynaMents
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
RedDot LiveServer 9.0
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 <rdedm:reference> element.
152
See also:
11/2008
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.
153
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>
DynaMents
Parameters/Child Elements
<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 enUS. 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
Notes
11/2008
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:
DynaMents
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.
multiple child elements to enable complex combinations of deleting, adding, and setting tags.
155
Syntax
11/2008 <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>
DynaMents
Tag name.
<type>
156
<storage-project> 11/2008
Child element for assigning tags to the specified target objects in the specified tagging/ voting configuration.
mode
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: "community": Default type. Is also assigned when end users assign tags. "editorial": Tags created by an editor or administrator. configuration-project
Name of the tagging/voting configuration. If nothing is specified: The first tagging/voting configuration of the project.
<rde-rd:targets> (optional) RedDot LiveServer 9.0
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 <rdedm:reference> element is specified in the surrounding Import DynaMent, the content
157
11/2008
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>
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".
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> RedDot LiveServer 9.0
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
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)
DynaMents
<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
Include DynaMent
11/2008
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. Read more about the following actions: 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").
DynaMents
160
Syntax
11/2008 <rde-dm:include mode content depth validfrom validto locale locale-policy onerrorscript prerequestscript postrequestscript script-requestparams contenttype method buffer-stream appserver timeout track-mode ="[include|text]" ="{content}" ="[0|1|...n]" ="{yyyy.mm.dd hh:mm:ss}" ="{yyyy.mm.dd hh:mm:ss}" ="{locale string}" ="[none|default|any]" ="{projectname:contentname}" ="{projectname:contentname}" ="{projectname:contentname}" ="[none|readonly|readwrite]" ="[text/xml|...]" ="[GET|POST|MULITPART]" ="[discard|keep]" ="[yes|no]" ="{timeout in seconds}" ="[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>
DynaMents
161
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 DynaMents "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
11/2008
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.
DynaMents
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
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
11/2008
Insert headers [variable header with type hash table, for example, header.put(key,value)] or Change the URL (variable url) or
DynaMents
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
"readonly": The object is passed on to the script. Request parameters can be read. 11/2008 "readwrite": The object is passed on to the script. Request parameters can be read and
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.
DynaMents
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
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: MIME types
"*/xml", "*+xml" or "*/rss*" "text/xsl" "*/html" or "*/xhtml" "javascript". Content is entered using: <script language="javascript"><!-- ... --> </script>
11/2008
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.
DynaMents 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
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.
RedDot LiveServer 9.0 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.
166
buffer-stream (optional) Used only with method="MULTIPART": Specification of whether the multipart request should be temporarily saved for use after its initial call.
11/2008
"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
DynaMents
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.
RedDot LiveServer 9.0
"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
"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)
11/2008
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. DynaMents "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.
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 RedDot LiveServer 9.0
168
"context-tags": The tags selected in the context-tags parameter from the content 11/2008
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)
DynaMents
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.
169
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)
11/2008
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 includemode parameter.
DynaMents
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 contentincludeattribute 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. RedDot LiveServer 9.0 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
11/2008
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. "{tagname}": Explicit specification of 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: rderd: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) DynaMents
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. RedDot LiveServer 9.0 "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
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)
11/2008
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.
DynaMents
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
Error Handling
11/2008
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: Return code -7320 -7501 -7502 -7503 -7504 -7511 -7512 Description The project was not found. The content item was not found. The content could not be included (incorrect content type, for example). The URL to be included was not specified. The content type is not XSL. XSL content items may only contain content of type XSL. The script contains an error or could not be found. The OnError script was not found or encountered an error. A timeout occurred while retrieving external content. The maximum processing depth was reached The document is no longer valid (according to the validfrom and validto parameters). Successful, but no content. Content constraint was not met, content not included. The content item was not found in the repository. Cannot process requested content. The PreRequest script was not found or encountered an error.
DynaMents
173
11/2008
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
DynaMents
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.
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
11/2008
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.]]>
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
11/2008
Example: PSX Module with content-qualifier Parameter Include DynaMent with PSX module:
<rde-dm:include content="abc.xml" stylesheet="def.xsl" contentqualifier="[#request:pageId#]"/>
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
DynaMents
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
11/2008
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)
DynaMents
Syntax
<rde-dm:include content="{parameter1=value1? parameter2=value2...}" weblet="{weblet alias}" />
177
Simple Call
11/2008 <rde-dm:include weblet="mediator" content="baseURL=www.reddot.com/" tag="notag" />
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
DynaMents
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. "{tagname}": Explicit specification of 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.
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.
RedDot LiveServer 9.0
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
The placeholder is then replaced by the string set in the Weblet via method
11/2008 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. For more information, see: Predefined Placeholders (Page 561) Syntax of Preassigned Placeholders (Page 564)
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:{webletalias}$$parameter:??{query-string}/# ". No other replacement or rendering takes place. The Weblet called as Weblet module is responsible for error handling.
179
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}" />
DynaMents
Simple Call
<rde-dm:include mode="include-version" content="text.html" version="draft" />
Parameters
mode
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
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 enUS. 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.
11/2008
other language.
"default": If a value is not available in the language you require, the value for the
DynaMents
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"
version (optional)
Version of the content item to include. 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.
Value if nothing is specified: For delivery: "final"; for preview (RedDot LiveServer/RedDot CMS): "draft".
include-mode (optional) RedDot LiveServer 9.0
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
181
"content-identifier": Name of the content in the XML element name. 11/2008 "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)
DynaMents
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. RedDot LiveServer 9.0 "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.
182
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: Return code -7320 -7321 Description The project was not found. The specified version was not found.
DynaMents
183
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 project2 locale2 version2 /> ="{projectname:contentname}" ="{projectname}" ="{locale string}" ="[final|draft|{version}]"
DynaMents
Simple Call
<rde-dm:include mode="diff" content1="text.html" locale1="de" version1="final" content2="text.html" locale2="de" version2="draft"/>
Parameters
mode
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
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 DynaMents
Version of the content item to be used. 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. content2 See content1. project2 (optional) See project1. locale2 See locale1. version2 See version1.
185
Result
11/2008
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>
DynaMents
186
Error handling
11/2008
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: Return code -7320 -7520 -7521 -7523 -7524 -7525 -7526 Description The project was not found. The specified version of the content item, project1:content1:version1, was not found. The specified version of the content item, project2:content2:version2, was not found. The version information is missing in parameter version1. The version information is missing in parameter version2. The locale information is missing in parameter locale1. The locale information is missing in parameter locale2.
DynaMents
187
Iolet DynaMent
11/2008
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. Read more about the following actions: Call an Iolet Use child elements to transfer additional parameters to the Iolet
Calling Iolets
Purpose
DynaMents
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
Syntax
11/2008 <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>
Simple Call
<rde-dm:iolet name="userinfoiolet" method="GetUserInfo"> </rde-dm:iolet>
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. RedDot LiveServer 9.0 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
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)
11/2008
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)
DynaMents
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"
tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. "{tagname}": Explicit specification of tag name. If the result is an XML tree, the previous
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.
RedDot LiveServer 9.0 <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
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>
11/2008
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
Error Handling
11/2008
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: Return code -10501 -10511 -10599 10101 10102 10103 10104 Description The Iolet generated an error message. Return value of the Iolet is not XML. The necessary license is missing. Attribute name missing. Attribute reference: Unknown rde-id Attribute type: Unknown type (allowed types: blank, "string", "xml") Parameters cannot be overwritten.
DynaMents
Result:...
Result:...
192
11/2008
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.
In the above example, two Attribute DynaMents are run with the same value for rdeid. After processing, the result of the Attribute DynaMent with processmode="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
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 <rderd: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
DynaMents
11/2008
194
Link DynaMent
11/2008
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. Read more about the following actions: Generate simple links without parameters Generate links with additional parameters and combine the Link DynaMent with other DynaMents
DynaMents
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
Notes
11/2008
Meaning Path of the Web server Name of the called Weblet ID of the active session Name of the active project ID of the current style sheet Separator between style sheet and content Name of the current content
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:
DynaMents <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.
196
11/2008
<rde-dm:link />
197
Purpose You can use a Link DynaMent with parameters and combine it with other DynaMents to publish a link.
Syntax
<rde-dm:link project tag prefix method xsl xml wrapper /> ="{projectname}" ="{"tagname}" ="{prefix} ="{method name}" ="{xsl contentname}" ="{xml contentname}" ="{wrapper}"
DynaMents
Parameters
project
198
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: Return code -12320 Description The project was not found
DynaMents
Only one link is generated for each Link DynaMent. Therefore, if you need multiple links, insert the required number of Link DynaMents.
199
11/2008
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>
DynaMents
200
11/2008
DynaMents
201
Link-Param DynaMent
11/2008
The Link-Param DynaMent is used to pass parameters with a link call. The Link-ParamDynaMent can only be used together with a Link-DynaMent. Read more about the following actions: Use the Link-Param DynaMent to pass additional parameters for a link.
Syntax
<rde-dm:link-param name ="{name}" value ="{value}" />
Parameters
name
Parameter that can also be addressed dynamically (example: "{$ioeXmlID}" for the page ID of the page from which the Link DynaMent is called).
202
11/2008
"Back" button:
<rde-dm:link method="html"> <br/> <rde-dm:link-param name="Back" </rde-dm:link>
value="{$rdeXmlID}"/>Back
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 ...
DynaMents
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
11/2008
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:
DynaMents
Generating Simple Links (Page 195) Generating Links with Parameters (Page 198)
204
Livelink DynaMent
11/2008
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 more about the following actions: Read specific objects from Open Text Livelink (mode="read") Create specific objects in Open Text Livelink (mode="create")
DynaMents
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
11/2008
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)
DynaMents
206
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>
DynaMents
207
Simple Call
11/2008 <rde-dm:livelink mode connector item include-mode child-depth /> ="read" ="Livelink" ="[#request:item#]" ="[#request:include-mode#]" ="[#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
Name of the repository connector to be used, as defined in RedDot LiveServer. The connector has to use a bridge for Open Text Livelink.
DynaMents 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
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
RedDot LiveServer 9.0
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
11/2008
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
DynaMents
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) RedDot LiveServer 9.0
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
".*": Returns all standard properties. 11/2008 "{category}.*": Returns all properties for the specified category. "{property}": Returns the values for the standard properties specified. You can specify
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)
DynaMents
Method used to add content items to the elements of the XML result.
"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. "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. Value if nothing is specified: "mixed"
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: yyyyMM-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-MMdd'T'HH:mm).
item-tag (optional)
This is the tag name of the XML element that displays the result of read object.
RedDot LiveServer 9.0 "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
210
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"
11/2008
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 DynaMents
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
query date.
three-months-ago: To be added, objects must have been created within three
query date.
Date value (following the pattern in the dateformat-in parameter): Objects must have been created on the specified date/time or later. RedDot LiveServer 9.0 <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
topics-only: Only dependent objects with type topic are added. 11/2008 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>
DynaMents
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
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>
11/2008
DynaMents
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. Return code -31100 -31101
RedDot LiveServer 9.0
Description Incorrect argument for a parameter The active user does not have the rights to perform this action on the content item selected The project was not found Unknown error when using the bridge Unable to load bridge support
213
11/2008
Return code -31511 -31512 -31513 -31514 -31515 -31516 -31521 -31522 -31523 -31530 -31561 -31580 -31581
Description Unable to find connector specified Unable to access bridge Unable to obtain list of available repositories Unable to access repository Unable to examine repository Bridge support cannot be loaded due to missing license The user cannot log on The user cannot log off No cleanup possible after the access General error General error while accessing the repository item Error while compiling a display element Error while compiling a display element (content-info) Error while compiling a display element (reference) Error while compiling a display element (metainfo) Error while compiling a display element (content) Error while compiling a display element (identifier) Error while creating the object to be cached Error handling collaboration actions Incorrect argument for a parameter Unable to determine size of (native) content Problem determining the links The maximum processing depth was reached
DynaMents
-31582 -31583 -31584 -31585 -31586 -31591 31103 31104 31119 31201
214
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 connector folder item-name item-type contentclass-name dateformat-in ref-type ref abort-events ="create" ="{connector name}" ="{object id}" ="{object name}" ="{object type name}" ="{contentclass name}" ="{dateformat}" ="[embedded|file|named]" ="{reference}" ="[error|warn|none|{warning-codes}| {error-codes}]"
DynaMents
> <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
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> DynaMents
Parameters
mode
Name of the repository connector to be used, as defined in RedDot LiveServer. The connector has to use a bridge for Open Text Livelink.
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:
RedDot LiveServer 9.0 "discussion": Livelink discussion "topic": Livelink topic "reply": Livelink reply
216
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: yyyyMM-dd'T'HH:mm). ref-type (optional)
11/2008
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. DynaMents
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. Value if nothing is specified: "embedded"
ref (optional) Required entry only for: 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/WEBINF/. 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.
RedDot LiveServer 9.0
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
"warn": The operation is aborted if any warning is issued. 11/2008 "none": The operation is not aborted even if there are errors or warnings. "{code}": Explicitly stated return codes for errors and warnings.
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.
DynaMents <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>
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.
RedDot LiveServer 9.0 <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
11/2008
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
DynaMents
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.
219
Result
11/2008
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>
DynaMents
If any errors occur, the return code is recorded as the error attribute of the rderd: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. Return code -31100 -31101 -31320 -31501 -31510
RedDot LiveServer 9.0
Description Incorrect argument for a parameter The active user does not have the rights to perform this action on the content item selected. The project was not found. Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to obtain list of available repositories Unable to access repository Unable to examine repository 220
11/2008
Return code -31516 -31521 -31522 -31523 -31530 -31531 -31532 -31533 -31561 -31580 -31581 -31582 -31583
Description Bridge support cannot be loaded due to missing license The user cannot log on The user cannot log off No cleanup possible after the access General error General error while creating content "Native" content must be provided General error while setting the properties of a repository item General error while accessing the repository item Error while compiling a display element Error while compiling a display element (content-info) Error while compiling a display element (reference) Error while compiling a display element (metainfo) Error while compiling a display element (content) Error while compiling a display element (identifier) Error while creating the object to be cached Error using RawContent Incorrect argument for a parameter Unable to determine size of (native) content The property specified in the import tag cannot be set, as it has not been defined The property specified in the import tag cannot be set, as it is read only The property specified in the import tag can possibly not be set (unable to determine type) The property specified in the import tag cannot be set because restrictions defined for the property are not fulfilled The specified content class was not found or could not be linked with the content/folder Problems occurred while creating an attachment The maximum processing depth was reached
DynaMents
-31584 -31585 -31586 -31587 31103 31104 31108 31109 31110 31116 31117 31118 31201
221
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}" />
DynaMents
Parameters
mode
Name of the repository connector to be used, as defined in RedDot LiveServer. The connector has to use a bridge for Open Text Livelink.
222
item 11/2008
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: "discussion": Livelink discussion "topic": Livelink topic "reply": Livelink reply
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.
DynaMents
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. Return code -31100 -31101 -31320 -31501 -31510 -31511 -31512 Description Incorrect argument for a parameter The active user does not have the rights to perform this action on the content item selected The project was not found Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to obtain list of available repositories Unable to access repository Unable to examine repository Bridge support cannot be loaded due to missing license The user cannot log on 223
11/2008
Return code -31522 -31523 -31530 -31551 -31561 -31586 31103 31104 31201
Description The user cannot log off No cleanup possible after the access General error General error while deleting a repository item General error while accessing the repository item Error while creating the object to be cached Incorrect argument for a parameter Unable to determine size of (native) content The maximum processing depth was reached
Syntax
<rde-dm:livelink mode connector item include-mode /> ="navigate" ="{connector name}" ="{object id}" ="{include-modes}"
Parameters
mode
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 of the object to read. Livelink nicknames are supported. 224
include-mode 11/2008
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"
DynaMents
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 timeintensive 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
Error Handling
11/2008
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. Return code -31100 -31101 -31320 -31501 -31510 -31511 -31512 Description Incorrect argument for a parameter The active user does not have the rights to perform this action on the content item selected The project was not found Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to obtain list of available repositories Unable to access repository Unable to examine repository Bridge support cannot be loaded due to missing license The user cannot log on The user cannot log off No cleanup possible after the access General error General error while accessing the repository item Error while compiling a display element Error while compiling a display element (content-info) Error while compiling a display element (reference) Error while compiling a display element (metainfo) Error while compiling a display element (content) Error while compiling a display element (identifier) Error while creating the object to be cached Incorrect argument for a parameter Unable to determine size of (native) content Problem determining the links The maximum processing depth was reached
DynaMents
-31513 -31514 -31515 -31516 -31521 -31522 -31523 -31530 -31561 -31580 -31581 -31582 -31583 -31584 -31585 -31586 31103
226
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>
DynaMents
Parameters
mode
search-template 11/2008
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.
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-MMdd'T'HH:mm).
context-mode (optional) DynaMents
Method used to add content items to the elements of the XML result.
"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. "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. Value if nothing is specified: "mixed"
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. RedDot LiveServer 9.0 "content-listdisplay": Some basic information about the content in each XML
228
rde-rd:mime: MIME type of the content item in the external repository 11/2008 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, contentbytesize, type, rde-rd:mime. DynaMents "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.
"metainfo": The metadata selected in the metainfo parameter, which is maintained as properties in the repository. "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" 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"
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.
".*": Returns all standard properties. "{category}.*": Returns all properties for the specified category.
229
"{property}": Returns the values for the standard properties specified. You can specify 11/2008
categories. You can specify one or several property names separated by semicolons. To be able to include metadata, you need to specify the mode "metainfo" in the includemode parameter.
is not required.
"{property}": Returns the values for the properties specified. You can specify one or
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
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
11/2008
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. If nothing is specified: 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)
DynaMents
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.
sortorder (optional, only effective when used together with sortedby) Sort order for the entries: "asc" or "ascending": Ascending "desc" or "descending": Descending
If nothing is specified: Values from the display template or the search object (template, query).
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. "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.
231
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. DynaMents name
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: Return code -31100
RedDot LiveServer 9.0
Description Incorrect argument for a parameter The active user does not have the rights to perform this action on the content item selected The project was not found Unknown error when using the bridge Unable to load bridge support 232
11/2008
Return code -31511 -31512 -31513 -31514 -31515 -31516 -31521 -31522 -31523 -31530 -31561 -31580 -31581
Description Unable to find connector specified Unable to access bridge Unable to obtain list of available repositories Unable to access repository Unable to examine repository Bridge support cannot be loaded due to missing license The user cannot log on The user cannot log off No cleanup possible after the access General error General error while accessing the repository item Error while compiling a display element Error while compiling a display element (content-info) Error while compiling a display element (reference) Error while compiling a display element (metainfo) Error while compiling a display element (content) Error while compiling a display element (identifier) Error while creating the object to be cached Error handling collaboration actions Incorrect argument for a parameter Unable to determine size of (native) content Problem determining the links The maximum processing depth was reached
DynaMents
-31582 -31583 -31584 -31585 -31586 -31591 31103 31104 31119 31201
For more information about prepared searches and how they are defined in the repository connector, see the Connectors documentation.
233
11/2008
DynaMents
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
Message DynaMent
11/2008
The Message DynaMent makes it possible to send messages. Read more about the following actions: Send e-mail messages via an SMTP server
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
DynaMents
You can, however, use these DynaMents to cache a complex page by inserting them into special content that you include via the Include 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>, <rderd: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
Syntax
11/2008 <rde-dm:message mode name send-type appserver ="smtp" ="{connector name}" ="[queue|direct]" ="[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>
DynaMents
The default parameter cachingtime cannot be used. This DynaMent sets the value of the caching time for the respective content to "0."
RedDot LiveServer 9.0
Parameters
mode
11/2008
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".
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
Value if nothing is specified: The value entered in the system configuration for the reddot.idea.appserver.callurls key (default value is "yes").
DynaMents
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>
One or more e-mail addresses for one or more recipients. Separate multiple addresses with commas.
type (optional) RedDot LiveServer 9.0
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
11/2008
text.
"text/html": The text is interpreted as an HTML page. Select this type if
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
DynaMents
sent as an attachment. The content is a temporary file that was, for example, received via a Web service. Value if nothing is specified: "embedded"
mime-type (optional) The specification of a MIME type that is used by the recipient to process the file that was received.
Value if nothing is specified: 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. RedDot LiveServer 9.0 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
11/2008
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).
DynaMents
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
Error Handling
11/2008
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: Return code -19321 -19322 -19501 -19502 -19901 19323 19324 Description The message could not be generated (required data missing?) The message transfer service could not be found or generated for the specified mode (internal error) The specified message service connector could not be found Not all of the parameters required for the call have been specified The message transfer master could not be found (fatal internal error) This encoding is not supported Preparation of attachment failed Error reading content:'<contentId>' project:'<projectId>' locale:'<locale>'
DynaMents
19325
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 wellformed XML element value.
For more information about the Include DynaMent, see the separate section. See also:
RedDot LiveServer 9.0
240
11/2008
Format of E-mail Addresses in the Message DynaMent You can enter the e-mail addresses for sender and recipient in the following formats: name@company.com or "Name"<name@company.com> The second format must be enclosed in CDATA sections and then looks like this: <![CDATA["Name"<name@company.com>]]> (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 <rderd: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.
DynaMents
241
11/2008
<document> <rde-dm:message name="smtp-connector" mode="smtp" send-type="direct"> <rde-rd:email> <rde-rd:from> <![CDATA["Company"<info@our-company.com>]]> </rde-rd:from> <rde-rd:reply-to> admin@our-company.com </rde-rd:reply-to> <rde-rd:recipients> <rde-rd:recipient type="to"> [#request:mail_to#0#] </rde-rd:recipient> <rde-rd:recipient type="cc"> someone@somewhere.org </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>
DynaMents
Schematic result: Subject = Information for you! Body = Hi, Marc <p>Here is our monthly newsletter for you:</p> <hr> [newsletter-content]
242
MetaData DynaMent
11/2008
You can use the MetaData DynaMent to read metadata of content items. It provides information about content items in a LiveServer Repository. Read more about the following actions: 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").
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
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)
DynaMents
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.
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
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":
11/2008
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) DynaMents
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.
"{tagname}": Explicit specification of tag name. "notag": Content in the result is not enclosed in XML elements.
245
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"
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)
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.
DynaMents
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: Return code -8320 Description The project was not found.
246
11/2008
The result:
<rde-idea:content resulttype="xml" locale="en" project="trails" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsltemplate="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:rderd="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"></rdeidea:creator> <rde-idea:lasteditor rde-idea:datetime="26.06.02 17:29"></rdeidea: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> >
DynaMents
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
11/2008
The result:
<rde-idea:content-item guid="standardcontent-ffffffffc0a80290ed05de4644-ed05da627e"> <rde-idea:name>5010A13CE57445239C70C7BED230312C.xml</rdeidea: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"></rdeidea:creator> <rde-idea:lasteditor rde-idea:datetime="30.05.02 16:05"></rdeidea:lasteditor> <Type>Type 1</Type> </rde-idea:content-item> DynaMents
Alongside the general content data, the content attributes below the attribute path "Type" are also output.
248
11/2008
The result:
<rde-idea:content-item guid="standardcontent-ffffffffc0a80290ed05de4644-ed05da627e"> <rde-idea:name>5010A13CE57445239C70C7BED230312C.xml</rdeidea: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"></rdeidea:creator> <rde-idea:lasteditor rde-idea:datetime="30.05.02 16:05"></rdeidea:lasteditor> <Type>Type 1</Type> <rank>1</rank> </rde-idea:content-item>
DynaMents
Alongside the general content data for the "admin" user, the two content attributes "Type" and "rank" are output.
249
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}" />
DynaMents
Simple Call
<rde-dm:metadata mode="list-versions" content="index.html" project="htmldemo" />
Parameters
mode
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) RedDot LiveServer 9.0
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
11/2008
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>
DynaMents
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 -8505 -8320 Meaning The content was not found The project was not found
251
Portal DynaMent
11/2008
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. Read more about the following actions: 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.
DynaMents
Syntax
<rde-dm:portal mode application instance initial-url ="include" ="{portal application}" ="{application instance}" ="[rdeBase|rdeLogin|rdeLogout| rdeRelogin|{explicit URL}]" url ="{explicit URL}" include-mode ="[html|xml|cdata|mixed]"
/>
252
Simple Call
11/2008 <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
DynaMents
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
"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"
11/2008
The response content is inserted within a CDATA element. Value if nothing is specified: "html"
tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
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"
DynaMents
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: Return code -23321 -23331 -23341 -23599
RedDot LiveServer 9.0
Description Application portal connector not found Application portal connector not active Unable to connect to portal application The necessary license is missing
254
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
Tag name of the XML element that surrounds each selected content item in the result.
"{tagname}": Explicit specification of tag name. "notag": Content in the result is not enclosed in XML elements.
255
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"
11/2008
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>
DynaMents
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: Return code -23321 -23331 -23341 -23599 Description Application portal connector not found Application portal connector not active Unable to connect to portal application The necessary license is missing
256
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 application instance /> ="remove" ="{portal application}" ="{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
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
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"
11/2008
Result If available, an instance of a portal application will be removed from the current session.
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: Return code -23321
DynaMents
Description Application portal connector not found Application portal connector not active Unable to connect to portal application connector Cannot find object The necessary license is missing
258
Portlet DynaMent
11/2008
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. Read more about the following actions: 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.
DynaMents
Syntax
<rde-dm:portlet mode connector portletContext portlet instance ="include" ="{portlet ="{portlet ="{portlet ="{portlet
<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
Simple Call
11/2008 <rde-dm:portlet mode="include" connector="PortletConnector" portletContext="/ demoPortlet" portlet="DemoPortlet"/>
Parameters
mode
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: Return code 33001 Description The maximum processing depth was reached 260
11/2008
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
DynaMents
Syntax
<rde-dm:portlet mode ="maximize" />
Simple Call
<rde-dm:portlet mode="maximize" />
261
11/2008
Parameter
mode
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: Return code 33001
DynaMents
Syntax
<rde-dm:portlet mode connector portletContext portlet instance /> ="remove" ="{portlet ="{portlet ="{portlet ="{portlet
262
Simple Call
11/2008 <rde-dm:portlet mode="remove" connector="PortletConnector" portletContext="/ demoPortlet" portlet="DemoPortlet"/>
All instances of the specified portlet are deleted from the session.
Parameters
mode
Result The specified instance (or all instances) of a portlet is removed from the current session.
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: Return code 33001 Description The maximum processing depth was reached
263
Process DynaMent
11/2008
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)".
DynaMents
Syntax
<rde-dm:process mode ="forward" control-id ="{rde-id}" > <Child-Elemente/> />
Simple Call
<rde-dm:process mode="forward" control-id ="{rde-id}" > <rde-dm:include content="text.html"/> </rde-dm:process>
Parameters
RedDot LiveServer 9.0 mode
264
11/2008
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.
DynaMents
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.
Syntax
RedDot LiveServer 9.0 <rde-dm:process mode url type status ="redirect" ="{redirect url}" ="[http|html]" ="{http response status}" >
<Child-Elemente/> />
265
Simple Call
<rde-dm:process mode="redirect" url="/cps/rde/xchg/demo" > <rde-dm:include content="text.html"/> </rde-dm:process>
Parameters
mode
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:
DynaMents "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.
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
Error Handling
11/2008
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.
Syntax
<rde-dm:process mode ="break" control-id ="{rde-id}" />
DynaMents
Parameters
mode
If no value is specified: processing restarts following the innermost enclosing Control DynaMent.
RedDot LiveServer 9.0
Notes If no element is found after which processing should restart, the DynaMent is ignored and generates the return code shown below.
267
Results
11/2008
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 29502 Meaning Control element not found - no result
DynaMents
268
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 foreach 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" />
DynaMents
Parameters
mode
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 29502
RedDot LiveServer 9.0
See also: Making Attribute Values or Child Attributes Available ('for-each') (Page 69)
269
Query DynaMent
11/2008
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 Servereven 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. Read more about the following actions: 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.
DynaMents
270
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 locale repository external-only include-mode metainfo ="{projectname;projectname;..}" ="{locale string}" ="{alias;alias;...}" ="[no|yes|ignore]" ="[{include-mode},{tagname};]" ="[{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}" item-tag ="[{tagname}|notag]" > <rde-dm:query-cis> query </rde-dm:query-cis> <rde-dm:query-verity> query (Verity-specific) </rde-dm:query-verity> </rde-dm:query> RedDot LiveServer 9.0
DynaMents
271
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. RedDot LiveServer 9.0
DynaMents
272
Selects which information about the content that has been found 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; for BLOB type content, also the file size in the size element.
"content-identifier": Name of the content in the XML element name. "context-tags": The tags selected in the context-tags parameter from the content
itself.
"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.
DynaMents
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. 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,contextmode1;author;metainfo3,context-mode3"
To be able to include metadata, you need to specify the mode "metainfo" in the includemode 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
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 nonpersonalized content is used for the output; not only the area limited by a possible <rdedm: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)
11/2008
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. DynaMents "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. Value if nothing is specified: "mixed"
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
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"
11/2008
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.
DynaMents sortorder (optional, only effective when used together with sortedby) Sort order for the entries: "asc" or "ascending": ascending order "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 contextmode 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
Setting that determines whether content constraints are considered for the display of search results (see also the constraints parameter in the Result section).
275
11/2008
"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 includemode="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. Value if nothing is specified: "no"
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"
appserver (optional) Configuration of DynaMent processing on the Web server or application server. DynaMents "yes": Even DynaMents that access external URLs will be executed in the usual order on
Value if nothing is specified: The value entered in the system configuration for the reddot.idea.appserver.callurls key (default value is "yes").
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_dateformatout.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). RedDot LiveServer 9.0
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
"YMD": European format: Date information in the format "aa-bb-cc" will be interpreted so 11/2008
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.
"{tagname}": Explicit specification of tag name. DynaMents "notag": Content in the result is not enclosed in XML elements.
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.
RedDot LiveServer 9.0
277
Child Elements
11/2008
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 highperformance 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.
DynaMents
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
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
11/2008
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.
DynaMents
279
Error Handling
11/2008
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: Return code 5201 -5300 -5301 -5310 -5320 -5321 -5322 Description The maximum processing depth was reached. General error message for unsuccessful searches. The search engine itself reports an error (output in the "errorengine" result parameter). None of the Verity repositories requested by the search is available. The project was not found Problem preparing the native search (JNI setting only). Problem preparing the native search (JNI setting only). Problem preparing the native search (JNI setting only). General error message for unsuccessful search. lsserver rejected the search due to a system overload. Transfer to lsserver failed due to encoding problems. lsserver not responding, or other URL connection problems. The result returned by lsserver is completely blank. The result returned by lsserver is uncertain. The result returned by lsserver cannot be parsed. Transfer of search query to lsserver has failed because parameters are too long. Problems reading the result of a native search. For the combination of ProjectIDs and localeStrings entered, no Query Plan could be created. The SearchEngineIolet is not available. The LiveServer that serves as search engine server is not accessible. The necessary license is missing.
DynaMents
-5323 -5330 -5331 -5332 -5333 -5334 -5335 -5336 -5337 -5340 -5350 -5510 -5520 -5599
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.
280
11/2008
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.
DynaMents
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
11/2008
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>
DynaMents
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
<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" contexttags="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>
DynaMents
11/2008
You can use a suitable XSL style sheet to convert the search results into an HTML page.
283
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 "Fulltext 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
DynaMents
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.
RedDot LiveServer 9.0
This simplification applies to all areas of RedDot LiveServer. It applies in particular to the parameters of RedDot DynaMents.
284
11/2008
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>
DynaMents
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
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]" />
DynaMents
Parameters
mode
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.
Tag name of the XML element that surrounds each found content item in the result.
"{tagname}": Explicit specification of tag name. RedDot LiveServer 9.0 "notag": Content in the result is not enclosed in XML elements.
286
11/2008
tag (optional) Tag name of the resulting 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.
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.
DynaMents
287
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".
11/2008
DynaMents
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
RDB DynaMent
11/2008
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.
DynaMents
Syntax
<rde-dm:rdb mode alias sql row item-tag maxrows chunksize chunk /> ="query" ="{connector name}" ="{select...; select...}" ="[{tagname}|notag]" ="[{tagname}|notag]" ="{number} ="{number of records}" ="{chunk number}"
289
Parameters
11/2008 mode
Mode of the RDB DynaMent, here "query". Default setting, can be omitted.
alias
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. "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
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.
DynaMents 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.
tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
290
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 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. maxchunks-ca: Maximum number of chunks. DynaMents lastchunk: Number of the last chunk nextchunk: Number of the next chunk. previouschunk: Number of the previous 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).
RedDot LiveServer 9.0
291
11/2008
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 Pao, 67</Street> <Phone>(21) 555-0091</Phone> </hotel> <hotel> <Name>Hotel Brasil</Name> <Street>Rua Americana</Street> <Phone>(21) 555-3736</Phone> </hotel> </destination>
DynaMents
All hotels matching the value of the "city" attribute selected by the active user are displayed.
292
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
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).
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 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
11/2008
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).
Deleting a record:
<rde-dm:rdb mode="update" alias="linux-mysql" sql="Delete From HotelList Where id=230;"/>
294
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 alias sql row item-tag maxrows chunksize chunk /> ="statement" ="{connector name}" ="{sql statement}" ="[{tagname}|notag]" ="[{tagname}|notag]" ="{number} ="{number of records}" ="{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
Precisely one database query in SQL (in accordance with the ANSI standard).
295
11/2008
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. "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
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. DynaMents 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.
tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
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"
296
Result
11/2008
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. maxchunks-ca: Maximum number of chunks. lastchunk: Number of the last chunk nextchunk: Number of the next chunk. previouschunk: Number of the previous chunk.
DynaMents
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).
297
RedDot DynaMent
11/2008
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")
Syntax
DynaMents <rde-dm:reddot mode method alt show /> ="edit" ="html" ="{alternative text}" ="[yes|no]"
Parameters
mode
298
show 11/2008
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".
Syntax
<rde-dm:reddot mode method alt show /> ="template" ="html" ="{alternative text}" ="[yes|no]"
299
Parameters
11/2008 mode
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".
DynaMents
<rde-dm:reddot method="html" alt="Click here to edit the style sheet hscont-news" mode="template"/>
300
Reference DynaMent
11/2008
The Reference DynaMent contains functions for various objects that are called by a reference. Read more about the following actions: 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 "setscope" 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="readmultipart").
This allows you to optimize memory use when reading large upload files.
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 content text validfrom validto locale locale-policy mode RedDot LiveServer 9.0 ="{projectname}" ="{projectname:contentname}" ="{text}" ="{yyyy.mm.dd hh:mm:ss}" ="{yyyy.mm.dd hh:mm:ss}" ="{locale string}" ="[default|none|any]" ="[exists|validperiod|constraints|data| localizeddata|group|grouphierarchically| attributes|localizedattributes]" ="{content group}" ="{attribute name}"
301
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
DynaMents
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
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
11/2008
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"
DynaMents 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
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
303
11/2008
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.
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.
Result
DynaMents
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 "resultattribute".
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: Return code -14320 14203 14213 14223 14233 14243
RedDot LiveServer 9.0
Description The project was not found The content item was not found. Content is currently not valid. The session does not meet the constraints placed on the content The content item has no content data. The content item does not have the matching content data (for the requesting session). The content item is not located in the specified (fully-qualified) group. The content item is neither in the specified (fully-qualified) group nor one of its subgroups. Content item has no attributes Content item has no matching attributes (for the requesting session) 304
11/2008
DynaMents
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"> ... RedDot LiveServer 9.0
305
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 content project scope timeout /> ="set-scope" ="{project:content name}" ="{project}" ="{session|request|server}" ="{timeout in seconds}"
DynaMents
Parameters
mode
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
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)
11/2008
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)
DynaMents
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 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: Return code -14320 Description The project was not found.
See also: Calling Web Services (Page 531) Receiving and Processing Attachments (Page 540)
RedDot LiveServer 9.0
307
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 content project cache-id replace /> ="set-cache-id" ="{project:content name}" ="{project}" ="{cache-id}" ="[true|false]"
DynaMents
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
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
11/2008
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
DynaMents
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: Return code 14275 Description The cache entry already exists. Cache ID has not been renamed.
See also: Calling Web Services (Page 531) Receiving and Processing Attachments (Page 540)
309
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 op attachment-attribute attachment-name-prefix attachment-size max-attachments buffer-stream cache-id <rde-rd:import> ...metadata... </rde-rd:import> DynaMents </rde-dm:reference> ="read-multipart" ="[full|next-field|discard]" ="{attribute name}" ="{prefix name}" ="{size in kb}" ="{number}" ="[discard|keep]" ="{cache-id}" >
Parameters
mode
"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
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)
11/2008
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.
DynaMents
"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. If nothing is specified: No cache entries are created.
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"
Child Elements A child element called <rde-rd:import> is available in "read-multipart" mode for assigning metadata to content.
RedDot LiveServer 9.0 <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.
311
Result
11/2008
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: Return code -14320 -14501 -14503 -14504 -14505
DynaMents
Description The project was not found Processing of the multipart attachment has failed. No access to Weblet request The session does not meet the constraints placed on the content Unknown operator for "read-multipart" mode Unknown value in the buffer-stream attribute Attachment too large: size {file size} > attachment-size The current request is not a multipart request
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:
RedDot LiveServer 9.0
312
Reporting DynaMent
11/2008
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. Read more about the following actions: 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.
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
Simple call
11/2008 <rde-dm:reporting mode="browser" connector="Test" />
Parameters
mode
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.
DynaMents
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".
314
Syntax
11/2008 <rde-dm:reporting mode ="acknowledge" connector ="{connector name}" />
Simple call
<rde-dm:reporting mode="acknowledge" connector="Test" />
Parameters
mode DynaMents
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
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.
DynaMents
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
Syntax
11/2008 <rde-dm:reporting mode connector name chart-type content project cache-id-attribute cache-id ="report" ="{connector name}" ="{report name}" ="{chart type}" ="{content name}" ="{project name}" ="{attribute name}" ="{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:constraint> </rde-dm:reporting> DynaMents
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
317
"rdeDefaultBarChart": Two-dimensional bar chart 11/2008 "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 charttype parameter. The content must match the following format: <report-data> <rows> <row> <{name column 1}>{value <{name column 2}>{value <{name column 3}>{value <...>...</...> </row> <row> <{name column 1}>{value <{name column 2}>{value <{name column 3}>{value <...>...</...> </row> ... </rows> </report-data> DynaMents
1 column 1}</{name column 1}> 1 column 2}</{name column 2}> 1 column 3}</{name column 3}>
2 column 1}</{name column 1}> 2 column 2}</{name column 2}> 2 column 3}</{name column 3}>
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
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{randomid}.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.)
11/2008
DynaMents
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.
RedDot LiveServer 9.0
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
11/2008
When using the chart-type parameter, there are two optional parameters for use with userdefined 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.
DynaMents
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. Return code -28601 -28602 -28701 Description Invalid RDB connector Error from the RDB DynaMent Chart engine not initialized
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)
RedDot LiveServer 9.0
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) 320
11/2008
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.
DynaMents
</rde-dm:reporting>
This call requests the total of all page requests of the mysite Web site on January 1, 2007.
321
11/2008
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.
DynaMents RedDot LiveServer 9.0
322
11/2008
This call requests the visits per hour of the html-demo Web site for May 2, 2007, and shows them as a line chart.
DynaMents
323
11/2008
DynaMents
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
11/2008
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>
DynaMents
Reporting DynaMent:
<rde-dm:reporting mode="report" connector="test" content="sampledata.xml" chart-type="rdeDefaultPieChartWithDepth"> <rde-dm:param name="chartLegendVisible">true</rde-dm:param> <rde-dm:param name="chartLegendPosition">insideTopRight</rdedm: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
11/2008
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
<!-- (1) --> <rde-dm:attribute mode="write" attribute="request:myConstraint" value="reportLevel gt 2"/> <!-- (2) --> <rde-dm:attribute mode="write" attribute="request:loop" value="0"/> <rde-dm:attribute mode="for-each" attribute="request:cacheId"
DynaMents
326
alias="reportContentName" > <rde-dm:attribute mode="write" attribute="request:loop" op="increase" /> <!-- (3) --> <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> <!-- (4) --> <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>
DynaMents
11/2008
327
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):
DynaMents
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 site (value of the Web site field from a reporting connector) 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 site (value of the Web site field from a reporting connector) 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 site (value of the Web site field from a reporting connector) 328
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 site (value of the Web site field from a reporting connector) 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 site (value of the Web site field from a reporting connector) Page impressions per day for a Web site:
DynaMents
Name: page-impressions-per-site-per-day Description: Total number of page impressions for each day of a selected month Parameters: year month site (value of the Web site field from a reporting connector) 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 site (value of the Web site field from a reporting connector) 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 site (value of the Web site field from a reporting connector) 329
Name: visits-per-site-per-day Description: Total number of visits for each day of a selected month Parameters: year month site (value of the Web site field from a reporting connector) 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 site (value of the Web site field from a reporting connector) Visits per hour to a Web site:
DynaMents
Name: visits-per-site-per-hour Description: Total number of visits for each hour of a selected day Parameters: year month day site (value of the Web site field from a reporting connector) 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) site (value of the Web site field from a reporting connector)
330
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 project (project of the content item) content (content item) site (value of the Web site field from a reporting connector) 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:
DynaMents
year month project (project of the content item) content (content item) site (value of the Web site field from a reporting connector) 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 project (project of the content item) content (content item) site (value of the Web site field from a reporting connector)
331
11/2008
</rde-dm:reporting>
This call requests the total of all page requests of the mysite Web site on January 1, 2007.
DynaMents
332
11/2008
This call requests the visits per hour of the html-demo Web site for May 2, 2007, and shows them as a line chart.
DynaMents
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
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: rdeDefaultBarChart rdeDefaultBarChartWithDepth rdeDefaultPieChart rdeDefaultPieChartWithDepth rdeDefaultLineChart Bar Chart (Example): Two-dimensional bar chart Two-dimensional bar chart with depth Two-dimensional pie chart Two-dimensional pie chart with depth Two-dimensional line chart
DynaMents
334
DynaMents
335
General Parameters
11/2008
Parameter chartAreaColor
Description Background color of the diagram area Additional background color of the diagram area. Creates a smooth transition from right to left to the color specified here. Background color for the entire image Additional background color for the entire image. Creates a smooth transition from right to left to the color specified here. Font for all captions (title, axes, values, legend)
Values Hexadecimal value with leading #. Default: transparent Hexadecimal value with leading #. Default: transparent
chartAreaGradient
chartBackgroundColor
Hexadecimal value with leading #. Default: transparent Hexadecimal value with leading #. Default: transparent
chartBackgroundGradient
DynaMents
chartFont
Name of a font, available in the RedDot LiveServer operating system. Default: Arial Hexadecimal value with leading #. Default: black (#000000) Value in pixels. Default: 10
chartFontColor
Font color for all captions (title, axes, values, legend) Font size for all captions except title and values along the axes Height of image Width of image Colors to be used
chartFontSize
Value in points. Default: 400 Value in points. Default: 300 Hexadecimal value with leading #. Default: BIRT setting Possible values: inside, outside. Default: outside Default: Bar Chart Value in pixels. Default: 16
chartSeriesLabelPosition
Position at which numerical values of the diagram are shown Diagram title Font size for title
chartTitle
RedDot LiveServer 9.0
chartTitleFontSize
336
Description Font size of values along the axes Color of the axes
Values Value in pixels. Default: 10 Hexadecimal value with leading #. Default: black (#000000)
chartAxisTickColor
Color of ticks along the axes Hexadecimal value with leading #. Default: black (#000000) Color of the grid lines Hexadecimal value with leading #. Default: Light gray (#dddddd) Possible values: true, false. Default: false Possible values: true, false. Default: false Possible values: true, false. Default: false Integer. Default: 1
chartGridColor
Hide axes Showing grid lines of x axis (vertical lines) Values staggered along the x axis Step of values and ticks along the x axis. Is not evaluated if string is given as value for chartXAxisType. Defines if values for x axis are evaluated as string or integer. Caption of x axis Showing grid lines of y axis (horizontal lines) Staggered view of the values along the y axis Step of values and ticks along the y axis Caption of y axis
DynaMents
chartXAxisType
Possible values: string, integer. Default: integer Default: None Possible values: true, false. Default: false Possible values: true, false. Default: false Integer. Default: 1 Default: None
337
Description Background color of the legend Additional background color of the legend. Creates a smooth transition from right to left to the color specified here. Position of the legend
Values Hexadecimal value with leading #. Default: transparent Hexadecimal value with leading #. Default: transparent
chartLegendPosition
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
DynaMents
chartLegendTitle chartLegendVisible
RedDot LiveServer 9.0
338
The same parameters as for the rdeDefaultBarChart diagram type apply. The following parameters are possible in addition: Parameter chartFloorColor Description Color of the depth dimension on the x axis with diagrams that have depth and axes. Color of the depth dimension on the y axis with diagrams that have depth and axes. Values Hexadecimal value with leading #. Default: Dark gray (#808080) Hexadecimal value with leading #. Default: Dark gray (#808080)
chartWallColor
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: Parameter chartSeriesLabelPosition Description Position at which numerical values of the diagram are shown Values Possible values: above, below, left, right. Default: above
DynaMents
339
Parameter chartAreaColor chartAreaGradient chartBackgroundColor chartBackgroundGradient chartFont chartFontColor chartFontSize chartHeight chartWidth chartSeriesColor chartLegendPosition chartLegendTitle
Description see above see above see above see above see above see above see above see above see above see above see above see above see above see above see above see above Defines if numerical values are shown as an absolute value or as a percentage
Values see above see above see above see above see above see above see above see above see above see above see above see above see above Default: Pie Chart see above Possible values: inside, outside. Default: outside Possible values: dataValue, percentage. You can have both values shown, separated by a semicolon. Default: percentage Floating point number. Default: 0 Default: None Possible values: dataValue, percentileDataValue. Default: percentileDataValue
DynaMents
chartMinSliceBoundary
All values below the limit shown here are combined to one segment Name of the combined segment Specifies if the number given for chartSeriesLabel is to be evaluated as an absolute value or as a percentage
chartMinSliceLabel chartMinSliceType
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)
340
Repository DynaMent
11/2008
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. Read more about the following actions: Reading content from an external repository (mode="read")
DynaMents
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
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> ...metadata... </rde-rd:import> </rde-dm:repository>
DynaMents
Parameters
RedDot LiveServer 9.0 mode
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)
11/2008
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-MMdd'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:
"content-listdisplay": Some basic information about the content in each XML
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, contentbytesize, 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 RedDot LiveServer 9.0
data for the respective language. For BLOB type content, only a minimum of information is specified.
"metainfo": The metadata selected in the metainfo parameter, which is maintained as properties in the repository. "userinfo": Records the name and ID of the current Livelink session user in the result
XML.
343
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" 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"
metainfo (optional)
11/2008
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.
".*": Returns all standard properties. "{category}.*": Returns all properties for the specified category. "{property}": Returns the values for the standard properties specified. You can specify
categories. You can specify one or several property names separated by semicolons. To be able to output metadata, you need to specify the mode "metainfo" in the includemode parameter.
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
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
11/2008
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. If nothing is specified: No cache entries are created.
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. DynaMents 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
345
11/2008
tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
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
DynaMents
The content is read from the repository specified and returned in the result XML.
346
Error Handling
11/2008
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: Return code -27110 -27320 -27501 -27510 -27511 -27512 -27513 -27514 -27515 Description Incorrect argument for a parameter The project was not found Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to obtain list of available repositories Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error General error while accessing RepositoryItem (content/folder) Error while compiling a display element Error while compiling a display element (content-info) Error while compiling a display element (content-reference) Error while compiling a display element (metainfo) Error while compiling a display element (content) Error while compiling a display element (identifier) Error while creating the object to be cached Versioning has been requested but is not supported by the repository. Incorrect argument for a parameter (parameter name is specified in the error message). Unable to determine size of (native) content
DynaMents
-27521 -27522 -27523 -27530 -27561 -27580 -27581 -27582 -27583 -27584 -27585 -27586 27101 27103 27104
347
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.
DynaMents
348
Syntax
11/2008 ="query" ="{connector name}" ="{project name}" ="[locale1;locale2;...]" ="{date format}" ="[{include-mode},{tagname};]" ="[rdeallmetainfo|{property}]" ="{chunk number}" ="{number of records}" ="{number}" ="{property name}" ="[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 (fr 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> </rde-dm:repository> <rde-dm:repository mode name project locale dateformat-out include-mode metainfo chunk chunksize maxhits sortedby sortorder
DynaMents
Parameters
mode
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.
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)
11/2008
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-MMdd'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:
"content-listdisplay": Some basic information about the content in each XML
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, contentbytesize, type, rde-rd:mime. RedDot LiveServer 9.0 "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.
350
11/2008
"metainfo": The metadata selected in the metainfo parameter, which is maintained as properties in the repository. "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" 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"
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.
DynaMents ".*": Returns all standard properties. "{category}.*": Returns all properties for the specified category. "{property}": Returns the values for the standard properties specified. You can specify
categories. You can specify one or several property names separated by semicolons. To be able to output metadata, you need to specify the mode "metainfo" in the includemode parameter.
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
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.
sortorder (optional, only effective when used together with sortedby) Sort order for the entries: "asc" or "ascending": Ascending "desc" or "descending": Descending
11/2008
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"
DynaMents 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
Value if nothing is specified: The value entered in the system configuration for the reddot.idea.appserver.callurls key (default value is "yes").
version (optional)
Content version label that is read. The version label must be the same as that used in the repository.
item-tag (optional)
Tag name of the XML element that surrounds each found content item in the result.
"{tagname}": Explicit specification of tag name. "notag": Content in the result is not enclosed in XML elements.
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
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. 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
11/2008
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. If nothing is specified: No cache entries are created.
size-max (optional) DynaMents
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. 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. 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
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.
tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element. DynaMents
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]]>. RedDot LiveServer 9.0 <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
<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]]>.
11/2008
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 lastchunk: Number of the last possible chunk (when all found content items for the
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 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: Return code -27102 -27103 -27104 -27105
RedDot LiveServer 9.0
Description mode="query" has been requested but is not supported by the repository. mode="query" with property search has been requested but is not supported by the repository. mode="query" with full-text search has been requested but is not supported by the repository. mode="query" with full-text search AND simultaneous property search has been requested, but is not supported by the repository. Incorrect full-text criterion Incorrect property criterion Invalid query expression
355
11/2008
Return code -27320 -27501 -27510 -27511 -27512 -27513 -27514 -27515 -27521 -27522 -27523 -27530 -27571
Description The project was not found Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to obtain list of available repositories Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error Error while searching. None of the (syntax ?!) errors in 271xx. Error while sorting Error while compiling a display element Error while compiling a display element (content-info) Error while compiling a display element (content-reference) Error while compiling a display element (metainfo) Error while compiling a display element (content) Error while compiling a display element (identifier) Error while creating the object to be cached Versioning has been requested but is not supported by the repository. Incorrect argument for a parameter (parameter name is specified in the error message). Unable to determine size of (native) content Exceptions that occurred during query.execute() Folder search not supported Content class search not supported
DynaMents
-27572 -27580 -27581 -27582 -27583 -27584 -27585 -27586 27101 27103 27104 27111 27112 27113
356
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 name folder content-name contentclass-name dateformat-in ref-type ref encoding abort-events ="create" ="{connector name}" ="{folder id}" ="{content name}" ="{contentclass name}" ="{date format}" ="[embedded|file|named]" ="{reference}" ="{encoding}" ="[error|warn|none|{warning-codes}| {error-codes}]" >
DynaMents
<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> </rde-dm:repository>
357
Parameters
11/2008 mode
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: yyyyMM-dd'T'HH:mm). Also see the Livelink repository-specific information below. ref-type (optional)
DynaMents
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.
"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": 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 <rderd:import> child element. Value if nothing is specified: "embedded"
358
11/2008
ref (optional) Required entry only for: 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/WEBINF/. 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.
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) DynaMents
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. "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.
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-valueseparator 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
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). 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 sequencethat is, with a leading backslash (example: delimiters="\""). 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 DTD definition file
DynaMents
11/2008
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.
"no": Entities are not resolved. <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.
RedDot LiveServer 9.0
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
Error Handling
11/2008
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: Return code -27100 -27131 -27133 -27501 -27510 -27511 -27512 Description Incorrect argument for a parameter The mode ="create" has been requested, but it is not supported by the repository in this form The parameter contentclass-name has been specified but cannot be interpreted by the repository specified Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error General error while creating content "Native" content must be provided General error while setting the properties of a repository item The parameter contentclass-name has been specified but cannot be interpreted by the repository specified. Null-contentclasses are possible. The property specified in the import tag cannot be set, as it has not been defined. The property specified in the import tag cannot be set, as it is read only. The property specified in the import tag can possibly not be set (unable to determine type).
DynaMents
-27514 -27515 -27521 -27522 -27523 -27530 -27531 -27532 -27533 27106
361
11/2008
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.
DynaMents
362
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 name folder folder-name contentclass-name dateformat-in item-type abort-events ="create-folder" ="{connector name}" ="{folder id}" ="{folder name}" ="{contentclass name}" ="{date format}" ="[folder|compound_document]" ="[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-dm:repository>
DynaMents
Parameters
mode
363
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. 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: yyyyMM-dd'T'HH:mm). Also see the Livelink repository-specific information below. 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.
DynaMents
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. "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.
Child Elements In "create-folder" mode, there is one child element. 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. You can only specify one <keywords> element. You need to specify separators between each attribute and its value (name-valueseparator 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
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). 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 ). Value if nothing is specified: "no" "yes": All entities are resolved according to the DTD definition file
DynaMents
11/2008
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.
"no": Entities are not resolved.
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.
RedDot LiveServer 9.0
365
Error Handling
11/2008
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: Return code -27100 -27132 -27133 -27501 -27510 -27511 -27512 Description Incorrect argument for a parameter mode="create-folder" has been requested but is not supported by the repository in this form. The parameter contentclass-name has been specified but cannot be interpreted by the repository specified Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error General error while creating content General error while setting the properties of a repository item The parameter contentclass-name has been specified but cannot be interpreted by the repository specified. Null-contentclasses are possible. The property specified in the import tag cannot be set, as it has not been defined. The property specified in the import tag cannot be set, as it is read only. The property specified in the import tag can possibly not be set (unable to determine type).
DynaMents
366
11/2008
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.
DynaMents
367
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 name content dateformat-in ref-type ref encoding abort-events DynaMents ="update" ="{connector name}" ="{content id}" ="{date format}" ="[embedded|file|named]" ="{reference}" ="{encoding}" ="[error|warn|none|{warning-codes}| {error-codes}]" contentclass-name ="{contentclass name}" contentclass-action="[add|remove]" >
<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> </rde-dm:repository>
368
Parameters
11/2008 mode
DynaMents
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.
"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": 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 <rderd:import> child element. Value if nothing is specified: "embedded"
ref (optional) Required entry only for: 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/WEBINF/. 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, RedDot LiveServer 9.0
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.
encoding (optional) Only for reftype="embedded" and "named":
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. "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.
DynaMents
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.
<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-valueseparator 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 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
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). 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 ). Value if nothing is specified: "no" "yes": All entities are resolved according to the DTD definition file
DynaMents
11/2008
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.
"no": Entities are not resolved. <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.
371
Error Handling
11/2008
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: Return code -27100 -27101 -27141 -27501 -27510 -27511 -27512 Description Incorrect argument for a parameter The specified user does not have the rights to perform this action on the content item selected. mode="update" has been requested but is not supported by the repository in this form. Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error General error while accessing the repository content. General error while attempting update for repository content Versioning has been requested but is not supported by the repository. mode="update" query was made to change or define the ID of the content. This is not supported by the repository in this form. The property specified in the import tag cannot be set, as it has not been defined. The property specified in the import tag cannot be set, as it is read only. The property specified in the import tag can possibly not be set (unable to determine type).
DynaMents
-27514 -27515 -27521 -27522 -27523 -27530 -27561 -27565 27101 27107 27108 27109 27110
372
11/2008
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.
DynaMents
373
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 name folder dateformat-in abort-events ="update-folder" ="{connector name}" ="{folder id}" ="{date format}" ="[error|warn|none|{warning-codes}| {error-codes}]" contentclass-name ="{contentclass name}" contentclass-action="[add|remove]" >
<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-dm:repository>
DynaMents
Parameters
mode
374
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: yyyyMM-dd'T'HH:mm). Also see the Livelink repository-specific information below. abort-events (optional)
11/2008
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. "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.
DynaMents
Child Elements In "update-folder" mode, there is one child element. 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-valueseparator 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:).
375
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). 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 sequencethat is, with a leading backslash (example: delimiters="\""). 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 DTD definition file
DynaMents
11/2008
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.
"no": Entities are not resolved.
376
Error Handling
11/2008
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: Return code -27100 -27101 -27110 -27142 -27501 -27510 -27511 Description Incorrect argument for a parameter The specified user does not have the rights to perform this action on the content item selected. mode="update-folder" has been requested, but the repository does not support folders. mode="update-folder" has been requested but is not supported by the repository in this form. Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error General error while setting the properties of a repository item General error while accessing the repository content General error while attempting update for repository content 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. The property specified in the import tag cannot be set, as it has not been defined. The property specified in the import tag cannot be set, as it is read only. The property specified in the import tag can possibly not be set (unable to determine type).
DynaMents
-27512 -27514 -27515 -27521 -27522 -27523 -27530 -27533 -27561 -27565 27107
377
11/2008
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.
DynaMents
Syntax
<rde-dm:repository mode ="delete" name ="{connector name}" content ="{content id}" />
Parameters
mode
378
content 11/2008
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 -27100 -27101
DynaMents
Meaning Incorrect argument for a parameter The active user does not have the rights to perform this action on the content item selected. mode="delete" has been requested but is not supported by the repository in this form. Unknown error when using the bridge. Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General error while executing General error while deleting a repository item. General error while accessing a repository item. Versioning has been requested but is not supported by the repository.
-27111 -27501 -27510 -27511 -27512 -27514 -27515 -27521 -27522 -27523 -27530 -27551 -27561 27101
379
Purpose You delete folders from an external repository using the Repository DynaMent in "deletefolder" mode.
Syntax
<rde-dm:repository mode ="delete-folder" name ="{connector name}" folder ="{folder id}" />
Parameters
mode
Results Provided the user has the necessary rights, the folder is deleted from the external repository.
380
Error Handling
11/2008
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 -27100 -27101 -27110 -27112 -27501 -27510 -27511 Meaning Incorrect argument for a parameter The active user does not have the rights to perform this action on the content item selected. mode="delete-folder" has been requested but is not supported by the repository. mode="delete-folder" has been requested but is not supported by the repository in this form. Unknown error when using the bridge. Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General error while executing General error while deleting a repository item. General error while accessing a repository item.
DynaMents
381
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 name content dateformat-in ref-type ref encoding abort-events DynaMents ="checkin" ="{connector name}" ="{content id}" ="{date format}" ="[embedded|file|named]" ="{reference}" ="{encoding}" ="[error|warn|none|{warning-codes}| {error-codes}]" contentclass-name ="{contentclass name}" contentclass-action="[add|remove]" >
<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> </rde-dm:repository>
382
Parameters
11/2008 mode
DynaMents
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.
"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": 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 <rderd:import> child element. Value if nothing is specified: "embedded"
ref (optional) Required entry only for: 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/WEBINF/. 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, RedDot LiveServer 9.0
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.
encoding (optional) Only for reftype="embedded" and "named".
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. "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.
DynaMents
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.
<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-valueseparator 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 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
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). 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 sequencethat is, with a leading backslash (example: delimiters="\""). 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 DTD definition file
DynaMents
11/2008
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.
"no": Entities are not resolved. <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 content item specified is changed in the repository and the content lock removed.
385
Error Handling
11/2008
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: Return code -27101 -27121 -27143 -27501 -27510 -27511 -27512 Description The specified user does not have the rights to perform this action on the content item selected. mode="checkin" has been requested but is not supported by the repository in this form. mode="checkin" has been requested but is not supported by the repository in this form. Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error General error while setting the properties of a repository item. General error while accessing the repository content General error while attempting checkin for repository content. The repository content is not checked out Versioning has been requested but is not supported by the repository. mode="checkin" query was made to change or define the ID of the content. This is not supported by the repository in this form. The property specified in the import tag cannot be set, as it has not been defined. The property specified in the import tag cannot be set, as it is read only. The property specified in the import tag can possibly not be set (unable to determine type).
DynaMents
-27514 -27515 -27521 -27522 -27523 -27530 -27533 -27561 -27564 -27566 27101 27107 27108 27109
27110
386
11/2008
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.
DynaMents
387
Syntax
11/2008 <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.
DynaMents
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 -27101 -27121 -27320
RedDot LiveServer 9.0
Meaning The active user does not have the rights to perform this action on the content item selected. mode="checkout" has been requested but is not supported by the repository in this form. Project was not found General error while accessing RepositoryItem (content/folder) General error while attempting checkout for repository content. The content item you wish to check out is already checked out Versioning has been requested but is not supported by the repository. 388
See also: Reading Content from External Repository ('read') (Page 342)
Syntax
<rde-dm:repository mode ="cancel-checkout" name ="{connector name}" content ="{content id}" />
Parameters
mode
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.
RedDot LiveServer 9.0
389
Error Handling
11/2008
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 -27100 -27101 -27122 -27501 -27510 -27511 -27512 Meaning Incorrect argument for a parameter The active user does not have the rights to perform this action on the content item selected. mode="cancel-checkout" has been requested but is not supported by the repository in this form. Unknown error when using the bridge. Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General error while executing General error while accessing RepositoryItem (content/folder) General error while attempting CancelCheckout for repository content. Versioning has been requested but is not supported by the repository. Content is not currently checked out.
DynaMents
-27514 -27515 -27521 -27522 -27523 -27530 -27561 -27563 27101 27105
390
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
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.
Result The available content classes or categories for all contents are listed.
391
Error Handling
11/2008
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 -27100 -27501 -27510 -27511 -27512 -27514 -27515 -27521 -27522 Meaning Incorrect argument for a parameter Unknown error when using the bridge. Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General error while executing Although content classes are supported, they cannot be listed.
DynaMents
392
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}" />
DynaMents
Parameters
mode
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
Error Handling
11/2008
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: Return code -27100 -27110 -27501 -27510 -27511 -27512 -27514 -27515 Description Incorrect argument for a parameter mode="list-classes-folder"has been requested, but the repository does not support folders. Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error Although content classes are supported, they cannot be listed.
DynaMents
394
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]" />
DynaMents
Parameters
mode
395
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.
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)
11/2008
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-MMdd'T'HH:mm). If nothing is specified: No formatting.
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:
"content-listdisplay": Some basic information about the content in each XML
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, contentbytesize, type, rde-rd:mime. RedDot LiveServer 9.0 "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.
396
11/2008
"metainfo": The metadata selected in the metainfo parameter, which is maintained as properties in the repository. "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" 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"
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.
DynaMents ".*": Returns all standard properties. "{category}.*": Returns all properties for the specified category. "{property}": Returns the values for the standard properties specified. You can specify
categories. You can specify one or several property names separated by semicolons. To be able to output metadata, you need to specify the mode "metainfo" in the includemode parameter.
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
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"
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
11/2008
Value if nothing is specified: The value entered in the system configuration for the reddot.idea.appserver.callurls key (default value is "yes").
version (optional)
Content version label that is read. The version label must be the same as that used in the repository.
DynaMents item-tag (optional)
Tag name of the XML element that surrounds each found content item in the result.
"{tagname}": Explicit specification of tag name. "notag": Content in the result is not enclosed in XML elements.
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.
RedDot LiveServer 9.0
398
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
11/2008
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. If nothing is specified: No cache entries are created.
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. DynaMents 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. 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
399
11/2008
tag (optional) This is the tag name of the XML element that displays the result of the DynaMent. "{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
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 lastchunk: Number of the last possible chunk (when all found content items for the
The individual entries found are output consecutively in item-tag elements (default: "rderd-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
Error Handling
11/2008
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: Return code -27100 -27320 -27501 -27510 -27511 -27512 -27513 -27514 -27515 Description Incorrect argument for a parameter The project was not found Unknown error when using the bridge Unable to load bridge support Unable to find connector specified Unable to access bridge Unable to obtain list of available repositories Unable to access repository Unable to check repository (for capabilities) The user cannot log on The user cannot log off No cleanup possible after the access General execution error Error while executing the finder Error while compiling a display element Error while compiling a display element (content-info) Error while compiling a display element (content-reference) Error while compiling a display element (metainfo) Error while compiling a display element (content) Error while compiling a display element (identifier) Error while creating the object to be cached Versioning has been requested but is not supported by the repository. Incorrect argument for a parameter (parameter name is specified in the error message). Unable to determine size of (native) content Exceptions which occurred during finder.execute() Display of parent folders is not supported
DynaMents
-27521 -27522 -27523 -27530 -27573 -27580 -27581 -27582 -27583 -27584 -27585 -27586 27101 27103 27104
27111 27114
401
Script DynaMent
11/2008
The Script DynaMent runs scripts for the dynamic display of contents. Read more about the following actions: 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
DynaMents <rde-dm:script project name content script-requestparams include-mode item-tag ="{projectname}" ="{projectname:contentname}" ="{projectname:contentname}" ="[none|readonly|readwrite]" ="[cdata|text|xml|mixed]" ="[notag|{tagname}]" >
<parameter name-1>{value 1}</parameter name-1> ... <parameter name-n>{value n}</parameter name-n> ... </rde-dm:script>
Parameters
RedDot LiveServer 9.0 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
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
11/2008
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. DynaMents "readwrite": Request parameters can be read and written.
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
Tag name of the XML element that is used to enclose the result within the result tag in case an error occurs during parsing.
"{tagname}": Explicit specification of tag name. "notag": The results are listed without the surrounding XML elements.
403
11/2008
tag (optional) This is the tag name of the resulting 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.
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. DynaMents
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
Error handling
11/2008
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: Return code -11511 11111 11401 Description The script generated an error message. Result is not XML; include-mode="mixed" was used. The script returns no value.
session
You can find the description of the methods of this object in the API documentation. content type base64 project String String Object String Content Content type (XML, XSL, HTML, Script) Base64 encoder for authentication Project name
405
11/2008
test.py
import sys result="<result><a>aaa</a><b>bbb</b></result>"
DynaMents
406
Tagging DynaMent
11/2008
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")
DynaMents
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).
RedDot LiveServer 9.0
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
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.
DynaMents
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
11/2008
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?
Syntax
DynaMents <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
11/2008
Child Elements The Tagging DynaMent in "defineTags" mode has one child element.
<rde-rd:tag>
Tag name.
DynaMents <type>
410
Error Handling
11/2008
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: Return code -35333 -35334 Description Cannot locate tagging configuration service Cannot locate tagging configuration
DynaMents
411
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>
DynaMents
412
Parameters
mode
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> RedDot LiveServer 9.0
413
"community": Default type. Is also assigned when end users assign tags. 11/2008 "editorial": Tags created by an editor or administrator. <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
DynaMents
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>
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
414
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>
11/2008
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
Result The name or the XML structures of the read tags are returned, depending on the setting in the metainfo parameter.
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: Return code -35333 -35334 Description Cannot locate tagging configuration service Cannot locate tagging configuration
415
Syntax
11/2008 <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>
DynaMents
Parameters
mode
416
Child Elements
11/2008
Date the tag was last changed. You can specify several elements to define a date range.
DynaMents
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>
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
match 11/2008
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 DynaMents
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: Return code
RedDot LiveServer 9.0
Description Cannot locate tagging configuration service Cannot locate tagging configuration
-35333 -35334
418
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
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
419
Child Elements
11/2008
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:
DynaMents
Description Cannot locate tagging configuration service Cannot locate tagging configuration
420
Syntax
11/2008 <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> DynaMents
Parameters
mode
Child Elements The Tagging DynaMent in "assignTags" mode has two child elements.
RedDot LiveServer 9.0 <rde-rd:targets>
List of target objects that are assigned tags, in individual <rde-rd:target> elements.
<rde-rd:target>
11/2008
"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.
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) DynaMents
Variant within the target object. For target objects types "content" and "contentsnippet": 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".
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>
Result The specified tags are assigned to all specified target objects. Tags that do not exist yet are created automatically with type community.
422
Error Handling
11/2008
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: Return code -35333 -35334 Description Cannot locate Tagging configuration service Cannot locate Tagging configuration
For more information about assigning tags with the Import DynaMent, see the separate section. For more information, see: Import DynaMent (Page 140) Defining and Assigning Tags (Page 155)
DynaMents
In this example, the sports tag is assigned to content items index.htm and news.htm.
423
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 configuration-project tagging-configuration uniqueness-values ="unassignTags" ="{project name}" ="{tagging configuration}" ="{value;value;..." >
DynaMents
<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
424
11/2008
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>
DynaMents
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 "contentsnippet": 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".
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. 425
<rde-rd:tags> 11/2008
List of tags whose assignments to target objects will be deleted, in individual <rde-rd:tagname> elements.
<rde-rd:tag-name>
Result The assignments of the specified tags are deleted for all specified target objects.
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: Return code -35333
DynaMents
Description Cannot locate Tagging configuration service Cannot locate Tagging configuration
-35334
In this example, the news tag is removed from content item index.htm.
426
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 configuration-project tagging-configuration suggestion-list-variant maxtags item-tag DynaMents > <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> ="suggestTags" ="{project name}" ="{tagging configuration}" ="{variant name}" ="{1-n}" ="[{tagname=|notag]"
Parameters
mode
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
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)
11/2008
Tag name of the XML element that surrounds each tag in the result.
"{tagname}": Explicit specification of tag name. "notag": Content in the result is not enclosed in XML elements.
Child Elements The Tagging DynaMent in "suggestTags" mode has two child elements.
<rde-rd:tag-name>
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 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: Return code -35333 -35334
RedDot LiveServer 9.0
Description Cannot locate tagging configuration service Cannot locate tagging configuration
428
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 configuration-project tagging-configuration chunksize chunk maxhits ignore-constraints dateformat-out dateformat-in context-mode item-tag > ="getAssignments" ="{project name}" ="{tagging-configuration}" ="{number of records}" ="{chunk number}" ="{number}" ="[no|yes|completely]" ="{date format}" ="{date format}" ="[mixed|cdata|none]" ="[{tagname}|notag]"
DynaMents
<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:tag-assignment> </rde-rd:assignment-filter> </rde-dm:tagging>
429
Parameters
mode
DynaMents
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"
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.
"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 includemode="content".
RedDot LiveServer 9.0 "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. Value if nothing is specified: "no"
430
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. "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.
11/2008
Tag name of the XML element that surrounds each selected content item in the result.
"{tagname}": Explicit specification of tag name. "notag": Content in the result is not enclosed in XML elements.
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>
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. RedDot LiveServer 9.0 "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
11/2008
<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:target>
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".
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:tag-assignment> (optional) RedDot LiveServer 9.0
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
11/2008
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 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: Return code -35333
DynaMents
Description Cannot locate tagging configuration service Cannot locate tagging configuration
-35334
433
11/2008
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>
DynaMents
434
<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>
DynaMents
11/2008
435
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 configuration-project tagging-configuration metainfo sortedby sortorder dateformat-out > ="getAssignedTags" ="{project name}" ="{configuration name}" ="[tag-name|tag]" ="{field name of tag}" ="[asc|desc]" ="{date format}"
<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:assignment-filter> <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>
DynaMents
436
Parameters
11/2008 mode
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.
DynaMents 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>
437
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 "contentsnippet": 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".
DynaMents
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: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:tag-assignment> (optional)
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
RedDot LiveServer 9.0
The name or the XML structures of the read tags are returned, depending on the setting in the metainfo parameter.
438
Error Handling
11/2008
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: Return code -35333 -35334 Description Cannot locate tagging configuration service Cannot locate tagging configuration
DynaMents
The result:
<tags> <tag-name>sports</tag-name> <tag-name>news</tag-name> </tags>
439
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: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> RedDot LiveServer 9.0 <rde-rd:tag-assignment> <rde-rd:constraint> {constraint expression} </rde-rd:constraint> </rde-rd:tag-assignment> </rde-rd:assignment-filter>
DynaMents
440
<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>
11/2008
Parameters
mode DynaMents
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" 441
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.
"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 includemode="content".
"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. Value if nothing is specified: "no"
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" cache-id-attribute (optional)
DynaMents
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.
item-tag (optional)
Tag name of the XML element that surrounds each selected content item in the result.
"{tagname}": Explicit specification of tag name. RedDot LiveServer 9.0 "notag": Content in the result is not enclosed in XML elements.
442
Child Elements
11/2008
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. Only target objects to which the tag was assigned at the specified time are included in the result.
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. DynaMents "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. <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:target>
Element that restricts the set of target objects included in the result.
<type>
Only used for type="content" and type="content-snippet". Content item in RedDot LiveServer as a target object.
443
11/2008
<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".
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:tag-assignment> (optional)
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"
<rde-rd:include-modes> (optional)
List for adding data for target objects in individual <rde-rd:include-mode> elements.
<rde-rd:include-mode>
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 name element.
444
You can specify one or more values separated by semicolons as the includemode 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 requested information item increases the runtime if the result is not already available in the cache. Therefore, we recommend using the includemode 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 contexttags 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,contextmode1;tagname2;tagname3,context-mode3"
DynaMents
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.
"mixed": Any angle brackets of tags contained in the content are replaced
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. RedDot LiveServer 9.0
445
Result
11/2008
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 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: Return code -35333 -35334 Description Cannot locate tagging configuration service Cannot locate tagging configuration
DynaMents
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
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}
DynaMents
447
11/2008
Parameters
mode
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. RedDot LiveServer 9.0
448
11/2008
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.
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
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
11/2008
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:assignment-filter> (optional)
You can specify filter criteria in additional elements within this child element to restrict the result.
<rde-rd:assignmenttime>
Operator used to compare the assignment time of the tag with the assignment time specified above. Possible values:
DynaMents "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. <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:target>
450
<project> 11/2008
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".
DynaMents
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:tag-assignment> (optional)
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 consolidated data is put in an XML structure. The <consolidation> child element is flagged with type="rule", as consolidation is predefined.
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 resultattribute. In addition to the general return codes (see Error Handling in the RedDot DynaMents chapter), the following messages are possible: Return code -35333 -35334 Description Cannot locate tagging configuration service Cannot locate tagging configuration
451
11/2008
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" periodstart="2008-11-14 02:08:28" storage-project="tagging" qualifyingvalues="" 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>
DynaMents
452
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>
DynaMents
</rde-dm:tagging>
453
Parameters
11/2008 mode
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. DynaMents "{time_value}...{time_value}": All reporting periods that lie within the specified period are returned, each in a separate <report-data> element.
Determines the order in which the data lines are displayed. The following values are possible:
"tag": Alphabetically by tag name RedDot LiveServer 9.0 "assignments": Numerically by number of assignments
454
11/2008
"qualifying-value, tag": Numerically or alphabetically by the value from qualifying-value, depending on the type of the first value. Alphabetically by tag name
DynaMents
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. RedDot LiveServer 9.0 "true": Data is flushed to the database immediately. This setting results in high system loads. You should therefore use it sparingly.
455
Child Elements
11/2008
The Tagging DynaMent in "getConsolidatedData" mode has one optional child element.
<rde-rd:target> (optional)
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 "contentsnippet": 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".
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.
Result The consolidated data is put in an XML structure. The <consolidation> child element is flagged with type="rule".
456
Error Handling
11/2008
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: Return code -35333 -35334 Description Cannot locate tagging configuration service Cannot locate tagging configuration
DynaMents
457
11/2008
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" configurationproject="tagging" tagging-configuration="taggingConfig" consolidationrule="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" periodstart="2008-11-14 02:00:00" storage-project="tagging" qualifyingvalues="" 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>
DynaMents
458
11/2008
</report-data> </consolidated-data>
Syntax
<rde-dm:tagging mode configuration project tagging-configuration consolidation-rule assignmenttime dateformat-in </rde-dm:tagging> DynaMents ="deleteConsolidatedData" ="{project}" ="{tagging configuration}" ="{tagging consolidation rule}" ="{date within reporting period}" ="{date format}"
Parameters
mode
Date and time to select a reporting period. The format is specified using the dateformat-in parameter. The following options are available:
"{Date + Time}": Reporting period in which the date and time are contained. "*": The reporting period for time interval Perpetual is sent in the <report-data>
element.
459
11/2008
"[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.
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: Return code -35333 -35334 Description Cannot locate tagging configuration service Cannot locate tagging configuration
DynaMents
460
Target DynaMent
11/2008
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. Read more about the following actions: Use the Target DynaMent to access specific content items and link constraints for content attributes in child element <rde-dm:constraint> (mode="select").
DynaMents
461
Syntax
11/2008 <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}" item-tag ="[{tagname}|notag]" > <rde-dm:constraint> {constraint expression} </rde-dm:constraint> </rde-dm:target>
DynaMents
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
Parameters
11/2008 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 enUS. 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: "none": If a value is not available in the language you require, no values are read in any
DynaMents
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"
RedDot LiveServer 9.0 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.
463
itself.
"content": Only for text type (XML, HTML, XSL, SCRIPT): 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. The following is an example of the correct syntax: "content-info,info;content,result" 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"
context-mode (optional)
DynaMents
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. RedDot LiveServer 9.0 "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.
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)
11/2008
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"
maxhits (optional) Maximum number of hits returned (1 n). If nothing is specified: No restriction; all hits are returned. 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.
sortorder (optional, only effective when used together with sortedby) Sort order for the entries: "asc": ascending order "desc": descending order
DynaMents
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).
RedDot LiveServer 9.0 "{1...n}": The content constraints will be checked for the specified number of content
465
Setting that determines whether content constraints are considered for the display of search results (see also the constraints parameter in the Result section).
"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 includemode="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. Value if nothing is specified: "no"
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"
DynaMents 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. 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.
RedDot LiveServer 9.0
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
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)
11/2008
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).
item-tag (optional)
Tag name of the XML element that surrounds each selected content item in the result.
"{tagname}": Explicit specification of tag name. "notag": Content in the result is not enclosed in XML elements.
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
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.rdestructure.category).
Operator: Specifies the relational operators used to compare the content attribute
11/2008
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
comparison value.
DynaMents "le" (less equal): Checks whether the content attribute is less than or equal to
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 <rdedm:constraint>. Value if a specified comparison value does not have a value: "-1" for numerical values, blank string "" for character strings.
468
11/2008
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.
DynaMents
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.
469
11/2008
"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"
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 resultattribute. In addition to the general return codes (see "Error Handling" in the "RedDot DynaMents" chapter), the following error messages are possible: Return code -4201 -4320
DynaMents
Description The maximum processing depth was reached. Project was not found. A parsing error occurred. The redundant database structure is unknown. An error occurred while executing the OQL query.
470
11/2008
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 <rdedm: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"
DynaMents
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
11/2008
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).
DynaMents
For more information about redundant database structures, see the Projects/Contents documentation.
RedDot LiveServer 9.0
472
11/2008
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 dAsti Naturale (Italy)</name> <description> Moscato dAsti 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>
DynaMents
473
User DynaMent
11/2008
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. Read more about the following actions: Outputting the active user's properties (mode="session") Determining a user's logon details (mode="session-check")
DynaMents
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
11/2008
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.
The user name, for example, is saved under the following attribute: "rde-edit-user.rdefields.name"
475
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.rdefields.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 attributee.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.
DynaMents
11/2008
476
11/2008
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-edituser". 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.
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
11/2008
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.
DynaMents
478
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"> <!-- *1* check whether we're logged in --> <rde-dm:attribute mode="condition" attribute="loggedIn" source="session" op="eq" value="yes"> <rde-dm:if> <!-- *2* we are logged in, display the logout button --> <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> <!-- *3* we are not logged in, check whether we must change our old password --> <rde-dm:attribute mode="condition" attribute="request:login-result" op="ne" value="-6522"> <rde-dm:if> <!-- *4* no indication that we must change our password --> 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> <!-- *5* code -6522 is likely to result from a DynaMent mode="login", telling us to change our password --> <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"/>"/>
DynaMents
11/2008
479
<input type="hidden" name="action" value="changepwd"/> </rde-dm:else> </rde-dm:attribute> </rde-dm:else> </rde-dm:attribute> <!-- *6* complete the form --> <input type="hidden" name="cpssessionid" value="[#session:rderd:sid#]"/> <input type="submit" /> </form>
11/2008
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"> <!-- *1* change the password --> <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> <!-- *2* no error loading the user, old password is correct
DynaMents
480
--> <rde-dm:attribute mode="write" attribute="userdata.rdefields.password" source="user" value="[#request:newpwd#]" /> <rde-dm:attribute mode="write" attribute="userdata.rdefields.force-password-change" source="user" value="false" /> <rde-dm:user mode="update" path="userdata" user="[#request:login#]" /> <!-- *3* switch to action=login and with the new password --> <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> <!-error loading the user, e.g. old password is incorrect --> <rde-dm:include content="login.htm"/> </rde-dm:else> </rde-dm:attribute> </rde-dm:attribute>
DynaMents
11/2008
<rde-dm:attribute attribute="action" mode="condition" op="eq" source="request" value="login"> <!-- *4* log in --> <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" redirectparameter="login=[#request:login#]&cpssessionid=[#session:rderd:sid#]" result-attribute="login-result" /> </rde-dm:attribute> <rde-dm:attribute attribute="action" mode="condition" op="eq" source="request" value="logout"> <!-- *5* log out --> <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
11/2008
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>
DynaMents
Syntax
<rde-dm:user mode depth path appserver /> ="session" ="[0|1|...n]" ="{attributename}" ="[yes|no]"
The standard parameter cachingtime cannot be used. This DynaMent sets the caching time for the respective content to "0".
482
Simple Call
11/2008 <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".
DynaMents 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
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. "{tagname}": Explicit specification of tag name. "notag": The results are listed without the surrounding XML elements.
Result
RedDot LiveServer 9.0
The essential user fields (master data) and selected user attributes will be output. The user password will not be output.
483
Error Handling
11/2008
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</rdeidea: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>
DynaMents
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
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 user password /> ="session-check" ="{username}" ="{user password}"
DynaMents
The standard parameter cachingtime cannot be used. This DynaMent sets the caching time for the respective content to "0".
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
Parameters
11/2008 mode
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 6220 6221 6222 6223 -6502 Meaning There is no LiveServer session on this server for the user. There is a LiveServer session on this server for the user, but the user can log on with multiple sessions. There is a LiveServer session on this server for the user, which will be used when the user logs on again. There is a LiveServer session on this server for the user, which will be terminated before the user logs on again. Wrong user or password
DynaMents
486
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 user password login-content login-fail redirect redirect-parameter login-url login-fail-url relogin directory-service project checkonly /> ="login" ="{username}" ="{user password}" ="{contentname}" ="{contentname}" ="[no|yes]" ="{parameters}" ="{url}" ="{url}" ="[no|yes]" ="[{connector-name}| LiveServer Repository]" ="{project}" ="[no|yes]"
DynaMents
The standard parameter cachingtime cannot be used. This DynaMent sets the caching time for the respective content to "0".
Simple Call
<rde-dm:user mode="login" user="username" password="password" logincontent="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.
RedDot LiveServer 9.0
487
Parameters
11/2008 mode
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
DynaMents
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. If no value is specified: "no"
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
11/2008
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
DynaMents
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. RedDot LiveServer 9.0 "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. If no value is specified: "no"
489
Notes
11/2008
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 -6320 -6502 Meaning The project was not found 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". Password is correct, but must be changed. The user was not logged on. User already logged on to current session, no relogon
DynaMents
-6522 6220
490
11/2008
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.
DynaMents
491
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]" />
DynaMents
The standard parameter cachingtime cannot be used. This DynaMent sets the caching time for the respective content to "0".
Simple Call
<rde-dm:user mode="login-trusted" user="username" logincontent="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
Parameters
11/2008 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.
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
Syntax
11/2008 <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."
DynaMents
Simple Call
<rde-dm:user mode="logout" logout-content="logout.htm" />
Parameters
mode
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. RedDot LiveServer 9.0 "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. Value if nothing is specified: "no"
494
11/2008
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. DynaMents 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.
RedDot LiveServer 9.0
495
Result
11/2008
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.
Syntax
<rde-dm:user mode user /> ="exists" ="{username}"
The standard parameter cachingtime cannot be used. This DynaMent sets the caching time for the respective content to "0".
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
Parameters
11/2008 mode
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": Return code
DynaMents
Meaning Processing completed successfully. The user does not exist in the LiveServer Repository or in the directory service. Processing completed successfully. The user exists in the LiveServer Repository or in the directory service.
6200 6210
<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).
497
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}" />
DynaMents
The standard parameter cachingtime cannot be used. This DynaMent sets the caching time for the respective content to "0".
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
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.
RedDot LiveServer 9.0
498
Result
11/2008
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": Return code - 6501 - 6511 - 6513 Meaning Incorrect password. User not found Procedure failed because the user is locked.
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 rdefields.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-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.rdefields.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.
499
Syntax
11/2008 <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"/> DynaMents
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
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.
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
Result
11/2008
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": Return code - 6504 - 6512 - 6513
DynaMents
Description User password contains less than 5 characters or is not correct User already exists User is currently being edited and is locked
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#]"/>
The result: The new user is created with the user name and password read from attributes "rdeedit-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)
501
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). The defined attribute branches below path are:
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.rdefields.login"
If no other user is specified, the user's properties from the active session are loaded.
DynaMents
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 user ="load" ="[{username}| rdeCurrentSessionUser]" password ="{password}" path ="{attributename}" directory-service ="[{connector-name}| RedDot LiveServer Repository]" project ="{projectname}"
502
11/2008
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="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
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.
DynaMents
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
11/2008
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.
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": Return code - 6315 - 6501 - 6511 - 6513 - 6516 Description Required directory service not found Incorrect password. User not found User is currently being edited and is locked Required project not found, using current project
DynaMents RedDot LiveServer 9.0
504
11/2008
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.
DynaMents
The result: The loaded user's data is displayed below attribute "rde-edit-user" in the session's active user.
RedDot LiveServer 9.0
See also: Using the User DynaMent (Page 475) Predefined Attributes for Source 'user' for Loaded Users (Page 558)
505
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. The defined attribute branches below path are:
rde-fields: User fields rde-groups: Groups rde-roles: Roles rde-attributes: Attributes
DynaMents
The user name, for example, is saved under the following attribute: "rde-edit-user.rdefields.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
11/2008
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="update" />
The user data that is read from the active user's attributes below the attribute "rde-edituser" is updated. Attributes that are not specified there are not changed.
Parameters
mode
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)
DynaMents
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
Error Handling
11/2008
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": Return code - 6503 - 6504 - 6511 - 6513 - 6521 Description User logon not correct User password contains less than 5 characters or is not correct User not found User is currently being edited and is locked Attribute path for data not found.
DynaMents
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 result: The user name of the user to edit is read from attribute"rde-edit-user.rdefields.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:
RedDot LiveServer 9.0
Using the User DynaMent (Page 475) Predefined Attributes for Source 'user' for Loaded Users (Page 558)
508
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>
DynaMents
509
11/2008
The standard parameter cachingtime cannot be used. This DynaMent sets the value of the caching time for the respective content to "0."
Parameters
mode
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}.rdegroups 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. DynaMents "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
510
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). Value if nothing is specified: "false".
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.
DynaMents mode
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
Error Handling
11/2008
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": Return code -6623 -6624 Description This user group does not exist in the LiveServer Repository. Invalid value for the op parameter.
See also: Loading Users to Active Sessions ('load') (Page 502) Updating Users ('update') (Page 506) Reading Properties of Selected Users ('report') (Page 514)
DynaMents
512
11/2008
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
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 depth buffersize chunk chunksize sortedby sortorder user path delim resulttype filename encoding item-tag ="report" ="[0|1|...n]" ="[1|2|4|8...]" ="{chunk number}" ="{number of records}" ="{username|name}" ="[asc|desc]" ="{usernames}" ="{attributename}" ="{separator}" ="[csv|xml]" ="{filename}" ="{encoding}" ="[{tagname}|notag]" >
DynaMents
<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
11/2008
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"/>
Parameters
mode
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
"username": User name for logging on to RedDot LiveServer 11/2008 "name": User name
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.
DynaMents
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) RedDot LiveServer 9.0
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
"{tagname}": Explicit specification of tag name. 11/2008 "notag": User records in the result are listed without the surrounding XML elements.
This is the tag name of the XML element that displays the result of the DynaMent.
"{tagname}": Explicit specification of tag name. "notag": The result is shown without the enclosing XML element.
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)
DynaMents
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)
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
<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")
11/2008
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.
DynaMents <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
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:
11/2008
"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.
DynaMents
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)
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
11/2008
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.
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</rdeidea: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
11/2008
Alongside the general user data for the "admin" user, the two user attributes "address.street" and "profile.level" are output.
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>
DynaMents
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
11/2008
Attribute "profile.level" has a value greater than 3. Attribute "profile.category" is set to "advanced".
522
WebComponent DynaMent
11/2008
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. Read more about the following actions: 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.
DynaMents
523
Syntax
11/2008 <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 >
DynaMents
Simple call
<rde-dm:webcomponent mode="include" component="component name" instance="test" />
Parameters
mode
Name of the project containing the Web Component. If nothing is specified: Current project
component
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
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"
11/2008
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)
DynaMents
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: Return code -30520 -30521 -30550 -30551
RedDot LiveServer 9.0
Description Web Component not found Web Component not active Web Module not found Web Module not active Access constraint of a parameter not met Access constraint of the Web Module not met Action not found Parameter set but not defined for Web Component/Module
525
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
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
Error Handling
11/2008
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: Return code -30520 -30521 -30550 -30551 Meaning Web component not found Web Component not active Web module not found Web module not active
Syntax
<rde-dm:webcomponent mode ="remove" instance ="{instance name}" />
Simple Call
<rde-dm:webcomponent mode="remove" instance="instance name" />
527
Parameters
11/2008 mode
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:
DynaMents
Meaning Web component not found Web Component not active Web module not found Web module not active Instance not found
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.
528
11/2008
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}" />
DynaMents
Simple Call
<rde-dm:webcomponent mode="include-css" component="component name" />
Parameters
mode
Name of the project containing the Web Component. If no value is specified: Current project
component
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
11/2008
component between Style and the file extension. Example for specifying a CSS style sheet named cmpTestStyleMy_Variant.css: <rdedm: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>" />
DynaMents
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: Return code -30570 Description CSS content not found
530
WebService DynaMent
11/2008
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. Read more about the following actions: 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.
For each WebService DynaMent there is one child element with the name <rde-rd:soapmessage>, 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 <rderd: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
Syntax
11/2008 <rde-dm:webservice name timeout cache-id attachment-attribute attachment-name-prefix ="{connector name}" ="{timeout in seconds}" ="{cache-id}" ="{attribute name}" ="{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> ...metadata... </rde-rd:import> </rde-dm:webservice >
DynaMents
Parameters
name
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
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)
11/2008
A prefix placed in front of the attachment content IDs to uniquely identify the content IDs in all the various Web services.
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"
DynaMents
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
11/2008
<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)
DynaMents
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. Value if nothing is specified: "embedded"
mime-type (optional)
The specification of a MIME type that is used by the recipient to process the file that was received. Value if nothing is specified: If type="embedded": "text/plain"
RedDot LiveServer 9.0
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
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":
11/2008
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.
DynaMents 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). <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.
Result
RedDot LiveServer 9.0
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
Error Handling
11/2008
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: Return code -25320 -25321 -25326 -25327 -25328 -25330 -25331 -25332 -25333 -25520 -25521 -25522 -25523 -25524 -25525 -25599 25400 Description One or more connector exceptions have occurred. Cannot initialize the desired Web service. Not all of the call's required parameters have been specified. A valid envelope does not exist in the connector with the specified name 'prepared-envelope'. Connection has timed out. Missing <rde-rd:soap-message> element. Parameter type information missing in the <rde-rd:soapmessage> element Parameter operation information missing in the <rde-rd:soapmessage> element Parameter prep-envelope information missing in the <rderd:soap-message> element This encoding is not supported. Preparation of the attachment has failed (see the log file for details). The server called did not return an envelope. Result parameters could not be read. (could not be found/ identified, etc.) Could not identify a result parameter in the returned envelope. The returned envelope contains a fault element. Points to a server-side error while processing the request. The necessary license is missing. The connector is not active.
DynaMents
For more information on using XPath expressions, see the separate sections. See also:
RedDot LiveServer 9.0
Using the Results (Page 19) XPath Statements in Parameters (Page 26)
536
11/2008
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).
537
11/2008
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> </rde-dm:webservice>
DynaMents
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"/> </rde-rd:soap-message> </rde-dm:webservice>
538
11/2008
DynaMents
539
11/2008
Sending attachments that have been received via the WebService DynaMent:
<!-- Receiving attachments --> <rde-dm:webservice name="DemoService" attachmentattribute="attachments" attachment-name-prefix="att_" reporttag="report"> <rde-rd:soap-message prepared-envelope="getAttachments" type="prepared"/> </rde-dm:webservice> <!-- Sending attachments --> <rde-dm:webservice name="DemoService" timeout="120" reporttag="report"> <rde-rd:soap-message prepared-envelope="sendAttachments" type="prepared"/> </rde-dm:webservice> <!-- Counting number of received attachments --> <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>
DynaMents
540
Sample call:
<rde-dm:webservice name="DemoService" attachment-attribute="attachments" attachment-name-prefix="att_" report-tag="report"> [...] </rde-dm:webservice> <!-- Counting attachments --> <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"/> <!-- Including content --> <rde-dm:include content="[#context:attachment#]"/> <!-- Generating link to content --> <rde-dm:reference content="[#context:attachment#]" scope="session" mode="setscope"/> <!-- Counting headers of an attachment --> <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> 11/2008 DynaMents
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 -Content-Type -LSContentType -att_CID234233234 -Content-Type -LSContentType
: : : : : :
<name of content item in object cache> text/xml XML <name of content item in object cache> text/xml 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>#]"/> RedDot LiveServer 9.0
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
11/2008
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#]"/>
DynaMents
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
Wrapper DynaMent
11/2008
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
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
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> DynaMents
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
<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>
11/2008
DynaMents
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
DynaMents
11/2008
546
11/2008
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)
DynaMents
547
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
DynaMents
"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)
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
11/2008
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.
DynaMents
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
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 valuefor 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://"
DynaMents
11/2008
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
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.
DynaMents
11/2008
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
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 ServletContainer, 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.
DynaMents
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
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.
DynaMents
11/2008
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
11/2008
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.
DynaMents
554
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.
DynaMents
11/2008
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.
555
11/2008
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").
DynaMents
lastEditor: Name of the user who last edited the content. lastEditTime: Time the content was last changed, measured in milliseconds since 197001-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 197001-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
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.
DynaMents
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
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.
DynaMents
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.
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
11/2008
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".
DynaMents
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
11/2008
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.
DynaMents
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)
560
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").
11/2008
DynaMents
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 ServletContainer, 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
RedDot LiveServer 9.0
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
11/2008
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/# DynaMents
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
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>
DynaMents
11/2008
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
See also:
11/2008
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)
Inline functions
DynaMents PSX
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.
RedDot LiveServer 9.0
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
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/#
DynaMents
11/2008
#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/#/#RDEREQUEST: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
#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//#
DynaMents
11/2008
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
See also:
11/2008
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)
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
<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)
DynaMents
568
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)
DynaMents
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). Whitespace 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
11/2008
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.
DynaMents
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
11/2008
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": quotedprintable encoding. Example:
DynaMents <rde-dm:attribute mode="write" attribute="subject" source="request" value="test"/> <rde-rd:subject>[#request:subject#defaultSubject#].encodeMailHeader(UTF-8, Q)</rde-rd:subject>
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.
RedDot LiveServer 9.0
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
11/2008
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.
DynaMents
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. Return The displayed date or an empty string.
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. Return The displayed date or an empty string.
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. Return The displayed date or an empty string.
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. Return The number of milliseconds since January 1, 1970, in string format or as an empty string.
572
11/2008
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. Return The number of milliseconds since January 1, 1970, in string format or as an empty string.
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.
DynaMents
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. Return The processed value including replacements.
replacePlaceholders(java.lang.String value) Replaces all specified placeholders from RedDot LiveServer by its values and returns the results in the edited value. Return The processed value including replacements.
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
11/2008
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.
DynaMents
toArray() Splits the value to be evaluated into substrings at each semicolon, and removes all whitespace 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.
RedDot LiveServer 9.0
574
11/2008
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.
DynaMents
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.
RedDot LiveServer 9.0
See also: Inline Functions for Parameter Values (Page 29) Inline Function: Integrating Your Own Classes (Page 30)
575
11/2008
Index
A
application integration Iolet DynaMent ............................. 188 Portal DynaMent .......................... 252 Portlet DynaMent ......................... 259 attachments Message DynaMent ...................... 235 WebService DynaMent ................. 531 Attribute DynaMent attributes copying ..................................... 80 moving ..................................... 83 renaming .................................. 78 data checking ................................... 61 deleting .................................... 88 reading ..................................... 40 reading multivalued .................. 69 referencing ............................... 75 saving ....................................... 93 writing ...................................... 49 general ........................................... 40 in XSL files ..................................... 95 modes condition .................................. 61 copy ......................................... 80 delete ....................................... 88 flush ......................................... 93 flushcookies ............................. 91 for-each .................................... 69 move ........................................ 83 read .......................................... 40 reference .................................. 75 remove ..................................... 86 rename ..................................... 78 write ......................................... 49 xslparam .................................. 95 values deleting from value list ............. 86 writing cookies ............................... 91 attribute placeholders ....................... 564 attributes (continued) reading .......................................... 40 multivalued .............................. 69 subattributes ............................ 69 referencing .................................... 75 renaming ....................................... 78 source ........................................... 22 values deleting from value list ............. 86 writing ........................................... 49 explicitly .................................. 93 to cookies ................................ 91
B
break Process DynaMent ....................... 267
C
Cache DynaMent content removing from cache .............. 107 general .......................................... 97 modes add-dependency .................... 103 notify ...................................... 107 set-id ...................................... 100 set-scope ................................. 97 cache entries dependencies .............................. 103 removing ..................................... 107 renaming ..................................... 100 validity ........................................... 97 cachingtime standard parameter ....................... 31 categories in repositories ...................... 391, 393 charts Reporting DynaMent .................... 334 check result recording ..................................... 120 child elements Content DynaMent ....................... 110 Iolet DynaMent ............................ 188 Message DynaMent ..................... 235 MetaData DynaMent .................... 243 Script DynaMent .......................... 402 576
DynaMents
attributes checking constraints ...................... 61 copying .......................................... 80 deleting ......................................... 88 in XSL ............................................. 95 moving ........................................... 83 placeholders ................................ 561
Index
11/2008
child elements (continued) Target DynaMent .......................... 461 User DynaMent ............................. 514 CMS DynaMents ..................................... 17 constraints Attribute DynaMent ........................ 61 importing ..................................... 141 Target DynaMent .......................... 461 content as source ....................................... 22 attributes importing ................................ 141 Cache DynaMent ............................ 97 checking ...................................... 120 checking into repository ............... 382 checking out from repository ........ 387 constraints importing ................................ 141 Content DynaMent general ................................... 110 creating in repository ................... 357 deleting in repository ................... 378 delivering metadata ..................... 243 general ........................................... 38 Import DynaMent ......................... 140 Include DynaMent ........................ 160 inserting ...................................... 160 MetaData DynaMent ..................... 243 preset attributes .......................... 555 Process DynaMent ....................... 264 reading from the repository .......... 342 Reference DynaMent .................... 301 removing locks ............................. 389 updating in repository .................. 368 WebComponent DynaMent ........... 523 content attributes importing ..................................... 141 inline notation ............................... 20 content classes in repositories ...................... 391, 393 Content DynaMent content deleting .................................. 126 importing ................................ 110 removing data ........................ 127 removing from cache .............. 129 general ......................................... 110 modes delete ..................................... 126 import .................................... 110
Content DynaMent (continued) modes (continued) notify-cache ........................... 129 remove-data ........................... 127 validate .................................. 120 content import Import DynaMent ......................... 141 content versions including ..................................... 180 context as source ....................................... 22 continue Process DynaMent ....................... 269 cookies as source ....................................... 22 Attribute DynaMent ........................ 91 deleting ......................................... 49 linking ........................................... 49 writing ..................................... 49, 91 CPS DynaMent general ........................................ 131 modes ID ........................................... 131 cps.log.categories ............................. 560 cps.log.level ...................................... 560 cpssessionid ..................................... 548
DynaMents
D
database RDB DynaMent ............. 289, 293, 295 delete lists importing ..................................... 154 diagrams Reporting DynaMent .................... 334 DynaMents definition ....................................... 15 general .......................................... 14 processing ..................................... 17 structure ........................................ 16 syntax ............................................ 16 tasks ............................................. 38
E
editing general .......................................... 38 RedDot DynaMent ........................ 298 577
Index
11/2008
e-mail Message DynaMent ...................... 235 error handling ...................................... 36 general ........................................... 33 external data sources RDB DynaMent ............................. 289
Import DynaMent (continued) importing ..................................... 150 delete lists ............................. 154 tagging ........................................ 155 Include DynaMent displaying differences .................. 184 general ........................................ 160 including content ......................... 160 including content versions ........... 180 including Weblet modules ........... 177 integrating PSX modules .............. 160 modes diff ......................................... 184 include ................................... 160 include-version ...................... 180 indexes inline notation ............................... 20 inline functions general .......................................... 29 integrating classes ......................... 30 placeholders ................................ 561 reference ..................................... 569 inline notation general .......................................... 20 inline functions ........................ 29, 30 integration CPS DynaMent ............................. 131 general .......................................... 38 Iolet DynaMent ............................ 188 Message DynaMent ..................... 235 Portal DynaMent .......................... 252 RDB DynaMent ............................. 289 Reporting DynaMent .................... 313 Repository DynaMent ................... 341 Script DynaMent .......................... 402 WebService DynaMent ................. 531 integrations Livelink DynaMent ....................... 205 Portlet DynaMent ......................... 259 Tagging DynaMent ....................... 407 Iolet calling .......................................... 188 Iolet DynaMent ............................ 188 Iolet DynaMent general ........................................ 188 querying an Iolet .......................... 188
F
folder entries in repository ................................. 395 folders creating in repository ................... 363 deleting in repository ................... 380 updating in repository .................. 374 formatting rules Attribute DynaMent read .......................................... 40 write ......................................... 49
DynaMents
forward Process DynaMent ....................... 264 full-text search ................................... 270 Query DynaMent .......................... 271 search queries ............................. 287
G
groups as source ....................................... 22
H
handbook conventions ................................... 12 general ........................................... 11 structure ........................................ 12 syntax ............................................ 12
I
ID CPS DynaMent ............................. 131 Image DynaMent general ......................................... 135 images with links ................................ 138 inserting images .......................... 135 with Link DynaMent ...................... 138 Import DynaMent content import ............................. 141 general ......................................... 140
578
Index
L
11/2008
O
objects creating in Livelink ....................... 215 deleting from Livelink .................. 222 reading from Livelink ................... 207
Link DynaMent general ......................................... 195 in Image DynaMent ...................... 138 using with parameters ...................... 198 without parameters ................ 195 Link-Param DynaMent general ......................................... 202 using ............................................ 202 live reports requesting .................................... 316 Livelink DynaMent general ......................................... 205 modes create ..................................... 215 delete ..................................... 222 navigate ................................. 224 read ........................................ 207 xmlsearch ............................... 227
P
page layout general .......................................... 38 Image DynaMent .......................... 135 Link DynaMent ............................. 195 Link-Param DynaMent .................. 202 Wrapper DynaMent ...................... 543 parameters attributes ....................................... 20 CMS placeholders .......................... 20 fixed values ................................... 20 general .......................................... 31 inline notation ............................... 20 source ........................................... 22 XSL .............................................. 567 passwords forcing change ............................. 477 personalization Attribute DynaMent ........................ 40 general .......................................... 38 Query DynaMent .......................... 270 Target DynaMent .......................... 461 User DynaMent ............................ 474 placeholders attributes ....................................... 75 general ........................................ 561 PSX module ................................. 160 syntax .......................................... 564 Weblet modules ........................... 177 Portal DynaMent general ........................................ 252 modes include ................................... 252 remove ................................... 257 session .................................. 255 portalinstance as source ....................................... 22 Portlet DynaMent general ........................................ 259 modes include ................................... 259 maximize ............................... 261 remove ................................... 262 579
DynaMents
M
manual symbols ......................................... 13 Message DynaMent general ......................................... 235 sending e-mail ............................. 235 metadata ........................................... 150 importing ..................................... 150 MetaData DynaMent delivering content data ................ 243 general ......................................... 243 listing versions ............................. 250 modes list-versions ............................ 250 MIME types during import ............................... 531 for import ..................................... 310
N
navigation information from Livelink ................................ 224
Index
Process DynaMent break ........................................... 267 continue ...................................... 269 forward ........................................ 264 general ......................................... 264 redirect ........................................ 265 processing ........................................... 17 process-mode standard parameter ....................... 31 PSX modules Include DynaMent ........................ 160 placeholders ........................ 561, 564
rdeDefaultProjectId ........................... 553 rde-dm import .................................. 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
11/2008
Q
Query DynaMent general ......................................... 270 listing Verity indexes .................... 286 modes list .......................................... 286 search queries creating .................................. 271 entering .................................. 287 searchable parameter .................. 284
DynaMents
R
RDB DynaMent database querying ......................... 289, 295 updating ................................. 293 general ......................................... 289 modes query ...................................... 289 statements ............................. 295 update .................................... 293 rdeAbsolutePrefix .............................. 548 rde-attributes .................................... 558 rdeClientCookies ............................... 553 rdeContentFixedRendering ................. 548 rdeContentProjectId ........................... 548 rdeContextPath .................................. 548
RedDot LiveServer 9.0
rde-id standard parameter ....................... 31 rdeInternalCaller ............................... 548 rdeLocale .......................................... 548 rdeLocaleAttr ..................................... 548 rdePageKey ....................................... 548 rdePathparam ................................... 548 rdePrefix ........................................... 548 rdeProjectID ...................................... 548 RDE-PSX ............................................ 564 rde-rd content-type ................................ 548 dynament-result .......................... 548 httpHeader- ................................. 548 httpHeader-method ..................... 548 idea.masterservlet.currenturl ....... 553 idea.masterservlet.homeurl ......... 553 idea.masterservlet.lasturl ............ 553 idea.masterservlet.repeaturl ........ 553 path-info ...................................... 548 query-string ................................. 548 remote-address ........................... 553 580
rdeContextRoot .................................. 548 rdeCurrentLocale ....................... 548, 553 rdeCurrentProjectId ........................... 548 rdeCurrentXmlId ................................ 548 rdeCurrentXslId .................................. 548
Index
11/2008
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
Reference DynaMent general ........................................ 301 modes read-multipart ........................ 310 set-cache-id ........................... 308 set-scope ..................................... 306 using ........................................... 301 reference lists importing ............................. 150, 154 registry as source ....................................... 22 reporting content data ................................ 243 standard reports .......................... 328 user data ..................................... 514 user properties ............................ 482 Reporting DynaMent diagrams ..................................... 334 general ........................................ 313 modes acknowledge .......................... 314 browser .................................. 313 report ..................................... 316 report-tag standard parameter ....................... 31 Repository DynaMent general ........................................ 341 modes cancel-checkout ..................... 389 checkin .................................. 382 checkout ................................ 387 create ..................................... 357 create-folder ........................... 363 delete ..................................... 378 delete-folder .......................... 380 list .......................................... 395 list-classes ............................. 391 list-classes-folder ................... 393 query ...................................... 348 read ....................................... 342 update ................................... 368 update-folder ......................... 374 requests as source ....................................... 22 predefined attributes ................... 548 response as source ....................................... 22 result-attribute standard parameter ....................... 31 581
DynaMents
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 DynaMent Edit RedDot .................................. 298 modes edit ......................................... 298 template ................................. 299 Template RedDot .......................... 299 redirect Process DynaMent ....................... 265 redundant database structures .......... 461
Index
11/2008
results using .............................................. 19 return codes ........................................ 36 error handling ................................ 36 roles standard parameter ....................... 31 rules Attribute DynaMent read .......................................... 40 write ......................................... 49
source (continued) users attributes ....................... 557, 558 standard parameters ........................... 31 structure DynaMents .................................... 16 symbols .............................................. 13 system as source ....................................... 22 predefined attributes ................... 560
S
Script DynaMent executing scripts .......................... 402 general ......................................... 402 scripts Script DynaMent ........................... 402 search limiting search area ...................... 284 limiting to content groups ............ 287 limiting to content types ............... 287 Query DynaMent .......................... 270 search queries creating .................................. 271 entering .................................. 287 searchable parameter .................. 284 with Query DynaMent ................... 271 with Repository DynaMent ............ 348 search engine indexes listing ........................................... 286 session predefined attributes ................... 553 sessions as source ....................................... 22 SMTP connection Message DynaMent ...................... 235 source attributes ....................................... 22 content attributes ................................ 555 inline notation ............................... 20 meaning ......................................... 22 requests attributes ................................ 548 session attributes ................................ 553 system attributes ................................ 560
T
tagging general ........................................ 408 imports ........................................ 155 Tagging DynaMent general ................................ 407, 408 modes assignTags ............................. 420 ConsolidateData ..................... 447 defineTags ............................. 409 deleteConsolidatedData ......... 459 deleteTags ............................. 415 getAssignedTags .................... 436 getAssignments ...................... 429 getConsolidatedData .............. 453 getTags .................................. 412 getTargets .............................. 440 renameTag ............................. 419 suggestTags ........................... 427 unassignTags ......................... 424 Target DynaMent constraints linking .................................... 461 general ........................................ 461 redundant database structures .... 461 using ........................................... 461 tasks DynaMents .................................... 38 Template Editor DynaMents .................................... 17
DynaMents
U
user behavior User DynaMent ............................ 474 User DynaMent data selected users ........................ 514 582
Index
User DynaMent (continued) general ......................................... 474 modes create ..................................... 499 delete ..................................... 498 exist ....................................... 496 groups .................................... 509 load ........................................ 502 login ....................................... 487 login-trusted ........................... 492 logout ..................................... 493 report ..................................... 514 session ................................... 482 session-check ......................... 485 update .................................... 506 properties current user ............................ 482 using ............................................ 475 users as source ....................................... 22 data checking ................................. 496 creating .................................. 499 deleting .................................. 498 editing .................................... 506 reading ................................... 514 determining logon information ..... 485 loading ........................................ 502 modifying groups .................... 509 logging off (User DynaMent) ......... 493 logging on (User DynaMent) . 487, 492 predefined attributes ................... 557 preset attributes .......................... 558 properties reading ................................... 482
11/2008
W
Web service WebService DynaMent ................. 531 WebComponent DynaMent general ........................................ 523 modes include ................................... 523 include-css ............................. 528 remove ................................... 527 session .................................. 526 Weblet modules including ..................................... 177 placeholders ........................ 561, 564 WebService DynaMent calling a Web service ................... 531 general ........................................ 531 Wrapper DynaMent example ....................................... 544 general ........................................ 543 using ........................................... 543
DynaMents
X
XML content Reference DynaMent .................... 301 Wrapper DynaMent ...................... 543 XPath as source ....................................... 22 Content DynaMent ....................... 110 expressions ................................... 26 inline notation ............................... 20 parameter rde-id ............................ 31 using ....................................... 19, 26 XSL RedDot DynaMent general ................................... 298 XSL parameters predefined ................................... 567 XSL style sheets Image DynaMent .......................... 135 Link DynaMent ............................. 195 Link-Param DynaMent .................. 202 RedDot DynaMent ........................ 298
V
validation .......................................... 120 validation rules Attribute DynaMent read .......................................... 40 write ......................................... 49 Verity indexes listing ........................................... 286
RedDot LiveServer 9.0
Verity search engine entering search queries ................ 287 Query DynaMent .......................... 271 versions including ...................................... 180
583