Command reference for Portal Scripting Interface

 

+
Search Tips   |   Advanced Search

 

  1. Introduction
  2. $Content
  3. $Layout
  4. $Portlet
  5. $Look
  6. $Access
  7. $Portal
  8. Authentication
  9. Examples
  10. Troubleshooting
  11. Property File Format
  12. Index paths

 

Introduction

The Portal Scripting Interface (wpscript) provides a scripting interface to portal administration functionality

Unlike xmlaccess , the portal is accessed with distinct user identities, not as a generic "super administrator".

The portal scripting component is an extension to the wsadmin tool of the WebSphere Application Server. Therefore, the scripting language is JACL, a version of TCL. JACL is an interpreted language without strong typing. It is a procedural language with some object oriented concepts that are used by the scripting component. This section provides a basic overview of JACL so that you will understand the examples used in this procedure.

  • The character # starts a comment that extends to the end of the line.

  • By default, each line is interpreted as one statement.

  • We can write multiple statements on one line by separating the statements with semicolons.

  • Statements can be nested by using brackets [], which are interpreted like backquotes in most UNIX shells: the statement within is executed, and its result substituted in place of the bracketed statement before interpreting the surrounding statement.

  • JACL is case-sensitive.

Example:

### Here is a comment single statement with arguments first statement in line ; second statement outer statement [first inner] [second inner statement]

The value of a JACL variable is accessed by placing a dollar sign ($) in front of the variable name.

A variable can contain an object.

A method of an object is invoked by using the object as the first part of a statement, followed by the method name, followed by any arguments that should be passed to the method.

Since there is no strong typing, a method can only be overloaded by varying the number of arguments.

Example:

### Variable 'Object' holds the object to invoke ### 
### Invoke the double argument version of the method 
$Object method arg1 arg2


### And now the single argument version 
$Object method arg 

### There may be a version with three arguments 
$Object method arg1 arg2 arg3


### Invoke the single argument version ### 
### The single argument is provided as a nested statement ### 
### The nested statement invokes the double argument version 
$Object method [$Object method argInner1 argInner2]

 

Script Beans

Scripting beans are objects with methods that work on the portal data.

Portal objects are not represented by JACL objects. There is no JACL object that represents a particular page or an individual portlet. Rather, there is a fixed number of Script Beans that provide access to specific areas of the portal data. Each bean has a name, which is also the name of the global JACL variable that stores it.

The available beans are:

Most method names are single English words, such as get or search or parent. All method names must be written in lowercase. Each bean has a help method. If invoked with a method name, it prints help for that method in the bean. If invoked without an argument, it prints general help for that bean, including a list of method names and other help topics. The general help message of the Portal bean includes an overview of the available beans and their responsibilities.

Example:

### get help - for the completely lost $Portal help 
### get help on a particular bean $Portlet help $Access help 
### get help on a method of a bean $Portal help login $Layout help select 
### get help on an extended help topic of a bean $Content help search-criteria 

 

Portal Objects

Most portal objects are represented in the script by an object identifier string which is based on the object ID in the portal. For example:

_6_00KJL57F9D02H456_A

These IDs are expected by methods as arguments and returned as results. Since an ID never contains whitespaces or characters that would be misinterpreted by JACL, it is a convenient handle for a portal object. If a method returns several objects, the IDs are separated by whitespaces. The result can then be used directly as a JACL list.

Unlike with the GUI, where geometric arrangement and a locale specific title provide information about an object, the IDs used in the script are unintelligible to the user. Most of the script beans therefore provide a details method that prints information about an object. The details method of a bean will only work for the objects handled by that bean. For example, the Content bean cannot provide details about IDs returned by the Layout bean.

Example:

### 'search' returns a list of objects foreach child [$Content search all] {
  # details get printed, they are not returned as a result   $Content details $child }

The scripting component tries to generate a "common name" for the portal objects. The common name is based on a global unique name, an object name, or a title assigned to the object. The common name never contains whitespace, special characters, or characters outside of the US-ASCII range. Hence, it can be displayed even in a terminal window that does not support national character sets. If suitable input data is available, the generated common name may provide an indication of what an object represents.

 

Tree Navigation

The Content, Layout, and Portlet beans each represent a tree hierarchy. The basic navigation methods are the same for all three. A tree bean provides methods to access the root node, to look up the parent and children of a node, and to maintain a cursor which points to a selected node in the tree. The code examples in this section use the Content bean, but the same operations can be performed on the other tree beans as well.

The command root returns the ID of the root node, as a fixed starting point for navigation. $Content root

We can select a node by its ID using the select command. We can deselect the current selection using deselect or using select without an argument. We can return the ID of the selected node using the current command. For interactive use, csn is an alias for current.

Example:

$Content select <id>
$Content deselect $Content current $Content csn 
### example: select the root node $Content select [$Content root]

### example: what is selected?
$Content current 
### example: deselect $Content deselect 

The path command returns a list of all IDs from the root to the currently selected node. The children of the selected node are returned in the same fashion by the children command. The ID of the parent of the selected node can be obtained by using parent.

Example:

$Content path $Content parent $Content children 
### example: select a node and print its children $Content select <some_node_id>
foreach child [$Content children] { puts "$child" }

The commands path, parent, and children can also be used with an explicit ID instead of implicitly referring to the currently selected node.

Example:

$Content path <id>
$Content parent <id>
$Content children <id>

For simplicity, there are dedicated select commands for the root node and for the parent of the currently selected node. In the following example, the first argument is a dummy, to distinguish the method from the select with an ID argument. It will not be interpreted. The second argument is a keyword, which is case insensitive. Alternative, shorter keywords are documented in the bean help.

Example:

$Content select the root $Content select the parent 

 

Search

All beans with tree navigation support identical commands for searching, but the available search criteria are different for each bean. As before, the Content bean is used in the generic examples.

Searches in trees are scoped. The search scope is the subtree below the selected node, including the selected node itself. If nothing is selected, the search scope is the full tree starting at the root.

There are two different commands for searching: search will return a list of matches, whereas find only succeeds if there is a single, unique match for the search. It fails if there is more than one match, or no match at all. It can be used in cases where a script should terminate if the search result is not a unique match. If the keyword select is passed to find, the search result becomes the selected node.

Example:

$Content search <type>
$Content search <type> <by> <value>

$Content find <type>
$Content find <type> <by> <value>

$Content find <type> select $Content find <type> <by> <value> select 

The first argument for all searches is the type of the nodes to look for. The type is specified by a keyword, which is case insensitive. The available types and corresponding keywords depend on the bean. In all beans, the keywords all and any can be used to search regardless of the type. There is a dedicated help topic for the search types.

Example:

### example: return all nodes in the search scope
$Content search all 
### example: get help on the available <type> keywords $Content help search-types 

The type selection can be combined with an additional search criteria, which is specified by a keyword (<by>) and a value to match against (<value>). The available search criteria and corresponding keywords depend on the bean. There is a dedicated help topic for the search criteria.

Example:

### example: get help on the available <by> keywords $Content help search-criteria 

The following are common search criteria. Alternative, shorter keywords are described in the help text on search criteria of the respective bean.

Value Description
id The value is an ID, the search is for the object with that ID.
uniquename The value is a string, the search is for the object with the string as its unique name.
commonnamehas The value is a string, the search is a for objects with the string as a substring in their common name. Comparison is case insensitive.
commonnameis The value is a string, the search is for objects with the string as their common name. Comparison is case sensitive.

Example:

### example: find and select by unique name
$Content find any uniquename "ibm.portal.Portlets" select 

 

Attributes

All beans use similar commands to query and modify attributes. Attributes are identified by a name, such as "uniquename", "title", or "markup". There are different commands for the different types of attributes. Similar to the details command in Portal objects, the commands must be invoked on the bean responsible for the object type. For example, attributes of content nodes can only be accessed through the Content bean, not through the Layout or any other bean.

The set of attributes supported for an object depends on the type of the object. Many attributes are read-only. Attribute values are always represented as strings in the scripting language. They are mapped from and to portal data types by the respective script bean. Exceptions will be triggered if the mapping fails.

 

Plain attributes

Plain attributes have a single value that can be queried using the get command. The object for which to query the attribute is specified by an ID, the attribute by name. If the attribute is not read-only, the value can be set using the set command, which expects the new value as the last argument. If the bean supports a current selection, the ID can be omitted for both commands to refer to the selected object.

Example:

$Content get <id> <attr>
$Content set <id> <attr> <value>

### only for beans with a current selection $Content get <attr>
$Content set <attr> <value>

### example: get unique name of a content node $Content get <id> uniquename 
### example: get type of the selected content node $Content get type 
### example: set theme of a content node set themeid [$Look find theme commonameis "Science"]
$Content set <id> theme $themeid 

The following are standard attribute names available for all objects. Names for additional attributes of individual portal object types are documented with the respective bean. Alternative or shorter names are documented in the bean help.

Value Description
id The identifier of the object.
type The type of the object.
uniquename The unique name of the object, if one is assigned.
commonname The common name of the object, if one could be generated.

 

List valued attributes

List valued attributes can have multiple values. They can be queried using the list command, which will return all values, separated by whitespace. The object for which to query the attribute is specified by an ID, the attribute by name. If the bean supports a current selection, the id can be omitted to refer to the selected object.

List valued attributes can be modified by adding or removing a particular value, or by removing all values from the list. The respective commands are add, drop, and empty. With all commands, the object is specified by ID and the attribute by name. The add and drop commands also require the value to be added or removed.

These commands are appropriate as long as the values do not contain whitespace and the order of the elements is not important. Currently, all list valued attributes satisfy these restrictions.

Not all list valued attributes can be modified by all of these commands. For example, some lists may not be empty, in which case the empty command is not available. However, if an operation is supported for an attribute, the operation uses the command as described here. List valued attributes may also change as a side effect of other operations. For example, if a title is set for a previously undefined locale, the new locale will show up in the list of locales. See Local specific attributes for details on titles and locales.

Example:

$Content list <id> <attr>
$Content add <id> <list> <value>
$Content drop <id> <list> <value>
$Content empty <id> <list>

### only for beans with a current selection $Content list <attr>
$Content add <list> <value>
$Content drop <list> <value>
$Content empty <list>

### example: add a new markup for the selected node $Content add markup wml 
### example: drop the american locale for the given node $Content drop <some_node_id> locale en_US

### example: drop all locales for the given node $Content empty <some_node_id> locale 

 

Locale specific attributes

Locale-specific attributes have different values for different languages and countries. They can be queried using the nlsget command, where nls stands for National Language Support. The object for which to query the attribute is specified by an ID, the attribute by name. If the bean supports a current selection, the ID can be omitted to refer to the selected object. The usual locale-specific attributes are:

  • title
  • description
  • shorttitle
  • keywords

For the Content bean, only the locale-specific attributes title and description exist. For the Portlet bean, all four of the attributes exist.

The language and country is given as a so-called locale, which consists of a language identifier, an optional country identifier, and an optional variant. Language and country are specified by standard two letter abbreviations, the language in lower case and the country in upper case. The components are separated by underscore characters. Here are some example locales:

en General English
en_US American English
de_CH Swiss German
pt_BR Brasilian Portuguese

The list valued attribute named "locales" holds all locales for which a locale specific attribute may be defined. However, all locale specific attributes are optional for all locales. There is no fallback algorithm that would, for example, return the general portuguese value if the brasilian portuguese value is not set. Such fallback algorithms are used when pages are assembled by the portal, but not for the administrative access provided by the portal scripting component.

Locale specific attributes that are not read-only can be set using the nlsset command. On top of the arguments for the nlsget command, it expects the new value of the attribute as the last argument. By setting an attribute for a locale that was not used before, the new locale is added to the list valued attribute "locales" mentioned above.

Example:

$Content nlsget <id> <attr> <locale>
$Content nlsset <id> <attr> <locale> <value>

$Content nlsget <attr> <locale>
$Content nlsset <attr> <locale> <value>

### example: get american title of a specific content node $Content nlsget <some_node_id> title en_US

### example: set german description of current selection $Content nlsset description de_DE "Kurze Beschreibung"

### example: set general english title of a specific node $Content nlsset <some_node_id> title en "English Title"

Since locale-specific attributes are often translated independently from script development, the nlsimport command can be used to read a separate property file that defines attribute values for a set of locales. The property file format is explained in detail in Appendix A. By specifying an appropriate prefix, it is possible to load values from the same property files that are used by the XMLAccess tool.

Example:

$Content nlsimport <id> <filename>
$Content nlsimport <id> <filename> <prefix>

To delete all locale-specific attributes before importing a set of values, empty the list valued attribute "locales" as described in List valued attributes.

 

Organization

For some beans, in particular the Content and Layout beans, the order of nodes is significant. In tree beans, the parent relationship of the nodes defines the hierarchy. Only nodes with the same parent node are in a particular order in trees. The Layout bean is used in the generic examples.

 

Sequence

The move command can be used to reorder nodes. The order of nodes is tracked as a non-negative integer position assigned to each node, with the first node at position 0. For tree beans, the positions compare only among the children of a common parent node. The position can be queried as a read-only plain attribute

The order of nodes is changed by the move command. It is used on a single node to assign an absolute position or to displace by a given distance. The positions of the other affected nodes are updated automatically. In both cases, the new position of the node will always remain within bounds. The position or displacement argument will be adjusted accordingly by the bean.

The move command expects the ID of the node to be moved, a keyword indicating whether the change is absolute or relative, and the new position or distance. If the bean supports a current selection, the ID can be omitted to move the selected object.

Example:

$Layout move <id> to <position>
$Layout move <id> by <distance>

### only for beans with a current selection $Layout move to <position>
$Layout move by <distance>

### example: move selected node to the top position $Layout move to 0

### example: move given node one down in the list ### if it already is the last node, do nothing $Layout move <some_node_id> by 1

### example: move selected node 4 up in the list ### if it is at position 0 to 4, it becomes the new head $Layout move by -4

### example: move given node to the last position ### negative absolute positions are interpreted as max int $Layout move <some_node_id> to -1

 

Hierarchy

In some tree beans, it is possible to change the parent of a node in the tree, thereby moving the whole subtree below that node to another part of the tree. This is achieved by the commands transfer or adopt. With transfer, the ID of the node and new parent are specified explicitly, while adopt uses the selected layout mode as the new parent. To improve readability and avoid confusion about the interpretation of the two IDs, the arguments of the transfer command are separated by the keyword "to".

Example:

$Content transfer <child_id> to <parent_id>
$Layout transfer <child_id> to <parent_id>
$Layout adopt <child_id>

### example: move a layout node below the root component of the page $Layout select the root $Layout adopt <some_node_id>

 

$Content

The content hierarchy is a tree of content nodes, which can be...

  • labels
  • compositions
  • links

Compositions are also called pages.

Links can be internal or external. In the GUI, links represent the nodes in the "Favorites" list. Internal links point to a portal page, external links can point to any URL.

The content hierarchy is accessed and modified by means of the $Content bean, which offers the following methods...

 

Navigation

The Content bean is a tree bean. The navigation is documented in Tree navigation.

 

Search

The generic search syntax is documented in Search. The Content bean supports the default search criteria, and the following keywords for node types in searches. Alternative, shorter keywords are documented in the bean help.

  • label
  • composition or page
  • internalurl
  • externalurl
  • url (either internal or external)
  • all or any

Example:

$Content help search-types 
### example: search all content nodes $Content search all 
### example: find and select page by unique name
$Content find page uniquename "ibm.portal.Portlets" select 
### example: find all pages under label "Administration"
$Content find label uniquename ibm.portal.Administration select $Content search composition 

 

Plain attributes

In addition to the default attributes, content nodes have the following attributes:

Attribute Description
position The numeric position among the siblings, 0-based.
themeid The identifier of the theme for the content node.
themename The name of the theme for the content node.
allportlets A flag that indicates whether all portlets are allowed for this page or not. If this flag is set true, the list of allowed portlets is ignored. (Refer to List valued attributes.)

The themeid attribute is writable. The themename attribute is not writable, but the value depends on the themeid attribute. The position attribute is not writable either, but the value depends on the organization of the content tree.

 

List valued attributes

The content nodes have three list valued attributes, locales, markups, and allowedportlets. See the bean help for alternative, shorter names for these lists.

The locales list holds the locales for which locale-specific attributes are defined.

The commands list, drop, and empty are available for locales. New values can be added by setting a title for the respective locales.

The markups list holds the markups supported by the content node. The commands list, add, and drop are available for markups. At least one markup has to be supported.

The allowedportlets list holds the portlets that are registered as allowed portlets for that page. The total list of portlets that can be used for this page is this list, plus the lists of allowed portlets of all parent pages.

Example:

### example for manipulating locales of a content node:
### select node, list locales, remove and recreate a locale ### "locale" is an alternative name for the "locales" list $Content select <id>
$Content list locales $Content drop locale en $Content nlsset title en "New English Title"

### example for manipulating markups of a content node:
### select node, list markups, replace wml by chtml ### "markup" is an alternative name for the "markups" list $Content select <id>
$Content list markups $Content add markup chtml $Content drop markup wml $Content list allowedportlets 

 

Locale specific attributes

The content nodes have two locale specific attributes, title and description. See the bean help for alternative, shorter names for these attributes. The title has to be defined for each locale, though it can be set to the empty string. A new locale is defined by setting the title for it.

Example:

### example for manipulating locales of a content node:
### select node, remove all, import, add one manually $Content select <id>
$Content empty locales $Content nlsimport nls/content.nls page.visualization $Content nlsset title en_GB "Visualisation"
$Content nlsset description en_GB "A page for..."

 

URL attributes

For a URL content node, the urlget command obtains the URLs. It requires the markup name as an argument. If an ID is given, the requested URL of that content URL node is returned. If the ID is omitted, the requested URL of the currently selected URL node is returned.

Example:

$Content urlget <markup>
$Content urlget <id> <markup>

### example: get WML URL of a specific content URL node $Content urlget <some_url_node_id> wml 

 

Metadata attributes

Content nodes can own metadata, which are name/value pairs of data that are associated with the content node. Metadata are used by the portal itself (for example, to set display attributes), or by the user. However, the user has to take care that none of the metadata information that is set by the portal is overridden.

Example:

$Content parmget <id> <name>
$Content parmset <id> <name> <value>
$Content drop <id> parm <name>
$Content list <id> parms <name>
 
### only for beans with a current selection $Content parmget <name>
$Content parmset <name> <value>
$Content drop parm <name>
$Content list parms <name>
 
### example: set the metadata for an instance property named # "MyUserData" on the selected node 
$Content parmset MyUserData A_User_Value 
 
### example: get the metadata for an instance property named # "MyUserData" (should return "A_User_Value") 
puts "[$Content parmget MyUserData]" 
 
### example: list all metadata names 
foreach pname [$Content list parms] { 
  puts "$pname"  
} 
 
#example: Drop the metadata with the name "MyUserData" 
$Content drop parm "MyUserData" 

 

Organization

The sequence of nodes can be modified as described in Sequence. It is currently not possible to reorganize the content hierarchy.

 

Life Cycle

The create command creates a new content node. The derive command creates a new content node for a page that is derived from another page. The delete command removes a content node.

When creating a new content node, the parent for the new node has to be selected. The first argument for creating is the type of the new node. Supported types are label, page, and externalurl. See the bean help for alternative and shorter names. It is currently not possible to create a node of type internalurl from a script. The second argument is a name for the new node. It will be set as the provisional English title, and the common name of the new node is computed from it. The last argument is one markup that will be supported by this nodes. Additional markups can be enabled by manipulating the list of markups.

The create command returns the ID of the newly created node. If the keyword select is appended to the command, the created node becomes the current selection.

Optionally, the script can specify a shared-flag, which indicates if the new page is a shared page (shared) or a non-shared page(nonshared). The optional flag private-flag indicates if the new page is private or public (possible values are private and public). This flag is only valid if a the content node type is page.

When you derive a page, the parent for the new page in the content tree has to be selected. Only pages that are flagged as shared and public can be used as base pages for derivation. The first argument is the name of the new page. The type of the node is implicit, since only pages can be derived. The second argument is the keyword from, the third is the identifier of the page to derive from. The supported markups are the same as for the base page. The derive command returns the ID of the newly created node. If the keyword select is appended to the command, the created node becomes the current selection.

Do not rely on the name being set as the English title, since this behavior might change in the future. Set the English title explicitly if the locale "en" is to be supported. However, the common name will be computed from the name argument.

Example:

$Content create <type> <name> <markup>
$Content create <type> <name> <markup> select $Content create <type> <name> <markup> [<shared-flag>] [<private-flag>] 
select 
$Content derive <name> from <id>
$Content derive <name> from <id> select 
### example: create and select a label at the top level,
###          then create a derived page below the new label $Content select the root $Content create label "Leisure" html select $Content derive "Movies" from <some_node_id>

The command delete removes a content node that has no children. Nodes that have children cannot be deleted. To reduce the risk of accidental deletion, this command always requires the ID as an argument, even if the node to be deleted is selected.

When deleting a page, all pages derived from that page will also be deleted. This also affects other users that have pages derived from that base page. If the currently selected node is deleted, either directly or by deleting a base page, the bean deselects.

Example:

$Content delete <id>

 

$Layout

The component hierarchy is a tree of components on a page. Components can be containers and controls. A container holds other components, a control displays a portlet.

The component hierarchy is accessed and modified by means of the $Layout bean.

Only pages have a component hierarchy. $Layout always refers to the page that is currently selected in the Content bean.

When the Content bean has no current selection, or the current selection is not a page, the Layout bean cannot be used. Whenever a node is selected in the Content bean, the current selection of the Layout bean is deselected.

In the GUI, the component hierarchy of a page is manipulated by the customizer. The operations of the Layout bean allows for the definition of component hierarchies that can not be handled by the customizer. Care has to be taken by the script developer if the customizer is to be used alongside scripting.

The Layout bean offers the following methods:

 

Navigation

The Layout bean is a tree bean. The navigation is documented in Portal objects.

In addition, the Layout bean provides the index command to obtain and resolve so-called index paths.

When invoked with an ID as argument, the command returns the absolute index path for that component. When invoked without an argument, it returns the absolute index path for the currently selected component.

When invoked with an index path and a keyword, the index command resolves the argument path. If the keyword is find, it returns the ID of the addressed component. If the keyword is select, it also selects it. The keyword is case insensitive. If the index path is not absolute, it will be resolved relative to the selected component.

Example:

$Layout index $Layout index <id>

$Layout index <ipath> find $Layout index <ipath> select 
### example: resolve an absolute index path $Layout index /1/0/3 find 
### example: select first child of current container $Layout index 0 select 

 

Search

The generic search syntax is documented in Search. The Layout bean supports the following keywords for node types in searches. Alternative, shorter keywords are documented in the bean help.

  • container
  • control
  • all or any

In addition to the default search criteria, the Layout bean supports the following criteria. Alternative, shorter names are documented in the bean help.

 

Plain attributes

In addition to the default attributes, components have the following attributes. Alternative, shorter names are documented in the bean help.

Attribute Description
position The numeric position among the siblings, 0-based.
skinid The identifier of the skin for the component.
skinname The name of the skin for the component.
modifiable A flag indicating whether the component can be modified.
deletable A flag indicating whether the component can be deleted.
width The width of the component, in pixel or percent.

The skinid, modifiable, deletable, and width attributes are writable. The boolean value of the flag attributes can be given as true/false, t/f, 1/0, or on/off. It is returned as true/false by the get command. The flag values are local values of the component. On derived pages, a component is modifiable or deletable only if the flag is also set on all base pages where that component is defined. The value of the width attribute can be given as a number of pixels, or as a numeric percentage followed by the percent sign.

The skinname attribute is not writable, but the value depends on the skinid attribute. The position attribute is not writable either, but the value depends on the organization of the component tree.

Example:

### examples for setting attributes of the selected node $Layout set modifiable true $Layout set deletable 0
$Layout set width "350"

Containers have the following additional attribute:

Attribute Description
orientation The orientation of the container.

The orientation attribute is writable. The value is returned as "horizontal" or "vertical". It can be set as horizontal/vertical or as row/column or as row/col.

Controls have the following additional attributes:

Attribute Description
portletdefinition The ID of the portlet shown in the control.
portletentity The IDid of the portlet entity shown in the control.

These attributes are not writable.

 

Global flags

A composition hierarchy has several global flags. These are similar to attributes of the content page node, except that they are associated with the composition hierarchy rather than the content node. In consequence, they have to be accessed through the Layout bean after selecting the page in the Content bean.

The global flags can be queried with the getflag and modified with the setflag command. The getflag command expects the name of the flag as the first argument. If the keyword numeric is added, it returns the value of the flag as a boolean 1 or 0. Without the keyword, it returns a string "true" or "false", respectively. The setflag command expects the name of the flag as the first argument, the new value as the second. The new value can be specified as any boolean value recognized by the BSF, like 1/0, true/false, t/f, on/off.

Example:

$Layout getflag <flag>
$Layout getflag <flag> numeric 
$Layout setflag <flag> <value>

### query a flag in a condition if [$Layout getflag active numeric] then {...} else {...}

The following global flags are supported. The bean help documents alternative and shorter names.

Attribute Description
active, a Whether the page is active.
bookmarkable, bookmark, b Whether an internal link to this page can be created.
shareable, share, s Whether this page can be used as a base for derived pages.

A page is not shown in the navigation if the active flag is false. Pages can be inactivated temporarily while they are modified, to prevent user from seeing an inconsistent view of the page. The bookmarkable flag is not writable.

 

Organization

The component hierarchy can be modified as described in Sequence and Hierarchy.

 

Life Cycle

The create command creates a new component. The parent container for the new component has to be selected. The first argument is a keyword indicating whether a container or control is to be created. Alternative, shorter keywords are documented in the bean help. The interpretation of the second argument depends on the type of object to create. When creating a container, it is the initial value for the orientation attribute. When creating a control, it is the value for the portletdefinition attribute. See Plain Attributes for both attributes. If the keyword select is appended, the newly created node becomes the current selection.

A page that has just been created, or from which all components have been deleted, does not have a root container. Only in that case, it is possible to create a container without selecting a parent. The new container becomes the root container for the page. It is not possible to create a page with a root control.

Example:

$Layout create container <orientation>
$Layout create container <orientation> select 
$Layout create control <portlet_id>
$Layout create control <portlet_id> select 
### example: append a column to the second row $Layout index /1 select $Layout create container column 
### example: create a new control in the first row or column $Layout index /0 select $Layout create control <some_portlet_id>

### example: create a page with a control in a row $Content create page "New Page" html select ### no deselect required, since nothing can be selected $Layout create container row select $Layout create control <some_portlet_id>

The delete command expects as the only argument the ID of the node to be deleted. To reduce the risk of accidental deletion, the id must be specified explicitly even if the node is selected. A container can only be deleted if it is empty. If the selected node is deleted, the bean automatically deselects.

Example:

$Layout delete <id>

 

$Portlet

The portlet repository provides access to portlets, portlet applications, and web modules. To provide easy access to the relations between the repository objects, the repository is modeled as a tree. Unlike with the content and component hierarchies, the repository tree is not arbitrarily nested.

At the root of the repository is a dummy node. Children of the root are the web modules. Web modules are the deployment units of the portal, they correspond to WAR files. The children of a web module are portlet applications.

The portlet repository is accessed by means of the Portlet bean, referenced as $Portlet in JACL. Modification of the portlet repository from a script is currently not supported.

The Portlet bean provides the following methods:

 

Navigation

The Portlet bean is a tree bean. The navigation is documented in Tree Navigation.

There is one dedicated select command to select the web module of the currently selected portlet application or portlet.

Example:

$Portlet select the root $Portlet select the parent $Portlet select the webmodule 

 

Search

The generic search syntax is documented in Search. The Portlet bean supports the following keywords for node types in searches. Alternative, shorter keywords are documented in the bean help.

  • webmodule, webmodules, module, modules, wm, w, m
  • application, applications, app, apps, a
  • portlet, portlets, p
  • concrete (portlet or application)
  • abstract (webmodule)
  • all or any

In addition to the default search criteria, the Portlet bean supports two criteria that match on the name of the objects. The name is similar to a common name, except that there are no restrictions on the character set. The name is a real attribute of the repository objects, not a synthesized one like the common name.

Attribute Description
namehas The value is a string, the search is for objects with the string as a substring in their name. Comparison is case insensitive.
nameis The value is a string, the search is for objects with the string as their name. Comparison is case sensitive.

Example:

### example: search all applications related to news $Portlet deselect $Portlet search application namehas "News"

### example: find and select unique news portlet ###          will fail if none or several are found $Portlet find portlet nameis "NewsPortlet" select 

 

Plain attributes

In addition to the default attributes, repository objects have some of the following attributes. Alternative, shorter names are documented in the bean help.

Attribute Description
name The name, for all object types.
version The version number, for web modules only.
contextroot The absolute path URI, for web modules only.
resourceroot The relative directory, for web modules only.
defaultlocale The default locale, for applications and portlets.

These attributes are also available:

Attribute Description
id, oid, guid The identifier of the node. Suitable input for 'select'.
uniquename, uname, un The global unique name of the node, if it has one.
type The type of the node. Options: repository, webmodule, application, portlet
name The name of the node.
commonname, cname, cn The common name generated for the node.
version The version number. Only for web modules.
contextroot, context, uri The relative URI for adressing the web module. Only for web modules.
resourceroot, resdir, dir, war The subdirectory where the web module resources can be found.
defaultlocale, dlocale, defloc The default locale. Only for portlet applications and portlets.
servlet The id of the associated servlet. Only for portlets.
cachescope, cs The remote cache scope of this repository node. Only portlet nodes can have this read-only flag. The attribute value can be empty. Valid attribute values are 'shared' or 's' for a shared remote cache scope, respectively 'nonshared' or 'ns' for a non-shared remote cache scope.
cacheexpiration, cacheexp, cexp The expiration value of the remote cache, in seconds. Only portlet nodes can have this read-only flag. The attribute value must be a numeric expression, where -1 means the cache never expires, 0 means the cache expires at each request.
remotecachedynamic, rcd Indicates if the remote cache is dynamic or static. Only portlet nodes can have this read-only flag. A value of true indicates that the remote cache is dynamic. false indicates that the remote cache is a static cache.

All attributes are read-only, there is no set command. The resourceroot attribute typically is the name of the WAR file of the web module.

 

List valued attributes

The portlet nodes have two list valued attributes, locales and parameters. See the bean help for alternative, shorter names for these lists. Only the list command is supported, the lists cannot be modified. The locales list is available for portlets and portlet applications. It holds the locales for which locale specific attributes are defined in Locale specific attributes. The parameters list holds the init parameter setting names that are associated with the specified portlet.

 

Locale specific attributes

Portlets and portlet applications have the following locale specific attributes. All attributes are optional. The list of locales for which attributes are defined can be queried using the list command (List valued attributes).

  • title
  • shorttitle
  • keywords
  • description

Only the nlsget command is available for locale specific attributes.

 

Portlet Metadata

Portlet nodes can own metadata, which are name/value pairs of data that are associated with the content node. Metadata are used by the portal itself (for example, to set display attributes), or by the user. The portal bean allows a read-only access on portlet metadata. Metadata can only be assigned with portlet-type or application-type repository objects.

Example:

$Portlet parmget <id> <name>
$Portlet list <id> parms <name>

### only for beans with a current selection $Portlet parmget <name>
$Portlet list parms <name>

### example: get the metadata for an instance property named # "MyPortletConfig"
puts "[$Portlet parmget MyPortletConfig]"

### example: list all metadata names for the selected portlet foreach pname [$Portlet list parms] {
puts "$pname" 
}

 

Portlet Preferences

It is possible to get and set preferences to portlet instances. Because portlet beans specify a static portlet only, and not a portlet instance that resides on a page, portlet instances must be identified by two ID values: The ID of the portlet that specifies the portlet itself, plus the ID of the portlet entity piid that anchors an instance of the portlet in a page.

The command prefnames can be used to obtain a list of available preference names. Portlet preferences may have multiple values. The command getpref therefore accepts a numeric index attribute, that denotes the number of the value to be obtained (0 means to return the first preference value, 1 means to return the second value, and so on). The total number of available preference values for a specific preference name is returned by the prefcount command.

The addpref command can be used to add a new portlet preference value to the portlet preference list. Portlet preferences can be set to read-only. This can be controlled by the commands spprof ("Set Portlet Preference Read-only Flag") and gpprof ("Get Portlet Preference Read-only Flag"), respectively.

Example:

$Portlet prefnames <id> <piid>
$Portlet getpref <id> <piid> <name> at <index>
$Portlet addpref <id> <piid> <name> <value>
$Portlet gpprof <id> <piid> <name> [numeric] 
$Portlet spprof <id> <piid> <name> <readonly-flag>

The portlet is identified by two ID values: The ID of the portlet itself, and the ID of the portlet entity. The ID of the portlet entity can be obtained by the command $Layout get piid.

Example:

### example: set a portlet preference ### 1. locate the control where the portlet resides ### 2. obtain its the portlet instance id ### 3. set the portlet preference accordingly set ctl [$Layout find all pid [$Portlet csn] select] 
set piid [$Layout get $ctl piid]
$Portlet addpref $piid MYKEY "SomeValue"

### example: list portlet preference values for key "MYKEY"
### the control ID is stored in the variable ctrl for {set ix 0} {$ix < [$Portlet prefcount $piid MYKEY]} {incr ix} {
  puts "[$Portlet getpref $piid MYKEY at $ix]"
}

### example: drop all portlet preferences on a ceratin key $Portlet droppref $piid  MYKEY

Dependent on the standard that the portlet complies with, there are differences in the handling of portlet preferences. Standard portlets allow to set multiple preference values on a preference key, while IBM portlets only support single values on each portlet preference key.

 

$Look

Themes and skins are two distinct sets of objects with a matrix relation, where each skin can be tied to any number of themes. The sets of themes and skins are accessible through the Look bean, which is referenced as $Look in JACL.

The Look bean provides access to the portal theme and skin objects:

 

Navigation

The Look bean currently is a simple lookup mechanism to access name and ID of the available themes and skins. It does not support a current selection, nor navigation of the matrix relation between both sets. Since that may change in the future, the deselect command is implemented. It can be used before searches to ensure that the search is global, even if a current selection is introduced in the future.

Example:

$Look deselect 

 

Search

The syntax for searching is similar to the generic tree search described in Search. Since the Look bean does not support a current selection, the search is not scoped and the keyword select is not supported for the find command. The command deselect (Navigation) can be used to ensure that a search is global, even if a search scope is introduced in the future.

The Look bean supports the default search criteria, and the following keywords for node types in searches. Alternative keywords are documented in the bean help.

  • theme
  • skin

Since the sets of themes and skins are distinct, there is no option to search for both type of nodes at the same time.

 

Plain attributes

Themes and skins support the default attributes. Only the get command is available. Since there is no current selection, the ID of the node for which to obtain an attribute value has to be given explicitly.

 

Global lists

For ease of use, there are two global lists that hold the common name of all themes and skins, respectively. They can be accessed with the listall command, which expects the list name as an argument. The following list names are supported. See the bean help for alternative list names.

  • themes
  • skins

Example:

### example: list the names of all themes $Look listall themes 
### example output:
Admin WebSphere Engineering Science Finance Corporate 

 

$Access and $PacList

The scripting operations for access control differ fundamentally from those for content, layout or the portlet repository. The reason is that access control data is not transparently cached on the client. To avoid a huge number of round trips and annoying response times for every simple lookup operation, a different programming model has been adopted for access control data.

The collected access control data for a resource is represented on the client by an object. These objects are explicitly created, locally modified, and written back to the portal. All local modifications become effective at the time the object is written back.

Two script beans are provided for access control data...

$Access Read and write access control objects.
$PacList Edit access control objects

The Access bean and PacList bean provide the following methods:

 

Access control objects

The complete access control data for a resource is represented on the client by a so-called PacList object. PAC stands for "Portal Access Control". PacList objects are opaque, they can not be manipulated directly. Instead, they are loaded into the PacList bean, which provides the operations to view and edit the objects. PacList objects are obtained from and written back using the Access bean.

The access control data for a resource is split in similar data groups for several action sets, also referred to as role types in the information center. The term action sets will be used here, as it has the smaller potential for misinterpretation. The portal uses predefined action sets, which combine the actions for the following types of portal users. One name for each action set is given in parentheses. Alternative names are documented in the help of the PacList bean.

For each action set, there is a list of principals that are explicitly allowed to execute the corresponding actions. A principal is a group or user, which are specified by a name or distinguished name (DN). There are three special principals, which represent an anonymous user, all authenticated users, and all user groups.

In addition to the list of principals, there are two flags that control the implicit distribution of permissions through resource hierarchies. The inheritance flag controls distribution of permissions from parent to child nodes. If inheritance is not blocked, a principal that has permission on the parent will have permission on the child, too. That is particularily useful for administrative actions. The propagation flag controls the other direction. If propagation is not blocked, a principal that has permission on at least one child will have permission on the parent as well. That is useful for simple actions, like viewing a page, which requires view access to all parents.

Although the flags can be manipulated for each action set, they will be ignored for security administrators and administrators. For these two action sets, inheritance and propagation is never blocked.

 

Life cycle

PacList objects are read from and written back to the portal using getacl and setacl in the Access bean. The command getacl returns the PacList object for a resource. It expects the category and identifier of the resource as arguments. The category identifies the script bean that is responsible for the resource. It is given as a keyword, which can be the bean name or the type of the resource. The supported keywords are documented in the help for the Access bean. PacList objects can only be obtained for resources handled by the Content and Portlet beans. For the root node of the portlet repository, there are no PacList objects.

The command setacl writes a PacList object back to the portal. That is only necessary if the PacList object has been modified. The only argument to the command is the PacList object itself. Each PacList object is tied to a particular resource and can not be written for any other resource.

Example:

$Access getacl <category> <id>
$Access setacl <paclist>

### example: get PacList object for a particular page ###          the object is stored in variable "acl"
$Content find label uniquename ibm.portal.Administration select set acl [$Access getacl Content [$Content current]]

### example: write back PacList object in variable "acl"
$Access setacl $acl 

To access or manipulate a PacList object, it has to be loaded in the PacList bean. The operations of the PacList bean always refer to the PacList object currently loaded. An object can be loaded for viewing only using view, or for manipulation using edit. Both commands expect the PacList object as an argument. The PacList bean can only be loaded if it is unloaded, or if it is loaded with an object that has not been modified.

Example:

$PacList view <paclist>
$PacList edit <paclist>

### example: load PacList object for content root, view only $PacList view [$Access getacl Content [$Content root]]

### example: load PacList object for a particular page $Content find label uniquename ibm.portal.Administration select set acl [$Access getacl Content [$Content current]]
$PacList edit $acl 

The command current returns the name of the loaded object, which includes the identifier of the resource. The command done unloads the PacList bean and returns the object that was loaded. If the PacList bean is already unloaded, done still returns the PacList object that was loaded before, which is useful for dealing with errors.

The command modified returns whether the currently loaded PacList object has been modified since it was loaded. If the keyword numeric is added, it returns the value of the flag as a boolean 1 or 0. Without the keyword, it returns a string "true" or "false", respectively.

Example:

$PacList current $PacList done 
$PacList modified $PacList modified numeric 
### example: write back and unload PacList object ###          only if it was modified if [$PacList modified numeric] {
  $Access setacl [$PacList done]
}

### example: recover the last loaded PacList object $PacList view [$PacList done]

 

Global lists

There is a global list that holds the names of the predefined action sets. It can be accessed with the listall command in the Access bean. The command expects the list name as an argument. The only supported list name is actionsets. See the bean help for alternative list names.

Example:

### example: list the names of all predefined action sets $Access listall actionsets 
### example output:
Admin SecurityAdmin Delegator Manager Editor PrivilegedUser User 

 

Principals

The list of principals for an action set can be access using the list command. The first argument is the name of an action set. If the second argument is the keyword all, the command returns all principals in the list, separated by newlines. A regular principal is listed with its name. A special principal is listed with a dedicated name embraced by special characters, which makes the special principals easy to spot. Since principal names can include whitespace, the complete list should not be parsed into items.

The principals in the list can be accessed individually. The keyword at as the second argument indicates that the third argument is an index. Alternative keywords are documented in the bean help. The command returns the principal at the given position in the list, where 0 is the index of the first position. If the index is out of range, the command returns empty. The number of principals can be obtained using count, which expects the name of the action set as the only argument.

Example:

$PacList list <actionset> all $PacList list <actionset> at <index>
$PacList count <actionset>

### example: get first principal in list of administrators $PacList list Administrator at 0

### example: list all principals in all lists foreach as [$Access listall actionsets] {
  puts "\nPrincipals for $as:"
  puts [$PacList list $as all]
}

The command grant adds a principal to a list of principals. The first argument is the name of the action set for which to add a principal. The second argument is a keyword that indicates whether a regular or special principal is to be added, as described below. The third argument specifies the principal to add. The PacList bean help documents alternative keywords for the second argument.

If the keyword name is given as the second argument, a regular principal is added. The third argument is the name of the principal, either as a fully qualified distinguished name, or as a short name. The name will only be resolved to a canonical form at the time the PacList object is written back to the portal. Therefore, it is possible to have duplicates in the list, which will be removed by the portal.

If the keyword special is given as the second argument, a special principal is added to the list. The third argument is a keyword indicating which special principal shall be added. The following special principals are supported. Alternative keywords are documented in the help for the PacList bean.

  • anonymous - a user that is not logged in

  • authenticated - any user that is logged in

  • allgroups - any group of a user that is logged in. This virtual user group contains all non-virtual user groups.

The grant command returns a success message if a principal was added to the list. It returns empty if the principal to be added was spotted as a duplicate. As mentioned above, duplicates can not be spotted by the PacList bean if names in non-canonical form are used.

Example:

$PacList grant <actionset> name <name>
$PacList grant <actionset> special <keyword>

### example: grant user access to anyone authenticated $PacList grant User special Authenticated 
### example: grant editor access to John Doe - twice $PacList grant Editor name "johndoe"
$PacList grant Editor name "uid=johndoe,dc=example_1,dc=com"

The command revoke deletes principals from the list for an action set. The first argument is the name of the action set. The second argument is a keyword that indicates how the principal to delete is specified, as described below. Alternative keywords are documented in the help for the PacList bean. In most cases, there is a third argument that specifies the principal to be removed. The command returns a success message if a principal was removed from the list, or empty if the principal to be removed was not found.

If the second argument is the keyword all, the command deletes all principals from the list. This is the only case where more than one principal is removed. It is also the only case without a third argument.

If the second argument is the keyword at, the third argument is the index of the principal to be deleted. This addressing style is similar to the list command. It can be used to delete regular and special principals. Note that the indices of the succeeding principals are changed by this operation.

If the second argument is the keyword name, the third argument is the name of the regular principal to delete. This addressing style is similar to the grant command. Since the PacList bean can not resolve names into canonical form, the name must be given in the exact same form in which it is present in the list. If the principal was read from the portal, that will be the canonical form. If the principal was added by a previous grant command, the name in the list will be unchanged from the argument given to that command.

If the second argument is the keyword special, the third argument is a keyword for the special principal to delete. This addressing style is similar to the grant command and uses the same keywords for the special principals.

Example:

$PacList revoke <actionset> all $PacList revoke <actionset> at <index>
$PacList revoke <actionset> name <name>
$PacList revoke <actionset> special <keyword>

 

Permission blocks

The command show is used to access the flags that control distribution of permissions. The first argument is the name of the action set, the second is the name of the flag to obtain. The optional keyword numeric indicates whether the flag value should be returned as a human readable string, or as a numeric value suitable for programmatic evaluation. Since the string value is subject to translation into different locales, only the numeric value can reliably be used in conditional statements. Note that the numeric value 0 indicates a block, while 1 stands for allowed distribution. The following names are supported for the two flags. Alternative names are documented in the help for the PacList bean.

  • inheritance - from the parent to this node

  • propagation - from the children to this node

Example:

$PacList show <actionset> <flag>
$PacList show <actionset> <flag> numeric 
### example: evaluate manager inheritance flag if [$PacList show Manager inheritance numeric] then {
  puts "inheritance is permitted"
} else {
  puts "inheritance is blocked"
}

The commands block and unblock can be used to change the flags that control distribution of permissions. They expect the name of the action set and the name of the flag as the first and second argument. The block command will prevent the corresponding distribution of permissions, unblock will allow it. The commands return a success message if the flag value has changed, or empty if the flag already had the desired value.

Example:

$PacList   block <actionset> <flag>
$PacList unblock <actionset> <flag>

### example: prevent propagation of delegator permissions $PacList block Delegator propagation 
### example: allow inheritance of user permissions $PacList unblock User inheritance 

 

$Portal

The $Portal bean provides...

The $Portal bean handles functionality that is outside of the responsibility of the other beans. This includes global portal data as well as technical aspects of scripting, such as the scripting session with the portal.

 

Authentication

Before any portal data can be accessed from a script, the user identity for script execution has to be established. The login command authenticates the scripting engine against the portal and creates a user session for the subsequent commands. There are several different options for logging in, which can be distinguished by the number of arguments.

The login command with two arguments expects a user name and a password as the first and second argument, respectively. The user name identifies the portal user. It can be given as a fully qualified distinguished name, or as a login name. The portal will look up the user name and verify the password.

Example:

$Portal login <user> <password>

### example: login as Portal user $Portal login wpsadmin <password>

The login command without arguments can only be used if security is enabled in the portal. In that case, a user name and password had to be given to the application server in order to connect to the portal. The portal will accept the user identity from the connection without a second password check. This requires that the application server user is also a portal user.

Example:

$Portal login 

The login command with a single argument can only be used if security is enabled in the portal. Like the version without argument, the user identity from the connection is accepted by the portal. In addition, that user requires manage permission on the portal itself. That is the same permission required to use the XMLAccess tool.

If these preconditions are satisfied, the user.name.given as argument, which is different from the user name of the connection, will be looked up and taken as the portal user identity. There is no second password check. This is similar to the su command found in many operating systems, which allows the super user to act as any other user, without knowing the user password.

Example:

$Portal login <user>

### example: login and change to Portal user $Portal login johndoe 

The logout command terminates the scripting session and allows the portal to free the resources allocated for that session. It should always be used before the scripting client exits. The logout command also invalidates the portal data cached in the client. It is therefore possible to re-authenticate as a different user without starting a new scripting client.

Logout and re-authentication as the same user should always be performed if the connection from the scripting client to the portal is re-established using the AdminControl bean of the wsadmin tool. The portal may have lost the user session in that case, which lets subsequent operations fail.

Example:

$Portal logout 

In a deployment scenario, the authentication should not be handled by the deployment script itself. Use a wrapper script for the authentication instead, so the deployment script can be executed under different user identities without changes. Here is an example for a wrapper script, which assumes that the deployment script defines a run_deployment procedure.

Example:

### keep the user identity of the connection $Portal login ### execute the deployment procedure run_deployment ### clean up before exit $Portal logout 

Alternatively, the deployment script can use procedures defined in a profile script for login and logout. Profile scripts are executed on startup of the scripting client.

Example:

### procedure for login proc portal_login { } {
  $Portal login <username> <password>
 # other startup operations, like logging the access }

### procedure for logout proc portal_logout { } {
  $Portal logout   # other shutdown operations }

 

Virtual Portal selection

The $Portal setvp command allows you to set a virtual portal for a login command. It is possible to set the virtual portal during a session, but the session only becomes effective during the $Portal login command.The virtual portal is specified by the URL context. This is the part of the home URL that identifies the virtual portal. If $Portal setvp is invoked without a URL context, the default virtual portal is set.

Example:

### example: set the virtual portal and execute a portal login ### in the example, the virtual portal URL context is employees,
### which would correspond with a base URL of '/wps/myportal/employees'

$Portal setvp employees 
$Portal login 

 

Examples

 

Delete portlets

Example:

### delete all welcome-portlets from all pages of a user ### see the Authentication section for portal_login and portal_logout portal_login foreach page [$Content search pages] {
  $Content select $page   foreach c [$Layout search control commonnamehas Welcome] {
    $Layout delete $c    }
 }
portal_logout 

 

Add portlets

Example:

### Add a FunPortlet next to each WeatherPortlet 
### procedure: add a portlet next to a control ### this changes the current selection of the Layout bean proc add_portlet { control portlet } {
  global Layout   $Layout select $control   set pos [$Layout get position]
  set pos [expr $pos + 1]
  $Layout select the parent   $Layout create control $portlet select   $Layout move to $pos }

### main program ### See the Authentication section for portal_login and portal_logout 
portal_login set fun [$Portlet find portlet nameis FunPortlet]

foreach page [$Content search pages] {
  $Content select $page   foreach c [$Layout search control commonnamehas Weather] {
    add_portlet $c $fun   }
}
portal_logout 

 

Troubleshoot

  • connectivity problem / MBean not found -> connected to wrong application server

  • bean not enabled -> not logged in

  • Layout bean not enabled -> no page selected in Content bean

  • PacList bean not enabled -> no PacList object loaded

  • no method named "xxx" -> typo or capitalization in method name, check bean help

  • no method named "xxx" with y arguments -> wrong syntax, check bean help

 

Property File Format

Locale specific attributes for a set of locales can be provided in a Java property file. The generic format of Java property files is described in the Java API documentation for method load in class java.util.Properties. The description here covers the particular properties that will be interpreted when locale specific attributes are loaded from a portal script.

The property files are loaded by the script interpreter. They have to be located on the client machine where the script is run.

A property file must be encoded in the ISO 8859-1 character encoding format.

Here is an example of a property file with no prefix.

Example:

locales = en de 
en.title = English Title en.description = A description, in English.

de.title = Deutscher Titel de.description = Eine Beschreibung auf Deutsch.

At the core of the file is the property locales, which holds a whitespace separated list of the locales for which attributes are defined in the file. Only the locales listed here will be interpreted when the property file is loaded.

The actual attribute values for each locale are defined as separate properties. The key for these properties is composed of the locale and the attribute name, separated by a dot. The attribute name is title or description, the locale must match the string listed in the locales property. Case is significant for property keys.

There is no fallback algorithm when loading locale specific attributes. If a property title.en is defined, it will not be considered when the title for locale en_US is required.

To combine different sets of localized data into a single property file, prefixes can be used. All properties of a set have to use the same prefix, which is separated from the property name by a dot. Here is an example of a property file with two sets, using the prefixes leisure and finance, respectively.

Example:

leisure.locales = en fr leisure.en.title = Leisure Page leisure.fr.title = Page de Loisir 
finance.locales = en de finance.en.title = Finance Page finance.en.description = Holds financial info portlets.
finance.de.title = Finanzseite 

We can also load property files in the scripting format by using the XML configuration interface. To do this, specify the locale as part of the prefix in a <localedata> tag.

 

Index paths

Index paths are used to refer to components in the component hierarchy. They are based on the index or position of a component in the surrounding container. An index path is a multi-dimensional index of a component, where the number of dimensions is equal to the depth of the component in the tree. Index paths can be absolute or relative, depending on whether there is a leading slash. Absolute paths start with a leading slash and are resolved from the root component. Relative paths start with a number and are resolved from the selected component. Trailing slashes are irrelevant.

/

The root component.

/0

The first child of the root component.

/1

Second child of the root component.

...

/0/0

The first child of the first child of the root component.

/0/1

Second child of the first child of the root component.

...

/5/1/3

The fourth child of the second child of the sixth child of the root component.

...

0

The first child of the current component.

1

Second child of the current component.

...

1/0

The first child of the second child of the current component.

...

 

Related information

 

Parent topic:

Portal Scripting Interface