For information about accessing scoped paths in the Pageflow and Workflow Modelers, see the chapter on the Pageflow Modeler in the Pageflow and Form Guide or the chapter on the WorkflowModeler in the Workflow Guide.Developing exteNd Director Applications
CHAPTER 12
This chapter describes scoped paths and how to use them in your exteNd Director applications. It has these sections:
For information about accessing scoped paths in the Pageflow and Workflow Modelers, see the chapter on the Pageflow Modeler in the Pageflow and Form Guide or the chapter on the WorkflowModeler in the Workflow Guide.
Scoped paths allow you to quickly access data in your exteNd Director applications. The term scope refers to the state of the data, or data persistence. Data is nonpersistent if it is available for a single user session. Data is persistent if it is available to one or more users over multiple sessions and, potentially, to external applications.
An exteNd Director application has access to a number of different nonpersistent and persistent scopes. An HTTP Session is an example of a nonpersistent scope, and the exteNd Director resource set is an example of a persistent scope. The path part of a scoped path is simply the location of the data within a particular scope.
exteNd Director includes a group of predefined scopes that are available from the Pageflow and Workflow Modelers and through the Scoped Path API.
Scoped paths make it easy to access and manipulate data:
Many scoped paths support XPath-based navigation of XML documents (see Predefined scopes). XPath is a language defined by the World Wide Web Consortium (W3C) for addressing parts of an XML document.
You can append an XPath expression to a scoped path that points to an XML document. The Scoped Path dialogs in the Pageflow and Workflow Modelers provide a link to the Scoped Path Navigator tool for this purpose.
For more information about the XPath Navigator, see Using the Scoped Path and XPath Navigators.
For information about XPath, go to http://www.w3.org/TR/xpath20/
exteNd Director provides a set of predefined scopes with path syntax based on standard file access and XPath. The table below is a summary of the features for each predefined scoped path. The table columns mean the following:
Scope: the name of the predefined scoped path. Click the name for more information.
XPath: if marked, this scoped path supports XPath. For more information, see Using the Scoped Path and XPath Navigators.
Read: if marked, this scoped path is readable. This means that the scoped data is available on a "copy from" function in the Pageflow and Workflow Modelers.
Write: if marked, this scoped path is writable. This means that the scoped data is available on a "copy to" function in the Pageflow and Workflow Modelers.
For more information, see Copying scoped paths.
Description
The Application scope is an application-wide scope for the HTTP session. Objects stored in this scope are available to any other object that reside in the same portlet application and that handles a request in the same session. For the Pageflow Modeler, this includes any other flow activities (including JSP and Servlet activities) and any other portlet contained in the same session.
Path
Application/aKey/path/xpath
Examples
Write (Copy to) example:
Session/doc/mydoc --> Application/docout/doc1
Read (Copy from) example:
Application/prop/aString --> Flow/property/prop1
Description
The Artifact scope is an application-wide scope for persistent data stored in any of the following:
This scope supports XPath navigation to XML documents. Artifact scopes are available on the "copy from" side of a scope copy in the Pageflow and Workflow Modelers.
TIP: It is more efficient to use the ResourceSet scope and CM scope scopes rather then the Artifact scope whenever possible.
Path
Artifact/cm://path/xpathArtifact/war://path/xpathArtifact/dir/path/xpath
Examples
Write (Copy to) example:
Flow/document/mydoc --> Artifact/c:/applications/docs/mydoc1.xml
Read (Copy from) example:
Artifact/c:/applications/docs/mydoc1.xml --> Flow/document/mydoc
Description
The CM scope is an application-wide scope for persistent data stored in the Content Management Subsystem. You must enter a known repository and path. On a "copy to" function (writable) the document is written to the specified location in the PUBLISHED status. This scope supports XPath expressions.
Path
CM/myrepository/mypathtodoc/xpath
Examples
Write (Copy to) example:
Flow/mydoc/doc --> CM/companydoc/reports/report1.xml
Read (Copy from) example:
CM/companydoc/reports/report1.xml --> Flow/mydoc/doc
Description
The Document scope allows you to create a temporary XML document. In a Pageflow or Workflow application the Document scope is available for a single object in a flow application, and is valid only on the "From" side of a copy.
NOTE: The document must be a valid (well-formed) XML document.
Path
Document/<elem></elem>
Example
This example shows a series of scoped path copy operations that copy elements from the Document scope to the Session scope:
/Document/<books/> -> /Session/bookref /Document/<book>Jungle book</book> ->/Session/bookref/books /Document/<book>Catcher in the Rye</book> -> /Session/bookref/books /Document/<book>Moby Dick</book> -> /Session/bookref/books
In the example shown above, you see how to create a document on the Session scope that contains multiple nodes with the same name. In the following example, you see an alternative way to do this:
/Document/<books/> -> /Session/bookref /Document/<book/> -> /Session/Temp /Request/param/title1 -> /Session/Temp/book /Session/Temp -> /Session/bookref/Books /Document/<book/> -> /Session/Temp /Request/param/title2 -> /Session/Temp/book /Session/Temp -> /Session/bookref/Books
Description
The Flow scope is used within a pageflow or a workflow. In a pageflow the flow scope is available to all flow objects (including contained pageflows) for the portlet application session. In a workflow the flow scope is available to all flow objects (including contained pageflows) for the duration of the workflow process.
The Flow scope provides exclusive access to these objects:
|
Flow scope option |
Description |
|---|---|
|
document |
XML document (this scope supports XPath expressions). |
|
property |
A string variable |
|
exception |
A message type or other data to associate with an Exception activity
|
|
document property |
A property (metadata) associated with a document |
|
The next three properties apply to a pageflow running within a workflow.
|
|
|
lock |
Attempts to lock a workitem for the current user: |
|
unlock |
Attempts to unlock a workitem for the current user: |
|
persistent |
Returns true if the workitem is in a persistent state (workflow context) and false if not persistent (pageflow context). |
Path
Flow/document/varName/xpathFlow/property/varNameFlow/exception/typedocumentproperty/varName
Examples
Write (Copy to) example:
Session/doc/mydoc --> Flow/document/doc1
Read (Copy from) example:
Flow/doc/doc1 --> CM/companydoc/reports/report1.xml
Description
The Format scope creates a unique identifier at runtime that can be appended to another scope or referenced by other activites in a flow.
This scope supports two types of formatters. Both of these formatters use the patterns as defined in the associated java.text.formatter class:
|
Format scope option |
What it does |
|---|---|
|
Decimal |
Generates a number in the specified format. Starts the get sequence at 0, and increments by 1 each time the getValue is called on the scope. This formatter does not allow for either initial value setting or a different increment setting.
|
|
Date |
Generates a timestamp in the specified format.
|
Path
Format/Date|Decimal/pattern
Examples
Format/Decimal/000.0# Format/Date/yyyy.MM.dd Format/Date/yyMMddHHmmsss Format/Date/FULL
Copy example:
CM/myRepository/folder1/${/Format/Date/yyyy.MM.dd}.doc
Description
The Log scope allows you to access the exteNd Director logging facility—runtime logging facility that writes information in one of several standard logs or in your own custom logs. You decide what level of detail you want in the logs. The output of the logs displays on the server console. If you don't specify the logging level, the default value is used.
The Log scope is available on the "To" side of copy in the Pageflow or Workflow Modelers.
For more information, see Logging Information.
Path
Log/LogIdentifier/Level
Examples
Log/EboFwLog Log/EboCmLog/5
Copy example:
String/mystring --> Log/myLogIdentifier
Description
he Portal scope returns a fully qualified URL to a portal resource. This scope is valid only on the "From" side of a copy.
|
Portal scope option |
Path option |
Description |
|---|---|---|
|
Url |
Login |
Returns PortalLogin portlet URL. |
|
Logout |
Returns Logout URL (terminates the current user session). |
|
|
NewUser |
Returns NewUser portlet URL |
|
|
Home |
Returns user-defined default page. If not defined or if the user is anonymous, returns the portal default page URL. |
|
|
Resource |
Returns the ResourceSet URI. |
|
|
Context |
Returns the Director application context URI. |
|
|
Portlet |
Returns a fully qualified URL to a portlet. |
|
|
Keyword See Using the Keyword option below |
Navigation/ContainerPages |
Displays navigation for container pages |
|
Navigation/SharedPages |
Displays navigation for shared pages |
|
|
Navigation/PersonalPages |
Displays navigation for personal pages |
|
|
Navigation/QuickLinks |
Displays navigation for quick links |
Path
Portal/Url/Login Portal/Url/Logout Portal/Url/NewUser Portal/Url/Home Portal/Url/Resource/a uriPortal/Url/Context/a uriPortal/Url/Portlet/a portlet name
Examples
Portal/Url/Resource/images/DirectorWelcomeHeader.jpg Portal/url/Context/PAC Portal/Portlet/StockQuote
Use the Keyword option to display the installed Navigation portlet by using the scoped path syntax in a pageflow activity. For example:
${Portal/Keyword/Navigation/SharedPages}
For more information, see Scoped path syntax in pageflow activites.
Keyword accesses the XSL pattern used by the installed Header portlet and the Navigation portlet. These two portlets use the same portlet class to display the content of a preference named layout, in conjunction with a specific XSL style sheet. The actual content is determined by the context user.
For more information see in the chapter about portal pages in the Portal Guide
Description
The PortletPreference points to the current portlet preference value with the specified variable name. This scope is private to the portlet preferences settings for the current portlet session. Values in this scope persist for the user and the portlet instance.
For more information, see the section on portlet preferences in thePortal Guide.
Path
PortletPreference/varName
Examples
Write (Copy to) example:
String/'300" --> PortletPreference/height
Read (Copy from) example:
PortletPreference/height --> Session/prop/height
See also
Scoped path syntax in portlet preferences
Description
The Request scope represents the request object associated with a portlet or HTTP request. Request scope values are available on portlet action and render requests, as described in the table below.
For information about how render and action requests are handled in pageflows, see the chapter on Working with Pageflows in the Pageflow and Form Guide.
The Request scope provides access to these values:
|
Request scope option |
Description |
Calls this method: |
|---|---|---|
|
param |
Returns the String object associated with the specified parameter. Available on render and action requests. |
getParameter() on EbiRequest. |
|
attr |
Sets or returns the String object associated with the specified attribute. Available on render and action requests. |
get/setAttribute() on EbiRequest |
|
cookie |
Returns the cookie value associated with the specified cookie name. Available on render and action requests. NOTE: This option returns an Object. If you are using it in a Pageflow it will not be available for a link expression or for rendering without further processing (in a Java activity, for example). |
getCookieValue() on EboCookieUtil |
|
api |
Returns the value associated with the specified request method. Available on render requests only. In the Pageflow Modeler, select the method from the tree view.
|
See methods on javax.portlet.RenderRequest |
|
prop |
Returns the HTTP request header for the specified property. Available on render and action requests. In the Pageflow Modeler, select the property from the tree view. |
getHeader() on EbiRequest |
Request API option and PersistMgr realm If you are using the PersistMgr realm configuration, the get() methods on the api option related to authenticated users—getAuthType(), getRemoteUser(), and getUserPrincipal()—will return null. This is because the request object does not get populated with authentication data by the application server when authentication is done through the PersistMgr.
You can get authentication information by instantiating a context object (com.sssw.fw.api.EbiContext) in your code. Use one of the createEbiContext() methods on EboFactory.
Request API option and iChain single sign-on To provide sign-on support for iChain, you may want to pull the user ID and password out of the request header. The getUserID() and getPassword() methods on the Request api option give you a way to do this.
Path
Request/param/varNameRequest/attr/varNameRequest/cookie/varNameRequest/api/methodRequest/prop/varName
Examples
Write (Copy to) example:
Session/mykey/locale --> Request/attr/locale
Read (Copy from) example:
Request/api/getLocale --> Session/mykey/locale
Description
The ResourceBundle scope allows you scope to a defined Java resourceBundle.
Path
ResourceBundle/family/aKey
Examples
Copy example:
ResourceBundle/myResourcesFile/Key1 --> Session/localize/locale
Description
The ResourceSet scope is an application-wide scope for persistent data stored in your exteNd Director project ResourceSet.
NOTE: This scope is similar to the Artifact WAR scope but restricts access to known locations in the WAR's ResourceSet.
This scope supports XPath navigation to XML documents.
Path
/ResourceSet/path/xPath]
Example
ResourceSet/pages/category/pagetype --> Flow/property/ptype
Description
The Response scope represents the response object associated with a portlet response.
Response scope values are available on both portlet action and render responses, unless specified otherwise in the table below. For information about how render and action responses are handled in pageflows, see the chapter on working with Pageflows in the Pageflow and Form Guide.
The Response scope provides access to these values:
|
Response scope option |
Description |
Calls this method: |
|---|---|---|
|
cookie |
Creates a cookie with the specified value and sets it in the browser. Available on render and action responses. |
addCookieToResponse() on EboCookieUtil |
|
render |
Sets the specified String parameter for the Portlet render request. Available on render responses only. |
setRenderParam() on ActionResponse |
Path
Response/cookie/varNameResponse/render/varName
Example
Copy example:
Session/param/myString --> Response/cookie/anAttribute
Description
The Session scope is private to the portlet and its included resources for the current portlet session. Objects in this scope are namespaced to be unavailable to other Web components in the portlet application.
IMPORTANT: If you want to access session variables from a Pageflow JSP page or Servlet activity, you need to copy the data to the Application scope. For more information, see Application scope.
Path
Session/aKey/path/xpath
Examples
Write (Copy to) example:
CM/myrepository/mypathtodoc/pubdoc.xml --> Session/doc/mydoc
Description
The String scope allows you to create a temporary string. In a Pageflow or Workflow application the String scope is available for a single object in a flow application, and is valid only on the "From" side of a copy.
Path
String/aString
Example
Copy example:
/String/I am here -> /Session/myparam
Description
The User scope provides access to the logged in user and user attributes. The User scope provide access to these values:
Path
User/fname User/lname User/email User/id User/myattr
Examples
Write (Copy to) example:
Session/attrubute --> User/attr/attribute1
Read (Copy from) example:
User/email --> Session/contact
The Pageflow and Workflow Modelers provide different ways to copy data from one scope to another at selected points in the flow application. For example, you can use scoped paths to write logical expressions on links and to copy data to and from different scopes.
NOTE: The copy function in the Pageflow and Workflow Modelers copies one value/object per copy. If you want to work with collections of objects, like scoping to a node in a DOM, you need to handle the parsing in a Java Activity or XSL.
You can copy a scoped path before or after the execution of a Pageflow or Workflow activity, or after a link is followed. The copy option you use depends on the logic of your flow. Here is how scoped paths are handled for each copy option:
You can copy scoped paths on activites whenever there is no conflict between two or more scoped paths going to the target activity. This is appropriate when:
A single link is associated with each activity (see example below)
Multiple links are associated with an activity, and the scoped data on each source activity is identical.
Suppose you want to return different pages results based on Link 2 and Link 3. In this scenario, since there is no potential conflict between two links going to a single activity, you could either copy the data on Link 2 and Link 3 or copy the data before the execution of HTML 2 and HTML 3.
You need to copy data on links when you have more that one link going to a single activity and you have different scopes associated with each link. Consider this scenario:
Here you have two links targeting HTML 3. If you want different data associated with this activity—that is, if you want the data to be dependant on the link source—you would need to copy the data on the links.
NOTE: Although you could have two "copy before" scopes on HTML 3, the flow engine has no way of distinguishing them by source link.
Scoped paths include a substitution syntax that can be included in certain application elements and resolved at runtime.
Scoped path support includes substitution syntax for accessing a path directly from HTML and XForm activities in pageflow applications.
NOTE: The standard syntax applies only to objects running in exteNd Director Pageflows.
The syntax is:
scopedpath?my_scoped_path/scopedpath
For example, in an HTML page:
<P>scopedpath?Request/attr/myVarName/scopedpath </P>
Substitutes the string value of myVarName for the scoped path syntax.
You can do dynamic resolution of scoped paths by appending the following syntax to an existing scoped path:
${myPath}
For example, to generate a dynamic document in the Content Management subsystem with the current timestamp as the file name, you could append the Format scope to the CM scope like this:
CM/myRepository/folder1/${/Format/Date/yyyy.MM.dd}.doc
You can use the dynamic substitution syntax ${path} in the Rules subsystem to access scoped paths. This function is available in any condition or action that has template fields.
For more information, see Installed Conditions and Installed Actions in the Rules Guide.
You can also nest a dynamic resolution within a rule using this syntax:
{$CM/folder/${Format/Date/<pattern>}}.doc
The dynamic substitution syntax can also be used to represent a value in a portlet preference descriptor. This example substitutes the value of the String scoped path for a portlet preference value:
...
<text-color> {$String/red} </text-color>
...
You can use the Scoped Path API to access scoped paths directly from your application code—for example, from a Java, JSP, or Servlet activity. Here are the principal classes for accessing scoped paths:
|
Package and class |
Provides |
|---|---|
|
Methods for accessing an instance of a scoped path |
|
|
createScopedPath method for getting a scoped path instance |
NOTE: The Scoped Path and XPath Navigators are essentially the same tools with slightly different features. This section covers the Scoped Path Navigator. For practical purposes, it applies to the XPath Navigator as well.
The Scoped Path Navigator is available from the Pageflow and Workflow Modelers and allows you to select a scoped path using a tree view. When you select one of the predefined scoped paths, the Scoped Path Navigator appears in a separate window:
The tree view also provides facilities for building XPath expressions.
To select a path in the Scoped Path Navigator:
Use the tree view to select the path.
The path you select is reflected in the text box at the top. You can type the path directly in the text box instead of using the tree view.
Some of the scoped paths support XPath expressions (see Predefined scopes). The Scoped Path Navigator supports some of the XPath expressions as defined by W3C. For usage details, see http://www.w3.org/TR/xpath20/.
IMPORTANT: The Scoped Path Navigator is capable of returning only one document element for each scoped path expression. If you use an XPath function that specifies more than one element, only the first element in the group will be returned.
To create an XPath expression:
Navigate to an element (typically an XML document) where you want to enter an XPath expression.
Select Real-time to have your expression evaluated automatically as you enter it, or select Evaluate to evaluate manually. The result of the evaluation displays at the bottom of the window.
NOTE: You can enter the expression in the editor field without using the XPath facilities described below.
Navigate to an XML document using the tree view or the editor and enter a valid XPath delimiter: a slash / character, an open bracket [, or an open parenthesis (. The Navigator displays a dropdown list of elements and functions available at the point you enter the delimiter. For example:
To add an item, select it from the dropdown, and type in an appropriate value when applicable. For example:
Repeat as needed until the expression is complete and valid.
TIP: You can right-click an element to access other XML editing facilities. For more information, see the chapter on XML Editors in Utility Tools.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
