FormsPublisher
Developer’s Guide
Release 6.7.1
Service Pack 1
© 1999-2007 Interwoven, Inc. All rights reserved.
No part of this publication (hardcopy or electronic form) may be reproduced or transmitted, in any form
or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior
written consent of Interwoven. Information in this manual is furnished under license by Interwoven, Inc.
and may only be used in accordance with the terms of the license agreement. If this software or
documentation directs you to copy materials, you must first have permission from the copyright owner
of the materials to avoid violating the law which could result in damages or other remedies.
Interwoven, Inc.
160 East Tasman Dr.
San Jose, CA 95134
http://www.interwoven.com
Interwoven, Inc. 4
Contents
Interwoven, Inc. 6
List of Figures
Figure 1 FormsPublisher Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Figure 2 FormsPublisher Directory Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Figure 3 Process Flow Overview: Creating a New Data Record . . . . . . . . . . . . . . .19
Figure 4 Process Flow Overview: Generating an Output File Using a
Data Record and a Presentation Template . . . . . . . . . . . . . . . . . . . . . . . . .21
Figure 5 FormsPublisher Example Directory Structure . . . . . . . . . . . . . . . . . . . . . .22
Figure 6 Templatedata directory structure within the FormsPublisher directory . . .23
Figure 7 Press Release data capture form (without data) . . . . . . . . . . . . . . . . . . . . .31
Figure 8 Press release data capture form (with data and VisualFormat tool bar) . . .35
Figure 9 Generating a Web Page with TeamSite FormsPublisher. . . . . . . . . . . . . . .72
Figure 10 Weather Data Record with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Figure 11 Weather form as it opens from a URL Command . . . . . . . . . . . . . . . . . . .89
Figure 12 Weather data record to be edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Figure 13 Weather form with Save, Preview, and Generate links. . . . . . . . . . . . . . . .91
Figure 14 Weather data record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Figure 15 Weather form showing an automatically generated name . . . . . . . . . . . . .92
Figure 16 Form Settings dialog box when the data record cannot be renamed. . . . . .93
Figure 17 Weather data capture template using a different style sheet . . . . . . . . . . . .94
Figure 18 Weather data capture template showing the navigation tree. . . . . . . . . . . .95
Figure 19 Press-release screen with collapsed duplicate fields . . . . . . . . . . . . . . . . .97
Figure 20 Data Capture Form with a Callout for the Weather Patterns Item . . . . . .124
Figure 21 Selecting a Value for Weather Patterns Using the Data Capture Callout .124
Figure 22 Data Capture Form with Announcement Field Reflecting
the Value Selected using the Weather Patterns Button . . . . . . . . . . . . . . .125
Interwoven, Inc. 8
About This Book
UNIX: Users should be familiar with basic UNIX commands and be able to use an
editor such as emacs or vi.
Windows: Users should be familiar with either IIS or web servers, and with basic
Windows operations such as adding users and modifying ACLs (Access Control Lists).
It is also helpful to be familiar with regular expression syntax. If you are not familiar
with regular expressions, consult a reference manual such as Mastering Regular
Expressions, by Jeffrey Friedl.
For information about TeamSite, refer to the ContentCenter online help systems and the
TeamSite Administration Guide.
Manual Organization
This manual contains the following sections and chapters:
Chapter 1, “Overview of FormsPublisher,” describes the functionality of
FormsPublisher and shows how to configure the fully functional example
templating environment supplied with FormsPublisher.
Chapter 2, “Setting Up Data Capture Templates,” describes how to customize data
capture templates for your site-specific needs.
Chapter 3, “Setting Up Presentation Templates,” provides an overview on creating
presentation templates for your site-specific needs.
Chapter 4, “Mapping Users, Templates, and Content Records,” describes how to
configure user access to specific templates and data records, which templates can
interact with which data records, and other configurable features of FormsPublisher.
Chapter 5, “Integrating FormsPublisher, DataDeploy, and Workflow,” describes how
to configure FormsPublisher to work with DataDeploy and TeamSite workflow.
Appendix A, “Configuring VisualFormat,” describes how to configure
FormsPublisher to use the VisualFormat text editor in data capture forms.
This manual uses the iw-home notation (italicized iw-home) when discussing both UNIX
and Windows systems. The italics are an Interwoven convention identifying iw-home as
a variable. You should interpret the iw-home notation used in this manual as the
symbolic name of the directory that contains your TeamSite program files.
Interwoven, Inc. 10
About This Book
Notation Conventions
This manual uses the following notation conventions:
Interwoven, Inc. 12
Chapter 1
Overview of FormsPublisher
Overview
FormsPublisher provides a highly configurable way to:
Capture, edit, and store data input from content contributors.
Define the appearance of displayed data.
Integrate captured data with other Interwoven features and products such as
TeamSite Workflow and DataDeploy.
FormsPublisher Model
The architecture of FormsPublisher allows data capture and data presentation to be
configured, executed, and managed separately. The following diagram and sections
provide a high-level overview of this architecture.
ContentCenter
TeamSite Client
TeamSite Server
Production
External Web Server
RDBMS
Data Capture
Content contributors working through ContentCenter have access to the data capture
subsystem. This subsystem lets content contributors select and work through forms
defined by data capture templates to create or edit existing data records, which by
default are stored in the TeamSite file system. Data is stored as XML and used to fill in
presentation templates to generate multiple renderings of the content, including for the
web and wireless devices. After data records are created, they can be displayed using
presentation templates or optionally deployed to a database using DataDeploy.
Data Presentation
After data is captured and stored as data records, users working through ContentCenter
or the command line can access the page generation subsystem to combine a data record
with a presentation template. The end result is a generated output file that displays the
Interwoven, Inc. 14
Chapter 1: Overview of FormsPublisher
data in a way defined by the presentation template. In addition, users can generate an
output file that obtains data from multiple data records and from queries to databases.
The generated output file can optionally be deployed to a production Web server using
OpenDeploy.
Definitions
The following sections define key FormsPublisher terms.
A data capture template is an XML file named datacapture.cfg that defines the form
used to capture data from content contributors. A data capture template is associated
with a category and type. The category and type define what type of data is required by
the data capture template. Each category and type is contained within a separate
directory in the file structure. The data that a content contributor enters in a data capture
template is saved on the TeamSite file system as an XML file in the form of a data
record. See “Data Storage Hierarchy” on page 17 for information about where data
capture templates reside.
Presentation Template
A presentation template is a file that defines how captured data will appear when it is
displayed. A presentation template is populated with a data record that was captured
earlier (through a data capture template) or from queries to databases. You can configure
FormsPublisher to populate any presentation template with any data record plus any
additional information as required from a relational database. You can use presentation
templates with component templates. A component template is a nested presentation
template that is part of another presentation template. You can also use a single data
record to populate more than one presentation template, resulting in a different look and
feel for the same data record. See “Data Storage Hierarchy” on page 17 for information
about where presentation templates reside.
Data Record
A data record is an XML file containing formatting information interspersed with data
captured from a content contributor or through other means. A data record is named by
the content contributor when it is saved, or it can be set up to be named automatically.
The data capture subsystem is a set of Java applications that perform the following
functions:
Reads the datacapture.cfg and templating.cfg configuration files to determine
what information should be presented to a content contributor using ContentCenter.
The page generation subsystem is a set of programs and libraries that perform the
following functions:
Reads the presentation template and templating.cfg configuration files to
determine what information should be presented to a content contributor.
Interprets content contributor input.
Combines data records and presentation templates to produce generated output files.
Configuration Files
FormsPublisher uses the following configuration files:
templating.cfg: The main FormsPublisher configuration file. It is an XML file
that resides outside of the TeamSite file system in iw-home/local/config and
specifies:
The type of data record being produced (iwov or xml).
The data categories and types that are available for use with FormsPublisher.
The presentation templates that can generate HTML files on which TeamSite
branches or directories.
The presentation templates that can be used with a specific data type.
The users or roles who are allowed to create or edit data records for a specific
data type.
The location of the presentation template used for previewing generated HTML
files.
Whether auto-DCR naming has been set for this data type and category.
Whether renaming is allowed.
How the form looks, including buttons that display, whether there is a
navigation tree, and what style sheet is used.
See Chapter 4, “Mapping Users, Templates, and Content Records,” for details about
customizing templating.cfg.
datacapture.cfg: An XML file that defines a data capture template and defines the
data capture form for a specific data type. It defines the data type itself (such as
what information the data type will contain and parameters that define what type of
Interwoven, Inc. 16
Chapter 1: Overview of FormsPublisher
data is legal in any input field). A datacapture.cfg file also specifies the look and
feel of the data capture form displayed in ContentCenter. Each data type has a
datacapture.cfg file. A FormsPublisher environment can contain any number of
datacapture.cfg files, differentiated by where they reside in the directory
structure. See “Data Storage Hierarchy” on page 17 for information about where
datacapture.cfg files reside. See Chapter 2, “Setting Up Data Capture Templates,”
for information about customizing datacapture.cfg.
available_templates.cfg: Identifies workflows to be initiated when certain
FormsPublisher events occur. Refer to the TeamSite Workflow Developer’s Guide for
more details.
Workarea
templatedata
content_record_1 pres_template_1.tpl
content_record_2 pres_template_2.tpl
... ...
Data categories are at the next level in the hierarchy and contain one or more data types.
For example, the data category beverages could contain separate directories for the data
types tea, coffee, milk, and so on. Data categories must be unique; data types within a
category must also be unique. In addition to residing in this directory structure, data
categories and types must also be listed in the templating.cfg configuration file to be
Data type directories each contain a datacapture.cfg file and the subdirectories data
and presentation. Details for the entire hierarchy are as follows:
Interwoven, Inc. 18
Chapter 1: Overview of FormsPublisher
TeamSite File
System
• datacapture.cfg
• Data records
5 8
1 Data Capture
Browser Subsystem templating.cfg
• Content 3 • Reads • Overall
contributor templating.cfg templating
requests new 4 2 rules
• Reads
form datacapture.cfg • Template-specific
• Content 6 • Displays menu rules
contributor fills choices in
in form 7 FormsPublisher
• Creates and saves
data records
9
Server-Side
Workflow
Subsystem
• Starts
successor
task
NOTE
In ContentCenter Standard, the categories and types of forms available to the user is
determined when the user logs in and the available forms are shown in the Forms
module.
6. The data capture subsystem displays the data capture form (as defined by
datacapture.cfg).
7. The content contributor enters data in the data capture form and selects File > Save
to name and save the data record. The new data is sent to the data capture
subsystem. Another option is to set up automatic naming of data records so that file
names are created automatically rather than by the user.
8. Using the data provided by the content contributor, the data capture subsystem
writes a data record to the TeamSite file system. The content contributor could
optionally have chosen to preview the output file. In that situation, the data capture
subsystem reads templating.cfg to determine which presentation templates are
available for that data type. The content contributor selects a presentation template
and the data capture subsystem displays a preview version of the data.
9. If creating the data record is a task associated with a TeamSite Workflow job, the
user indicates the task has been completed and the TeamSite Workflow subsystem
starts the successor task.
Interwoven, Inc. 20
Chapter 1: Overview of FormsPublisher
Figure 4 Process Flow Overview: Generating an Output File Using a Data Record
and a Presentation Template
6
3
Page Generation
Browser Subsystem templating.cfg
1
• Content • Reads templating.cfg • Overall
contributor selects 2 templating
Generate in • Reads presentation rules
FormsPublisher 4 template lists
• Template-specific
• Content • Displays menu rules
contributor selects choices in
a data record and FormsPublisher
presentation 5 • Combines data
template records and
presentation
templates
7 Server-Side
Workflow
Subsystem
• Starts
successor
task
6. The page generation subsystem generates an output file by entering data from the
chosen data record and any other applicable sources into the chosen presentation
template.
7. If creating the generated output file is a task associated with a TeamSite Workflow
job, the user indicates that task has been completed and the TeamSite workflow
subsystem starts the successor task.
iw-home
examples
Templating
README
config
README
templating.cfg.example
example_server_side_inline_callout.ipl
tags
iwov_format_html.pm
iwov_ldap.pm
iwov_ticker.pm
iwov_timestamp_simple.pm
iwov_webdesk_url.pm
README
templatedata
workflow
README
author_submit_dcr-0.ipl
author_submit_dcr-3.ipl
author_submit_dcr.wft
Interwoven, Inc. 22
Chapter 1: Overview of FormsPublisher
templatedata
README
component
ecm Data Category: ecm
press-release Data Types:
...
press-release-immediate
...
press-release-iwov
internet
...
} •
•
•
press-release
press-release-immediate
press-release-iwov
userscript
Data Category: userscript
contact
}
... Data Types:
location • contact
...
organization • location
... • organization
position • position
...
xml Data Category: xml
press-release
...
press-release-with-tabs
...
} Data Types:
•
•
press-release
press-release-with-tabs
xslt
Data Category: xslt
}
product
... Data Types:
tasklist • product
...
weather • tasklist
... • weather
yacht • yacht
...
Perform the following steps to set up the example templating environment. You must
copy these files and directories to locations that are specific to your site.
1. Decide which workarea you will use for the initial FormsPublisher setup. Ideally,
this workarea should be on a temporary test branch where you can submit and
publish without affecting the rest of your TeamSite installation. After
FormsPublisher is configured in a workarea on this test branch, you can copy the
workarea to a permanent branch pertaining to your web site. You can then submit
the workarea to the staging area and use Get Latest to propagate the setup to other
workareas on the branch.
2. Read each directory’s README file for details about directory contents and
last-minute information that might not be documented elsewhere.
Interwoven, Inc. 24
Chapter 1: Overview of FormsPublisher
3. Copy the following file to the specified location, ensuring that all users have read
and write permission for each file:
Copy: To:
iw-home/examples/Templating/ The workarea determined in step 1. Copy the
templatedata entire templatedata directory tree, including
the templatedata directory itself. Do not
change any directory or file names. The end
result should be
workarea_name/templatedata/... as shown
on page 23.
Check with your system administrator to determine whether a workarea has already
been set up and if files have been copied into it.
4. Edit the templating.cfg file, changing the value of the vpath-regex attribute in
the <branch> element in each data category from
"specify_branches_where_FormsPublisher_is_used" to ".*" or a more
restrictive regular expression.
5. If you need to integrate workflow with FormsPublisher, edit
available_templates.cfg as described in the next section, “Editing
available_templates.cfg to Initiate Workflows”.
After you perform these tasks, the example templating environment is fully functional.
Workflow files that allow authors to submit data records were installed in the applicable
directories during the FormsPublisher installation. You can use the example templating
environment to create or edit data records, generate HTML files by combining a data
record with a presentation template, and deploy a data record’s extended attributes to a
database using TeamSite workflow and DataDeploy. See Chapter 5, “Integrating
FormsPublisher, DataDeploy, and Workflow,” for more information about integration
with workflows and DataDeploy.
This <template_file> section says that when authors submit a data record, they will be
prompted to initiate a workflow job using the configurable_author_submit.wft
workflow. If multiple workflows are available for an action, the author is prompted to
select a workflow.
Interwoven, Inc. 26
Chapter 1: Overview of FormsPublisher
NOTE
End users must have administrator privileges on their Windows client machine in order
for VisualFormat to install successfully.
You can insert a link to open a data capture template for a specified category and type in
the specified workarea. Use the syntax:
http://server/iw-cc/newform?vpath=pathname&iw_tdt=category/type
where server is the name of the TeamSite server, pathname is the path to your area
(such as /default/main/br/WORKAREA/wa), and category/type is the FormsPublisher
data category and type (such as internet/PressRelease).
To insert a link to edit a data record or an output page, use the syntax:
http://server/iw-cc/edit?vpath=filename
This link can be hard-coded anywhere you need a link to FormsPublisher, such as in a
Web site, a presentation template, or an HTML-formatted email. See the TeamSite User
Interface Customization Guide for information on other types of links. You can also use
the iwov_webdesk_url tag to include links in presentation templates. Refer to the online
documentation for this tag (in iw-home/httpd/iw/help/tst/pt) for details.
Starting FormsPublisher
Perform the following steps to start FormsPublisher after you have configured the
example templating environment:
1. Refresh the browser within TeamSite.
2. Select a new form.
NOTE
When using FormsPublisher on a MacIntosh client with Mozilla browsers, pop-ups
cannot be blocked. Verify by selecting Mozilla > Preferences > Privacy and Security >
Popup Windows. The Block unrequested popup windows field should not be checked.
NOTE
Most of the references in this manual refer to users of ContentCenter Standard or
ContentCenter Professional; however, the same information should apply to users
accessing FormsPublisher in other ways.
Interwoven, Inc. 28
Chapter 2
This chapter describes how to edit and create data capture templates. It is assumed that
the example templating environment’s directory structure exists on your system and that
you now intend to customize this environment by creating new data capture templates.
See Chapter 1, “Overview of FormsPublisher,” for more information about the example
templating environment’s directory structure.
The following list describes some of the characteristics of data capture forms that you
can configure in a datacapture.cfg file.
The number and appearance of data capture fields in a data capture form.
The content and appearance of labels for each data capture field in a data capture
form.
How data will be captured, such as through a check box, radio button, or text field.
Characteristics of the data entered in each section’s fields, including maximum
length and whether the data is text or image.
Editing capabilities for text areas.
A description of the field or the format of its content.
The fields, if any, that must be filled in before the data entry form can be saved.
The fields that can only be filled in by a specific content contributor.
The data entry fields that can be displayed multiple times in the same data capture
form, and the number times the fields can be displayed.
The scripts that should be called to enhance the way content contributors enter data.
When a content contributor finishes filling in a data capture form and selects Save, the
data capture subsystem combines the newly entered data with the XML rules defined in
the datacapture.cfg rule sets. If a DTD is available, it is also used to create the XML
file. The end result is a data record that is an XML file that associates field names from
the data capture form with the values that were entered in those fields by the content
contributor.
Data capture templates should validate against the datacapture6.0.dtd file, which can
be found at iw-home/local/config/datacapture6.0.dtd. Use the iwxml_validate
CLT to validate your data capture templates.
However, a validated template is not necessarily a valid file. If you are using data
capture templates created in Release 5.5.2 or earlier, they are still valid if they have
dcr-type='iwov' specified in the templating.cfg file. You can validate these files
against datacapture5.0.dtd.
If the data capture forms from TeamSite Templating 5.5.2 or earlier were created from
your DTD and have dcr-type='xml' specified, these templates are no longer valid.
After you validate your template, you should also verify it using the iwdctverifier
CLT. This CLT checks for common errors made when developing templates.
Another example is provided in “Using the viewoptions Element” on page 88 that shows
how to take advantage of some of the customization functionality.
Interwoven, Inc. 30
Chapter 2: Setting Up Data Capture Templates
The examples in the internet and intranet directories are of the “IWOV” data capture
type. These are maintained for compatibility with previous TeamSite Templating
versions.
1. The DTD system identifier points to the location of the DTD. This statement is
required if you want to have the data record comply with the DTD. The example
shows the URL using localhost. It is good practice to replace this with the
complete URL so the DTD can always be located.
2. The <ruleset> element provides the name of the data capture form.
3. The <root-container> represents the root node of the resulting XML. The
location attribute of this element is the name of the resulting root node.
4. The <container> with the label Heading contains a Title item. The text provided
using <description> displays when the user clicks the ? icon on the form.
Interwoven, Inc. 32
Chapter 2: Setting Up Data Capture Templates
9. A new and-container named Body that has at least one instance and can be
duplicated up to 20 times by the user.
10. The Body container contains required items labeled IWSubElements, Section, and
Subheading for the user to enter information about the press release.
11. The Body container also contains required items labeled Paragraph for the user to
enter information about the press release. The Paragraph item is a text area that
uses the VisualFormat editor.
12. All elements in the datacapture.cfg are closed.
Interwoven, Inc. 34
Chapter 2: Setting Up Data Capture Templates
Figure 8 Press release data capture form (with data and VisualFormat tool bar)
When this file is saved in the data directory, the resulting data record in XML format is
as follows:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE press-release SYSTEM "http://localhost/iw/pr.dtd">
<press-release>
<body>
<section>
<paragraph>
<p>A new candidate enters the race as of 9/23/04.</p>
</paragraph>
<subheading>Mayoral Race</subheading>
</section>
</body>
<head>
byline author="great.writer" location="IL"/>
<title>Candidate Joins Race</title>
</head>
</press-release>
<!ELEMENT root-container(label?,((tab)+|(container|item|
choice|dialog)+))>
<!ATTLIST root-container
name CDATA #REQUIRED
combination (and | or) "and"
location CDATA #REQUIRED
>
Interwoven, Inc. 36
Chapter 2: Setting Up Data Capture Templates
<!ATTLIST container
name CDATA #REQUIRED
combination (and | or) "and"
min CDATA "1"
max CDATA "1"
default CDATA "1"
location CDATA #IMPLIED
refid CDATA #IMPLIED>
eaSaveFormat (withInstanceNums | withoutInstanceNums)"withInstanceNums"
<!-- @eaSaveFormat: Tag UI specific for EA compatibility.
withoutInstanceNums only applies when min==max==1. -->
>
<!-- validation-regex is a regex for validating this element -->
Interwoven, Inc. 38
Chapter 2: Setting Up Data Capture Templates
>
<!-- The delimiter attribute is for multiple=t only -->
<select>
<inline command="command name" />
</select>
runs the "blah" callout program, and that program returns this text:
<substitution>
then the DCT snippet will, after callout execution and inline
substitution, look like:
<select>
<option label="ABC" />
<option label="123" />
<option label="Jackson 5" />
</select>
-->
<!ELEMENT inline EMPTY>
<!ATTLIST inline
command CDATA #REQUIRED
>
<!-- window-features is ignored if dialog type is button. function and
function-param can only be used if
dialog type is a button. Function name should not contain braces and
arguments. -->
Interwoven, Inc. 40
Chapter 2: Setting Up Data Capture Templates
<!ATTLIST field-ref
name CDATA #REQUIRED
>
DCT Identifier
The <data-capture-requirements> element lets you assign a unique identifier for each
data capture template. Exactly one <data-capture-requirements> element is required
in a datacapture.cfg file. The information in a <data-capture-requirements>
element is for reference only. None of the information in this element is stored in the
data record that is created when the datacapture.cfg file is processed by the data
capture subsystem. The name attribute within a <data-capture-requirements> element
is optional. The <dtd-system-identifier> is a URI indicating the DTD where the
<data-capture-requirements> were derived. The value of this attribute is used as the
system identifier of the document type declaration when a data record type is defined as
xml in the templating.cfg file and is used for constructing the XML during the save
process and for validating the data record when it is saved; it is stored in the <!DOCTYPE
preamble of the resulting XML data record.
The dcr-validation attribute results in the data record being validated when it is saved
from the data capture form. The values are:
none: No validation is performed when the data record is saved (default).
accept-invalid: The data record is validated against a given DTD. The relevant
DTD location is specified using the dtd-system-identifier attribute of
data-capture-requirements. If the data record is invalid, the data record is saved
with an .invalid extension and the user is warned.
reject-invalid: The data record is validated against a DTD. The relevant DTD
location is specified using the dtd-system-identifier attribute of
Rule Set
The <ruleset> element contains the items that make up the rule set that defines the
appearance and behavior of the data capture form. A datacapture.cfg file must contain
exactly one <ruleset> element. The name attribute within a <ruleset> element is
required. The value of the name attribute appears as the name of the data capture form
(Press Release as shown on page 31).
Root-Container
The <root-container> is a required node that maps to the root element. The name and
location attributes are required. For combination, you can specify whether it is an and
or an or container; the default is and. Use an or-container to specify that the user is
prompted to specify which items are to be duplicated. Use an and-container to specify
that the entire set of items will be duplicated. If its combination is not or, the
root-container will not be shown in the data capture form. Unlike the <container>
element, the <root-container> element cannot have max and min attributes.
Interwoven, Inc. 42
Chapter 2: Setting Up Data Capture Templates
Script
The <script> element is used for FormAPI scripts. Refer to TeamSite FormsPublisher:
FormAPI Developer’s Guide for information.
Tab
FormsPublisher data capture forms can be configured to contain one or more tab views
containing groupings of similar items. The <tab> element in datacapture.cfg
configures the tab feature. The name attribute within the <tab> element is displayed as a
tab name.
The tab feature only supports the XML data record style. The IWOV data record style is
not supported.
NOTE
The location and pathid attributes must be globally unique in a <tab> element.
Container
A <container> is a named set or grouping of data capture items. A <container> should
be used as a method for grouping a set of items. Items in a container are contained
within a visible box in the data capture form.
The following attributes are used with a <container> to specify a repeatable instance (a
replicant) that can contain multiple nested items and instances. Whenever additional
iterations of the instance can be displayed (that is, if the max threshold has not yet been
reached), the Insert icon is active. Whenever iterations of the instance can be removed
(that is, if the min threshold has not yet been reached), the Delete icon is active.
name: The name of the container that displays in the data capture form.
default: The number of the container is displayed initially in the data capture form.
max: The maximum number of the <container> element that can reside within the
data capture form. If not specified, max defaults to 1. If there is no limit on the
number of instances, max should be unbounded. If a value is not specified for max,
users may attempt to add so many containers that they run out of memory.
min: The minimum number of the <container> element that must reside within the
data capture form.
combination: Specifies whether the entire set of items will be repeated when the
user requests another set (and) or whether the user will be prompted to select one of
the items (or). The valid values are or and and.
location: Name of a complex XML element to which the container corresponds;
applicable to XML-style data records only. See “Scoping Rules” on page 64 for
information on location.
refid: Matches the refid from an <itemref> element. This is applicable only in
cases of recursive references.
eaSaveFormat: Specific to the next generation Tagger GUI. See the “Next
Generation Tagger GUI” appendix in the TeamSite Administration Guide for more
information.
If a <label> is defined, it displays as the label in a form, and all visible references to the
container will use the label. The value for name is used for all FormAPI operations,
while the value for <label> is only used for display in the form. A <label> should
always work for internationalization; name is not guaranteed to.
Choice
Each <choice> element is equivalent to a <container combination ='or'> with no
location and with min or max values equal to 1. Because <choice> does not have a
location, it can be rendered more compactly.
Since FormsPublisher does not support subsequent elements that do not have a location
(where neither the parent element nor the child element has a location), nesting two
<choice> elements is not supported.
Interwoven, Inc. 44
Chapter 2: Setting Up Data Capture Templates
Incorrect use of location and/or pathid attributes inside and outside of <choice>
elements can result in data loss when saving and reloading data record (DCR) data. To
avoid this problem, be sure that the location and pathid attributes are uniquely
specified in the data capture template (DCT) for all items and containers at the same
level as the choice, and for all children items and containers of the choice.
Notice that the saved data record contains two <myItem> nodes - each one with a
different fundamental data type, but with the same node name. Because these nodes in
the data record have the same name but different definitions and locations in the DCT,
they are indistinguishable. This ambiguity, caused by the illegal usage of location and
pathid, can cause data to fail to load properly.
See “XML Mapping” on page 60 and “Reducing Nested Containers” on page 64 for more
information about non-located containers and how they are processed by
FormsPublisher.
Itemref
The <itemref> element can only appear as a child of an or-container or a <choice>
element. It can only refer to ancestor nodes. It has a refid attribute that corresponds to a
matching refid attribute on a target container. It also has a label attribute and min and
max attributes.
Item
An item is a single set of data (that is, a single field on the form) that is to be captured
from a content contributor. A rule set must contain at least one item. Items can be nested
within containers. Each item must contain one or more instances (see “Instance” on
page 47 for more information).
The optional subelements for <item> are <label> and <description>. The <label> and
<description> subelements consist of character data. The information provided by
<label> is used as the field name in the data capture form. A <description> provides
more details about what the data capture item represents or the format that may be
required for data entry and displays when the user clicks the ? next to the field label.
The max attribute specifies the maximum number of <item> elements that can be
contained within the data capture form. Use this setting to limit the number of
replicants that a form can contain.
The min attribute specifies the minimum number of <item> elements that must be
contained within the data capture form. Use this setting to control the minimum
number of replicants that a form must contain.
The default attribute specifies the initial number of replicants that display in
the form.
The pathid attribute specifies the XML node that the item refers to. See “Scoping
Rules” on page 64 for information on pathid and location attributes.
The isTitle attribute specifies whether the content of the item’s first-level replicant
is displayed in the item’s title at the top of the replicant group. If set to t, the first
replicant’s content is displayed in the title. If set to f, replicant content is displayed
in the normal content areas.
If a rule set contains more than one item, item names must be unique within any given
nesting level; that is, siblings cannot have the same item name. For example, the
following syntax is illegal because it uses the item name Section twice in the same
nested section in the <ruleset> element:
<ruleset name="Press Release">
<root-container name = "Press-Release" location = "press-release">
<item name="Section" pathid = "section">
<text size="40" maxlength="100">
</text>
</item>
<item name="Section" pathid = "section">
<text size="80" maxlength="200">
Interwoven, Inc. 46
Chapter 2: Setting Up Data Capture Templates
</text>
</item>
</root-container>
</ruleset>
However, the following syntax is legal because it uses the item name Section in
different nested sections:
<ruleset name="Press Release">
<root-container name = "Press-Release" location = "press-release">
<container name="Morning Edition" max="4">
<item name="Section">
<text size="80" maxlength="200">
</text>
</item>
</container>
<container name="Evening Edition" max="4">
<item name="Section">
<text size="100" maxlength="400">
</text>
</item>
</container>
</root-container>
</ruleset>
Instance
The term instance is used conceptually throughout this document. There is not an actual
element named <instance> in a datacapture.cfg file. As used in this document,
instance refers to any section in datacapture.cfg defined by one of the following
elements:
<browser>
<checkbox>
<hidden>
<radio>
<readonly>
<select>
<text>
<textarea>
An instance defines how to capture data for an item. An instance can also define an ACL
that determines which (if any) instance a specific user is allowed to use to enter data.
Interwoven, Inc. 48
Chapter 2: Setting Up Data Capture Templates
Interwoven, Inc. 50
Chapter 2: Setting Up Data Capture Templates
This section provides additional details on the attributes and subelements described in
the instance table.
Example 1
The following code allows all users having the role of editor to select checkboxes for
the item “abc” in the data form:
<item name= "abc">
<checkbox>
<allowed> <cred role="editor"/> </allowed>
</checkbox>
</item>
Example 2
The following code allows all members of the engineering TeamSite group to enter
text for the item “abc” in the data form:
<item name= "abc">
<text>
<allowed> <cred group="engineering"/> </allowed>
</text>
</item>
Example 3
The following code allows all users except joe to use the current instance:
<allowed>
<not>
<cred user="joe"/>
</not>
</allowed>
Interwoven, Inc. 52
Chapter 2: Setting Up Data Capture Templates
Example 4
In the following example, <allowed> lets just editors enter text for the item “abc” in the
data form. Users having any role other than editor can only select checkboxes for the
“abc” item. The first instance a user satisfies is the one that is used.
<item name= "abc">
<text>
<--only for editors-->
<allowed> <cred role="editor"/> </allowed>
</text>
<checkbox>
<!--for everyone else-->
</checkbox>
</item>
Example 5
The following example shows how to prohibit multiple roles from editing a field. If the
<or> statement is not included, only the first role is not allowed.
<allowed>
<not>
<or>
<cred role='master'/>
<cred role='admin'/>
<cred role='editor'/>
<cred role='author'/>
<cred role='reviewer'/>
</or>
</not>
</allowed>
Example 6
The following code segments show some examples of using <allowed> with
<readonly>. The <readonly> tag makes a field read-only to certain users, which means
that they can only read it, and they cannot write to it.
This example says that only the user chris gets a text field for the Headline. Implicitly,
it is read-only for everybody else.
<item name="Headline">
<text>
<allowed><cred user="chris"/></allowed>
</text>
</item>
Example 7
The functionality of the preceding example is identical to that of the following example
that includes the <readonly> element:
<item name="Headline">
<text>
<allowed><cred user="chris"/></allowed>
</text>
<readonly/>
<!-- Absence of an <allowed> tag means "everyone". -->
</item>
To reverse it so the user chris gets a read-only field and everyone else gets a text box,
use:
<item name="Headline">
<readonly>
<allowed><cred user="chris"/></allowed>
</readonly>
<text/>
</item>
Example 1
The following code limits access to a required text area. Master users can see the text
area and must fill it out, but nobody else can see the field. Users who are not allowed to
see this text area will not be forced to fill it out and will be able to save the data record
even though the value for the text area is not set.
<item name="SecretComments">
<textarea cols="15" rows="10" required="t">
<allowed>
<cred role="master" />
</allowed>
</textarea>
<hidden/>
</item>
Interwoven, Inc. 54
Chapter 2: Setting Up Data Capture Templates
Example 2
The following code also limits access to a required text area. In this case, everyone
except Master users can see the text area and must fill it out. Master users will be able to
save the data record even though the value is not set.
<item name="SecretComments">
<hidden >
<allowed>
<cred role="master" />
</allowed>
</hidden>
<textarea cols="15" rows="10" required="t" />
</item>
Example 3
The following code requires an Author to enter a value for a hidden field (for example,
through a callout button). Masters, Administrators, and Editors may enter a value but
are not required to.
NOTE
Use this functionality with extreme caution. Requiring users to enter information when
they cannot see that the information is required can severely impair usability.
<item name="SecretComments">
<hidden required="t" >
<allowed>
<cred role="author" />
</allowed>
</hidden>
<textarea cols="15" rows="10" / >
</item>
Example 4
In the following code, all users are required to have a value in the text area. However,
the text area is hidden for Authors. In this scenario, an Editor, Administrator, or Master
user would create the data record and set a hidden field, and only then would Authors be
able to edit and save the data record. Authors cannot save this data record if the hidden
field has not been pre-filled.
NOTE
Use this functionality with extreme caution. Requiring users to enter information when
they cannot see that the information is required can severely impair usability.
<item name="SecretComments">
<hidden required="t" >
<allowed>
<cred role="author" />
</allowed>
</hidden>
<textarea cols="15" rows="10" required="t"/ >
</item>
The following table identifies the editing and formatting capabilities on various client
platforms.
VisualFormat
You may specify a configuration file to be used with VisualFormat for a specific text
area. Refer to Appendix A, “Configuring VisualFormat,” for information on creating
configuration files. The name of the configuration file is specified with the
<external-editor-config> attribute. If that attribute is not set, the default file
/httpd/iw/visualformatconfig.xml is used.
TinyMCE
TeamSite supports TinyMCE as an alternate text editor for formatting and filling in
fields in data capture forms.
Interwoven, Inc. 56
Chapter 2: Setting Up Data Capture Templates
The <inline> element is shown in the DTD for the <checkbox>, <radio>, and <select>
elements. The <inline> element cannot contain <cred> subelements or additional
<inline> elements.
The inline callout program should return a well-formed XML document. The
document's outermost element should be a <substitution> element. It should contain
any XML that is valid according to datacapture5.0.dtd. That <substitution>
element will contain six <option> elements, enumerating a variety of types of yacht hull
materials.
<?xml version="1.0" encoding="UTF-8"?>
<substitution>
<option value="Lead" label="Lead"/>
<option value="Tin" label="Tin"/>
<option value="Silicon" label="Silicon"/>
<option value="Plastic" label="Plastic"/>
<option value="Paper" label="Paper"/>
<option value="Glass" label="Glass"/>
</substitution>
This simple callout outputs a static result. A more sophisticated callout program could
query a database and return the query results as <option> elements.
IW_ROLE: The role of the current data capture user (for example, editor).
IW_USER: The domain and full user name of the current templating user (for
example, domain\andre).
IW_WORKAREA: The vpath to the current workarea (for example,
//servername/default/main/development/WORKAREA/chris).
The exit status from a server-side inline callout should be 0 to indicate a successful
execution. Normally an inline callout should not return a non-zero value. However, an
example where a non-zero value may be needed to indicate an error condition is if you
are populating a <select> menu by making a database query and the database is offline.
Rather than displaying a form with no choices, you may prefer an exception be
displayed.
If the behavior of a read-only text or textarea field is not as expected, try the following
options.
Similarly, if a text field becomes a textarea field with the addition of the <readonly>
tag:
Do not use the <readonly> tag in the text field.
When the form renders, get the item and set it to read-only using FormAPI as shown
in the preceding code.
Dialog
The main functions of the <dialog> element are described in Appendix B, “ECM
Connector,” in the TeamSite Administration Guide. The <dialog> element has been
extended to provide the following additional features.
The type attribute now accepts a value of button, which allows the addition of a
configurable button in a data form.
An additional attribute, function, allows you to specify any Javascript function to
call when the button is clicked. This attribute is used together with the <script>
element as shown in the following examples.
An addition element, <function-param>, lets you specify information to pass as a
function argument for the Javascript function named in function.
Interwoven, Inc. 58
Chapter 2: Setting Up Data Capture Templates
Example 1
The following example specifies a button in a data form that calls jsFunctionName when
clicked.
<dialog type="button" label="Add" function="jsFunctionName"
rowcontinue="t">
</dialog>
……
<script>
Function jsFunctionName()
{
alert();
}
</script>
Example 2
NOTES
The function attribute and <function-param> element can only be used if dialog
type is button.
The function name represented above by jsFunctionName must not contain braces
or arguments.
See “Data Capture Template DTD” on page 36 for additional information.
XML Mapping
This section provides examples and discussion about how differences in the
datacapture.cfg file can generate different XML data record output. It also shows
usage of the location and pathid attributes.
Containers have a location that is usually the name of a complex XML element to which
they correspond. A complex element is an element that has attributes, children, or both.
The location attribute indicates the element node to be replicated if the attribute max is
set to a value greater than 1 (that is, what XML node is replicated) and provides a
relative location onto which child items can be scoped.
Items similarly have a slightly more complex attribute called pathid which specifies
either an attribute or a simple element. The meaning of the pathid is either to create an
attribute node on an element or to create an element node with a value set to the value of
the item.
NOTE
See “Choice” on page 44 and “Reducing Nested Containers” on page 64 for more
information about code containing both located and non-located nodes.
Example 1
Interwoven, Inc. 60
Chapter 2: Setting Up Data Capture Templates
NOTES
Containers other than the root-container were not needed.
The complexity of the data capture template is of similar complexity to an instance
XML document.
The name attribute is still present and is a required attribute.
A DTD was not required, in which case, the order of the <first> and <last> nodes
was not specified and is not guaranteed.
Example 2
This DCT is almost identical to Example 1, but the XML file is very different.
<data-capture-requirements>
<ruleset name='person'>
<root-container name="person" location="person">
<item name='firstname' pathid='@first'>
<label>Your First Name</label>
<text/>
</item>
<item name='lastname' pathid='@last'/>
<label>Your Last Name</label>
<text/>
</item>
</root-container>
</ruleset>
</data-capture-requirements>
NOTES
The attribute pathids that have the same element name (that is, person) refer to the
same instance of that node in the current scope. In other words, the output is
<person first='John' last='Doe'/> rather than
<person first='John'/><person last='Doe'/>.
When items are in a <container> element and begin with an @, they are implicitly
setting attributes on the parent node. In other words, the output is
<person first='John' last='Doe'/> rather than
<person><person first='John' last='Doe'/></person>.
The only change required to the data capture template to support an XML format
that is different from the previous example is modification of the pathid. Users of
the form would not be aware of a difference.
Example 3
This DCT is almost identical to Example 2, but it demonstrates how PCDATA items are
scoped.
<data-capture-requirements>
<ruleset name='person'>
<root-container name='person' location='person'>þ
<item name='firstname' pathid='@first'>
<label>Your First Name</label>
<text/>
</item>
<item name='lastname' pathid='@last'/>
<label>Your Last Name</label>
<text/>
</item>
<item name='age' pathid='#PCDATA'/>
<label>Your Age in Years</label>
<text/>
</item>
</root-container>
</ruleset>
</data-capture-requirements>
NOTES
Items whose pathids are #pcdata represent the PCDATA value of the parent.
Attribute pathids that have the same element name (that is, person) refer to the same
instance of that node in the current scope. In other words, the output is
<person first='John' last='Doe'/> rather than
<person first='John'/><person last='Doe'/>.
If you have #PCDATA in contiguous fields, when the data record is opened for
editing all fields will be combined into one field, which concatenates all the data
entered in the various fields. Because XML does not maintain boundaries between
#PCDATA nodes, there is no way to reconstruct the replicant instance boundaries.
To avoid this behavior, use a pathid that references an element, rather than
#PCDATA.
Interwoven, Inc. 62
Chapter 2: Setting Up Data Capture Templates
Example 4
NOTE
The firstname and lastname items are now scoped by the container surrounding them
rather than by the ruleset containing them.
Scoping Rules
Both items and containers can appear either at the root level of the data capture template
(that is, as a child of a <root-container>) or as children of <container> elements.
These scoping rules define the meaning of the location and pathid:
The values of pathid and location are always relative to the nearest parent element
that has a defined location attribute.
If a pathid is #PCDATA, the value of the parent container node is set to the value of
that item. See Example 3.
If the element section of a pathid referencing an attribute is omitted, the attribute is
set on the parent container node. See Example 2.
The following rules apply to the use of the paths in the pathid attribute of <item>:
Any section of the path, except the last part, must refer to a globally unique node.
Using such paths in items whose parent is a container with max greater than 1 results
in the creation of new nodes until the last section of the pathid.
Using such paths in items where the pathid refers to an attribute and the item has a
max greater than 1, results in creating a node for each attribute.
The following rules apply to the use of the paths in the location attribute of
<container> elements:
Any section of the path, except the last part, must refer to a globally unique node.
Using such paths in containers whose parent is a container with max greater than 1,
results in the creation of new nodes.
NOTE
See “Choice” on page 44 and “XML Mapping” on page 60 for more information about
code that contains both located and non-located nodes.
Interwoven, Inc. 64
Chapter 2: Setting Up Data Capture Templates
Example 1
This example shows the use of locations that are not abbreviated.
<data-capture-requirements>
<ruleset name='html'>
<root-container name='html' location='html'>
<container name='header' location='header'>
<item name='title' pathid='title>
<text/>
</item>
<container name='authors' location='authors'>
<item name='author' pathid='author' max='unbounded'>
<text/>
</item>
</container>
</container>
</root-container>
</ruleset>
</data-capture-requirements>
Example 2
Both Example 1 and Example 2 produce the same result in the data record:
<html>
<header>
<title>Dr. Strangelove: or How I Learned to Stop Worrying and
Love the Bomb</title>
<authors>
<author>Stanley Kubrick</author>
<author>Terry Southern</author>
</authors>
</title>
</header>
</html>
This example works only because <header> and <title> are simple and globally
unique. If <header> were more complex or if there could be more than one, it would
need to be represented with a <container>.
Item References
The rules for evaluation of item references, represented by the <itemref> tag, are:
The <itemref> must be the immediate child of a container whose combination
attribute is or or a <choice> node.
The target of the reference must be an ancestor node.
The target of the reference must define a location.
The reason for these restrictions is that unlimited nested recursion is supported for
recursively defined elements, and these restrictions ensure that no cyclical references
can occur that might cause an infinite loop.
Example 1
The simplest situation where itemref elements are used is to model simple recursive
elements. In this situation, a section is defined recursively as either a paragraph or a
subsection. At the beginning, a single section container appears that can either contain a
sequence of paragraphs or a section.
<container combination="or" name="section" location="section"
refid="section">
<item name="paragraph" pathid="para" max="unbounded">
<text/>
</item>
<itemref name="section_ref" refid="section"/>
</container>
or
<container name="section" location="section" refid="section">
<choice name="section_choice">
<item name="paragraph" pathid="para" max="unbounded">
<text/>
</item>
<itemref name="section_ref" refid="section"/>
</choice>
</container>
<section>
<section>
<paragraph>This is paragraph one of subsection one.</paragraph>
<paragraph>This is paragraph two of subsection one.</paragraph>
Interwoven, Inc. 66
Chapter 2: Setting Up Data Capture Templates
</section>
</section>
Example 2
Example 1 becomes more powerful by adding a max attribute to the section container.
<container combination="or" name="section" location="section" min="0"
max="unbounded" refid="section">
<item name="paragraph" pathid="paragrah">
<text/>
</item>
<itemref name="section_ref" refid="section"/>
</container>
or
<container name="section" location="section" min="0" max="unbounded"
refid="section" />
<choice name="section_choice">
<item name="paragraph" pathid="paragraph">
<text/>
</item>
<itemref name="section_ref" refid="section"/>
</choice>
</container>
Example 3
Example 2 showed how cumbersome nested sections can be; notice the difference when
each section is given a name attribute.
Because containers with combination="or" are logically both a list and a choice, this
situation must be represented differently than Example 8.
<container name="section" location="section" min="0" max="unbounded"
refid="section">
<container combination="or" name="section_choice">
<item name="paragraph" pathid="paragraph">
<text/>
</item>
<itemref name="section_ref" refid="section"/>
</container>
<item name="section_title" pathid="/@title">
<text/>
</item>
</container>
Interwoven, Inc. 68
Chapter 2: Setting Up Data Capture Templates
Example 4
This example shows a complex situation where a section can contain tables, paragraphs
and sections, and where tables can contain sections or tables.
<container combination="or" name="section" location="section" min="0"
max="unbounded" refid="section">
<item name="paragraph" pathid="para">
<text/>
</item>
<container name="table" location="table" refid="table">
<container name="row" location="tr" min="1" max="unbounded">
<container combination="or" name="cell" location="td" min="1"
max="5">
<item name="simple_cell" pathid="#pcdata">
<text/>
</item>
<itemref name="table_ref" refid="table" />
<itemref name="inner_section_ref" refid="section" />
</container>
</container>
</container>
<itemref name="section_ref" refid="section"/>
</container>
or
<container name="section" location="section" min="0" max="unbounded"
refid="section">
<choice name="section_choice">
<item name="paragraph" pathid="paragraph">
<text/>
</item>
<container name="table" location="table" refid="table">
<container name="row" location="tr" min="1" max="unbounded">
<container name="cell" location="td" min="1" max="5">
<choice name="cell_choice">
<item name="simple_cell" pathid="#pcdata">
<text/>
</item>
<itemref name="table_ref" refid="table" />
<itemref name="inner_section_ref" refid="section" />
</choice>
</container>
</container>
</container>
<itemref name="section_ref" refid="section"/>
</choice>
</container>
Interwoven, Inc. 70
Chapter 3
Setting Up Presentation
Templates
Presentation templates are designed to display data. The data may be obtained from the
following sources:
Data records
Queries to relational databases
Scripting-generated output
Included files
Included presentation components
The following diagram shows an example of how an output page may be generated
when data is obtained from a data record.
Standard Header –
using an included file instead of an shtml directive.
This included file can be changed
once and the entire site regenerated.
Image
Navigation
Caption
Body Text
Navigation
and Related
Links can be
obtained Body text, Image, and Related Links
from Caption are obtained
included files, from the data
included record using iw_xml
presentation tags and HTML code.
templates,
queries to a
database, or
from code
entered as
CDATA.
Standard Footer –
using an included file.
Interwoven, Inc. 72
Chapter 3: Setting Up Presentation Templates
Create custom libraries and invoke them from within the <iw_perl> tag (for
Perl-based presentation templates). Lower-level visual building blocks can be
accessed by programmers directly from a template.
Intermix XML and Perl or Java to generate any output format (such as html, asp,
and jsp). Presentation information does not need to be hard-coded into the template.
Make common code components reusable across templates.
Create generic components (component templates) that display differently based on
the parameters they are given by their enclosing template.
Eliminate page compilation costs on the production web server, thus increasing
scalability of your web site.
Use component templates. The component template may have key/value parameters
passed to it by the enclosing template. For example, a component template may
include an SQL query whose body depends on parameters from the enclosing
template. Component templates do not take a data record.
Use Java extensions and extension functions supported by Xalan-Java (XSLT PT
compiler only; see “Presentation Template Type and Construction”).
NOTE
When extracting values from a data record using a presentation template, the method for
doing so differs depending on the dcr-type attribute specified in templating.cfg.
When dcr-type="iwov" is specified, the presentation template should use item names
for extracting values from the record (for example, <iw_value name="item_xpath" />).
When dcr-type="xml" is specified, the presentation template should use the pathid for
extracting values (for example, <iw_value name="item_absolute_pathid" />).
The rest of this section describes how to configure FormsPublisher to use the PT
compiler of your choice, basic information about how to construct each type of
presentation template, and where to get more detailed information about writing
presentation templates.
Global Settings
The Perl PT compiler is set globally by default. If you do not change the PT compiler
settings in templating.cfg, the Perl PT compiler is used to process presentation
templates for all data types. The following line in templating.cfg sets this global
configuration:
<templating ptcompiler="com.interwoven.ui.formspub.utils.PerlPTCompiler">
To change the global setting so that the XSLT PT compiler is used for all data types,
change the preceding setting as follows:
<templating ptcompiler="com.interwoven.ui.formspub.utils.XSLTPTCompiler">
Data-Type-Specific Settings
To override the global PT compiler setting for a data type, set the ptcompiler attribute
within that data type’s template element to the PT compiler of your choice. For
example, to use the XSLT compiler to render presentation templates for the “product”
data type, set the ptcompiler attribute as follows:
<data-type name="product" dcr-type="xml">
<presentation>
<template name="product.xsl" extension="html"
ptcompiler="com.interwoven.ui.formspub.utils.XSLTPTCompiler">
Or, to specify that the Perl PT compiler be used for a data type, the appropriate setting
would be:
ptcompiler="com.interwoven.ui.formspub.utils.PerlPTCompiler">
Interwoven, Inc. 74
Chapter 3: Setting Up Presentation Templates
Custom Compilers
A URL command is also provided to generate (but not preview) display data.
Syntax is:
http://hostname/iw-cc/urlgenerate?dcr=dcr_name&pt=pt_name&output=output_n
ame
If the generated HTML file already exists, you can overwrite it with a new file of the
same name using the following command:
http://hostname/iw-cc/urlgenerate?dcr=dcr_name&pt=pt_name&output=output_n
ame&override=true
Perl PT Compiler
NOTE
Perl presentation templates cannot be used for non-OS users or when the utility daemon
runs as a non-root user.
Presentation templates processed by the Perl PT compiler are written in any format and
may contain custom Interwoven XML tags, HTML, and Perl. If the tag <iw_pt
encoding='...'/> is used at the beginning of the file or is omitted entirely, everything
that is not a presentation template tag will automatically behave as if it were inside a
CDATA section.
Typical man pages are available online for each tag. If iw-home/iw-perl/bin is in your
path statement, you can access these man pages by issuing the command perldoc
TeamSite::PT::tag_name.
XSLT PT Compiler
If you write your own XSL files to create additional XSLT presentation templates, they
must be well formed and must conform to the syntax and semantics defined in XSL
Transformation Version 1.0 (http://www.w3.org/TR/xslt). It is recommended that you
ensure that the input HTML code in each XSL file is well-formed by using a
commercially available tool for converting plain HTML to XHTML.
NOTE
The XSLT PT compiler also supports the Xalan-Java extensions and extension library.
See http://xml.apache.org/xalan-j/extensions.html for details about the
extensions and declaring the Xalan-related namespaces.
Interwoven, Inc. 76
Chapter 4
This chapter describes how the templating.cfg file maps the interaction between
content contributors, data capture templates, presentation templates, and data records.
Sections in this chapter discuss the following:
templating.cfg Overview
Example templating.cfg File
Templating DTD
Explanation of templating.cfg Based on the DTD
Setting Previewing Path Variables
Using the viewoptions Element
templating.cfg Overview
The templating.cfg file is an XML file that resides outside of the TeamSite file system
in iw-home/local/config. Each FormsPublisher installation must have exactly one
such file. By configuring templating.cfg, you can control:
The type of data record being produced (iwov or xml).
The data categories and types that FormsPublisher can use.
The presentation templates that can generate HTML files on specified branches or
directories.
The presentation templates that can be used with a specific data type.
The users or roles that are allowed to create or edit data records for a specific data
type.
The location of the presentation template used for previewing generated HTML
files.
The method for naming data records, including whether automatic DCR naming is
to be used.
The links that display on the screen.
This is the templating.cfg file that configures the example templating environment
described in Chapter 1, “Overview of FormsPublisher.” During installation, this file is
installed in your iw-home/local/config directory. If a file by this name already exists,
the new file is installed as templating.cfg.example. The file configures
FormsPublisher to recognize and use the following data categories/types:
ecm/press-release
ecm/press-release-immediate
ecm/press-release-iwov
intranet/deptinfo
intranet/weather
internet/careers
internet/auction
internet/pr
internet/book
internet/medical
internet/yacht
userscript/contact
userscript/location
userscript/organization
userscript/position
xml/press-release
xml/press-release-with-tabs
xslt/product
xslt/tasklist
xslt/weather
xslt/yacht
The following section shows a subset of this file with sections for the deptinfo,
weather, auction, pr, contact, location, and press-release data types.
See the diagram key on page 81 for a summary about items referenced in the
templating.cfg file. See “Explanation of templating.cfg Based on the DTD” on page 83
for an explanation of the templating.cfg file elements and attributes.
NOTE
The templating.cfg file must use either a UTF-8 or ISO-8859-1 encoding
declaration.With any other encoding, Preview and Generate operations fail with a
“malformed templating.cfg” error.
Interwoven, Inc. 78
Chapter 4: Mapping Users, Templates, and Content Records
1 <templating>
<category name="intranet">
2
<locations>
<branch vpath-regex=
"specify_branches_where_FormsPublisher_is_used"/>
</locations>
3 <data-type name="deptInfo" dcr-type="iwov">
<presentation>
<template name="deptInfo.tpl" extension="html">
<locations>
<branch vpath-regex=".*" preview-dir="/">
<directory dir-regex=".*" />
</branch>
</locations>
</template>
</presentation>
</data-type>
4 <data-type name="weather" dcr-type="iwov">
<presentation>
<template name="weather.tpl" extension="html">
<locations>
<branch vpath-regex=".*" preview-dir="/">
<directory dir-regex=".*" />
</branch>
</locations>
</template>
</presentation>
</data-type>
</category>
<category name="internet">
5
<locations>
<branch vpath-regex=
"specify_branches_where_FormsPublisher_is_used" />
</locations>
6 <data-type name="auction" dcr-type="iwov">
<presentation>
<template name="auction.tpl" extension="html">
<locations>
<branch vpath-regex=".*" preview-dir="/">
<directory dir-regex=".*" />
</branch>
</locations>
</template>
</presentation>
</data-type>
Interwoven, Inc. 80
Chapter 4: Mapping Users, Templates, and Content Records
Diagram Key
1. The <templating> element identifies the file as a templating.cfg file.
2. The intranet category. Notice that you need to enter the branches for the location;
no default branches are set in this file.
3. The deptInfo data type in the intranet category; with the name of the presentation
template to be used.
4. The weather data type in the intranet category.
5. The beginning of a new category—internet.
6. The auction data type in the internet category.
7. The pr data type in the internet category. Three presentation templates are
identified, using the <template> attribute, as being available for this data type.
8. The beginning of userscript category. Forms in this category demonstrate
FormAPI usage.
9. The contact data type in the userscript category.
10. The location data type in the userscript category.
11. The xml category that contains the press-release data type. This has
dcr-type='xml' and reflects the use of the datacapture6.0.dtd.
Templating DTD
The templating6.0.dtd file is as follows:
Interwoven, Inc. 82
Chapter 4: Mapping Users, Templates, and Content Records
Templating Element
The <templating> element is the root element and marks the beginning of the
templating.cfg file’s configuration information and identifies the file as a
templating.cfg file.
The <category> element contains one or more <data-type> elements. A data category
must have its own <category> element in templating.cfg in order for FormsPublisher
to recognize and use the data category. Even if a data category is located correctly in the
directory structure described on page 17, it will not be recognized by FormsPublisher
unless it is named in a <category> element as shown here. The <category> element’s
name attribute is required.
Use the <locations> element within a <category> element to show the branches in
which that category will be available. Note that the location for the category needs to
be specified to list the branches where FormsPublisher is installed. This is especially
important if you have users of ContentCenter Standard to prevent them from getting a
long duplicated list of forms. If you want all branches to be included, you can use the
syntax <branch vpath-regex=".*">.
Interwoven, Inc. 84
Chapter 4: Mapping Users, Templates, and Content Records
<allowed>: Lets you set an ACL to specify which users can or cannot use a specific
data type. If <allowed> is not set, any user can use the data type (see page 52 for
additional examples). The <allowed> element can have any of the following
subelements:
<cred>: Lets you name a user, role, or group in the ACL (for example,
user="joe" or role="master"). A role specified in the <cred> subelement
matches the role of the user if that role exists as a member of the set of roles
possessed by the logged-in user. A group specified in the <cred> subelement
matches the user’s group if that group exists as a member of the set of groups
that the logged-in user belongs to.
<and>: Logical and statement for grouping ACL credentials.
<or>: Logical or statement for grouping ACL credentials.
<not>: Logical not statement for negating ACL credentials. For example, the
following allows all users except joe to use the current instance:
<allowed>
<not>
<cred user="joe">
</cred>
</not>
</allowed>
<viewoptions>: Provides information on how the form appears on the user’s screen,
and how the form can be named. The <viewoptions> element has the following
attributes:
actionlist: Lists the links that display on the data form. The valid tokens are
separted by a semicolon (;). Valid tokens are save, saveas, preview, generate,
settings. If this attribute is not specified, all links appear at the top of the
form.
showtree: Determines whether a field navigation tree displays on the left side of
the window.
dcr-renamable: Indicates whether users can rename a data record that was
named with dcr-autonaming. If this is set as f, the Form Settings link allows
prevents users from setting a different name for the form.
cssurl: Specifies the name of a style sheet that can be used to change the
appearance of that specific data capture form.The following example shows
using a full path name to specify the location of the .css file.
< data-type name="press-release" dcr-type="xml">
<viewoptions cssurl="http://server:port/style.css"
dcr-autonaming="t"/>
You can put the .css file on the webserver running on port 81. However, adding
the .css file to one of the workareas on the TeamSite server will probably not be
successful because you have to use the webserver to serve the .css file. Refer to
KB article 50537 at https://support.interwoven.com for an example .css
file.
dcr-autonaming: Enables unnamed data records to be saved with an
automatically generated file name.
The <template> element marks the beginning of the section that maps a presentation
template to a data type. It specifies which presentation templates are available for use
with the data type named in the <data-type> element. For example, the deptInfo.tpl
template is used to display data records for the deptinfo data type. The <template>
element can contain the following attributes:
extension: Specifies the extension that will be used on any files this template
generates. This attribute is required.
fullpage: Specifies that the generated HTML file is a full HTML page. This
attribute is optional.
name: Specifies the presentation template’s file name in the
workarea_name/templatedata/data_category/data_type/presentation
directory. This attribute is required.
The <branch> element uses extended regex syntax to specify on which branches a
presentation template can generate a file. The <branch> element can have the following
attributes:
vpath-regex: Specifies on which branches files can be generated using this
presentation template. The example shown here (".*") specifies that all branches
can have files generated by the deptInfo.tpl presentation template.
preview-dir: Specifies the directory (in an area of a branch) in which generated
files will be previewed when you preview a data record (using the FormsPublisher
Preview button).
The <directory> element uses regex syntax to specify where generated HTML files
based on this presentation template may be saved. For example, to specify that
Interwoven, Inc. 86
Chapter 4: Mapping Users, Templates, and Content Records
generated HTML files based on deptInfo.tpl will reside in the current directory, use
the notation ".*".
The way to configure FormsPublisher so that the correct directory is searched is to set
preview-dir in the templating.cfg file to point to the directory containing the file. For
example, set the preview-dir variable to /images if pixel.gif resides in /images.
Then pixel.gif is found and displays during the preview.
The preview-dir variable (in the templating.cfg file) associated with each
presentation template defines the directory where the preview file virtually exists during
preview time. A preview creates temporary files that are generated in the preview-dir
directory. When a browser is opened and directed to the preview file, the URL that the
browser points to is the URL for the preview file in the directory defined in
preview-dir.
Many of the examples suggest removing the change that was just made to return the
form to its original. If you choose not to do that, your examples may be different.
1. Open the weather form and enter data in the Announcement field, as shown:
Figure 10 Weather Data Record with data
2. Click the Save button and save this form as today.xml in the data directory.
URL Commands
URL commands let authors access FormsPublisher directly from a published intranet
page or HTML-formatted email by clicking one or more URL links to the source file.
The following URL Command opens the weather form in ContentCenter Standard.
http://host-name/iw-cc/newform?iw_tdt=intranet/weather&vpath=wa-name
where:
wa-name is the name of the workarea where the author is creating this new record.
Interwoven, Inc. 88
Chapter 4: Mapping Users, Templates, and Content Records
The following URL command would let the author edit the weather form today.xml.
http://host-name/iw-cc/edit?vpath=dcr-path-name
where:
dcr-path-name is the path to the data record for the author to edit.
Refer to the TeamSite User Interface Customization Guide for more information about
URL commands.
This list does not determine the order in which the links are displayed in the form.
The Form Settings dialog box is affected by this configuration. If Generate is
hidden for a particular data capture template, the Form Settings dialog box does not
show the panel where the user can select a path to the generated file. If both Preview
and Generate are hidden, the Form Settings dialog box just displays the panel for
selecting the path to the data record.
In view mode, only Preview and Generate display. If the configuration is set to hide
the Generate link, when a data record is opened in view mode, only the Preview
link displays.
Interwoven, Inc. 90
Chapter 4: Mapping Users, Templates, and Content Records
Auto-DCR functionality may be turned on for a specific category and type by setting the
dcr-autonaming attribute of the <viewoptions> element to "t" (true).
3. Click the Save link. The data record is saved as iwDCRnumber_timestamp without
prompting the user for a name. The Auto-DCR naming feature provides a unique
name for this data record. This can be overridden if the user selects the Save As link
(if available) or with a user-provided function in FormAPI. The screen showing the
assigned name appears:
Figure 15 Weather form showing an automatically generated name
Refer to the TeamSite FormsPublisher: FormAPI Developer’s Guide for further details on
auto-DCR naming capabilities.
Interwoven, Inc. 92
Chapter 4: Mapping Users, Templates, and Content Records
You can use the dcr-renamable attribute with the dcr-autonaming attribute to prevent
users from renaming data records. If you set dcr-renamable="f", users cannot rename
the data record. The Form Settings dialog box displays as shown in Figure 16, with the
Form Entry field not editable. The format of this code is:
<category name="intranet">
...
<data-type name="weather" dcr-type="iwov">
...
<viewoptions dcr-autonaming="t" dcr-renamable="f" />
</data-type>
...
</category>
Figure 16 Form Settings dialog box when the data record cannot be renamed
}
3. Open the templating.cfg configuration file. Navigate to the configuration
information about the weather type and add a viewoptions element as follows:
NOTE
The value of the cssurl attribute is the name and port number of the web server (for
example, http://server1:81). Do not place the overrideStyles.css file in a
workarea and point to it there. It must be served by the web server.
<category name="intranet">
...
<data-type name="weather" dcr-type="iwov">
...
<viewoptions cssurl="webservername:port\overrideStyles.css"/>
</data-type>
...
</category>
Save the templating.cfg file.
4. Open a new weather form and the screen appears as shown. Notice how the font
size and color of the description item changed.
Figure 17 Weather data capture template using a different style sheet
See the TeamSite User Interface Customization Guide for more information on style
sheets.
Interwoven, Inc. 94
Chapter 4: Mapping Users, Templates, and Content Records
NOTE
If you specify a collapsed mode, it is recommended that you enable the Expand All
Items and Collapse All Items buttons (displayed at the top of a data form). Enabling
this feature allows users to quickly expand fields that are initially collapsed. This feature
is disabled by default, so that the buttons are not displayed. Configuration of this feature
is controlled by the iw.formspub.expandall.enabled parameter in the
application_custom.xml file. That file is part of the UI toolkit and is described in
detail in the TeamSite User Interface Customization Guide.
If you specify collapsed mode, it is also recommended that you enable Data Record
Search so that users can search data records even when the records are collapsed. See
“Enabling Data Record Search” on page 97 for more information.
Interwoven, Inc. 96
Chapter 4: Mapping Users, Templates, and Content Records
Data Record Search is disabled by default, so that the text field and Search button are
not displayed. This is a global UI setting, with the configuration affecting all data record
displays. This setting is controlled by the iw.formspub.searchdcr.enabled parameter
in the application_custom.xml file. That file is part of the UI toolkit and is described
in detail in the TeamSite User Interface Customization Guide. Refer to that document for
information about enabling Data Record Search.
Interwoven, Inc. 98
Chapter 5
Integrating FormsPublisher,
DataDeploy, and Workflow
This chapter describes how to integrate FormsPublisher with DataDeploy and TeamSite
workflow. It contains the following sections:
Integration Overview
Integration Steps
Integration Overview
The following steps show the process to create, save, submit, and deploy a data record
when FormsPublisher and DataDeploy are integrated.
1. In TeamSite ContentCenter, a content contributor requests a new data record,
chooses a data category and type, and enters data in the resulting data capture form.
2. The content contributor saves the data capture form. FormsPublisher signals
OpenDeploy that a data record has been created or modified. OpenDeploy
synchronizes data with the database.
3. In TeamSite ContentCenter, the content contributor submits a data record.
FormsPublisher can be configured to automatically initiate a workflow process after
a particular user action as a convenience to the end user. This can be done in
available_templates.cfg (see “Editing available_templates.cfg to Initiate
Workflows” on page 25).
4. DataDeploy is automatically signaled to perform the following functions:
Determine which data types are affected by the data record change.
Read in all necessary database mapping information from DataDeploy
configuration files.
Populate the database with elements of the data record, based on the mapping
file.
Write a log of all DataDeploy activity to the dd-home/log file.
Refer to the Database Deployment for OpenDeploy Administration Guide for
additional information.
Integration Steps
The following sections describe the configuration steps you must perform on
FormsPublisher, TeamSite workflow, and DataDeploy to integrate them for your
specific templating environment.
TeamSite FormsPublisher
Install and set up FormsPublisher, which prepares FormsPublisher for integration with
DataDeploy and TeamSite workflow. You do not need to perform any additional tasks
on FormsPublisher to enable integration.
DataDeploy
A DataDeploy configuration file must be created for each type of data record that will
be deployed. DataDeploy generates these configuration files automatically. However,
the information is provided here for your information. For example, to use DataDeploy
to deploy a data record that is based on the data capture template
/templatedata/beverages/tea/datacapture.cfg, a DataDeploy configuration file
must be created for the data type tea. Likewise, to deploy a data record based on
/templatedata/beverages/coffee/datacapture.cfg, a DataDeploy configuration
file must be created specifically for the data type coffee.
DataDeploy configuration files for FormsPublisher use the following location and
naming conventions:
workarea_name/templatedata/data-category/data-type/data-type_dd.cfg
For example:
/workarea_name/templatedata/beverages/tea/tea_dd.cfg
Or, in the case of the Press Release example shown in “Data Capture Example” on
page 31:
/workarea_name/templatedata/internet/xml/press-release_dd.cfg
TeamSite Workflow
FormsPublisher supports a preconfigured templating-specific workflow template,
author_submit_dcr.wft. This file is installed by FormsPublisher in
iw-home/local/config/wft/default. It configures the Author Form Submit
workflow job displayed in the New job window when FormsPublisher starts a workflow
job. Check available_templates.cfg to verify that the workflow is set up and to add
additional workflows.
Configuring VisualFormat
Overview
Interwoven VisualFormat is a rich text editor based on Ektron eWebEditPro.
VisualFormat is supported only on TeamSite systems running on Windows platforms.
After it is configured, you can use VisualFormat to enter and format text in
FormsPublisher data form text fields. Configuring FormsPublisher to use VisualFormat
is controlled by the following attributes of the <textarea> element in
datacapture.cfg:
external-editor
external-editor-config
external-editor-inline
Additional Documentation
The eWebEditPro documentation set also applies to VisualFormat. For access to the
complete eWebEditPro 5.1 document set, see the Ektron Web site’s documentation
download page (http://www.ektron.com/ewebeditproXML.aspx?id=1277).
If you create other VisualFormat configuration files, it is recommended that you retain
the original visualformatconfig.xml file for backup purposes. Additional
configuration files must reside in the iw-home/httpd/iw directory or in a subdirectory
any number of levels below iw-home/httpd/iw.
NOTE
Disabling Run ActiveX controls and plug-ins in the Internet Explorer security settings
causes the VisualFormat installation window to appear when a user opens a form, even
if VisualFormat is already installed on the client. Since ActiveX is not enabled,
VisualFormat cannot determine whether the client exists and tries to install it.
Feature Differences
The following features are enabled by default in VisualFormat through the
visualformatconfig.xml configuration file. These features were available—but not
enabled by default—in previous versions of VisualFormat.
More information on these settings can be found in the developerguide.pdf file in the
Ektron eWebEditPro 5.1 documentation.
A button for HTML validation.
A button for justifying text.
The <clean> element has the charencode attribute set to utf-8 instead of
entityname. See page 356 (the “Configuring for Extended and Special Characters”
section) of developerguide.pdf in the Ektron eWebEditPro 5.1 documentation.
The <clean> element now has the xsltfilter subelement defined.
The <standard> element has the publish and selection attributes set to xhtml.
The <viewas> element now has the view attribute set to wysiwyg, the publish
attribute set to xhtml and the Unicode attribute set to true.
Tables have the following new options:
appendrow
appendcolumn
insertrowabove
insertrowbelow
insertcolumnright
moverowup
moverowdown
movecolleft
movecolright
508table
The <mediafiles> element has new valid extensions (jpe,txt,doc). The jif
extension is no longer valid.
The <resolvemethod> element now has the allowoverride attribute set to true.
Configuring TinyMCE
FormsPublisher supports TinyMCE for formatting and filling in fields in data capture
forms. This appendix describes how to configure FormsPublisher to use TinyMCE, and
optionally how to customize the appearance and behavior of TinyMCE when it is used
with FormsPublisher. The following topics are addressed:
Installation
Configuring FormsPublisher to use TinyMCE
Customizing TinyMCE
Installation
TinyMCE is installed automatically on the TeamSite server system during TeamSite
installation. You do not have to perform any additional steps to install TinyMCE
software. However, before you can use TinyMCE you must configure FormsPublisher to
use TinyMCE rather than the default text editor, Visual Format.
NOTE
FormsPublisher only supports the version of TinyMCE that is shipped and installed with
TeamSite. Do not attempt to install or integrate other versions of TinyMCE with
TeamSite.
You can also map a specific TinyMCE configuration to a specific data capture form by
setting the external-editor-config attribute for the data capture form to the name of
the configuration you want to use for that form.
NOTE
The external-editor-inline attribute specifies that a text editor is inline (that is, it
appears as a tool bar in the text area) rather than a button when the data record displays in
Internet Explorer. This attribute is provided for use with the VisualFormat text editor. It
is not supported when TinyMCE is used.
Some TinyMCE icons used in FormsPublisher integrations are different from the icons
used in standalone TinyMCE installations. These icons are described in the
ContentCenter Professional User’s Guide and the ContentCenter Standard User’s Guide.
Example:
IWTinyMCECustomConfig("iwov_default", "toolbarRow",
"whitespace,styleselect,formatselect,fontselect,fontsizeselect,\
forecolor,|,bold,italic,underline");
IWTinyMCECustomConfig("iwov_default", "toolbarRow",
"bullist,numlist,|,outdent,indent,|,justifyleft,justifycenter,\
justifyright,justifyfull,|,cut,copy,paste,pasteword,search,|,undo,\
redo,|,iespell,anchor,link,unlink");
IWTinyMCECustomConfig("iwov_default", "toolbarRow",
"hr,removeformat,visualaid,|,sub,sup,|,charmap,|,image,table,help,\
code");
IWTinyMCECustomConfig("iwov_default", "styles",
"Large Bold=example1;Red Bold=example2;Row Highlight=tablerow1");
Customizing TinyMCE
You can customize TinyMCE in the following ways:
The number of rows (up to a maximum of three) displayed in the toolbar.
The buttons that appear in the toolbar. You can choose from a set of predefined
buttons, or you can create buttons with a custom appearance and/or behavior.
New toolbar styles defined in a custom .css file, which can be applied generally or
to specific tables, rows, or cells, or the text in the editor.
New plug-ins to extend the TinyMCE functionality.
Custom configuration items as defined by Moxiecode for TinyMCE version 1.4.5.
For information on custom configuration items, refer the documentation available at
http://TeamSite_server_name/iw/tinymce/docs/reference_configuration.ht
ml.
The following sections describe how to perform these customizations. When applicable,
the instructions first describe how to use predefined configuration items, and then how
to optionally create and use custom configuration items.
To create a custom toolbar configuration, you use the following API to add your custom
configuration definitions in iw-home/httpd/iw/tinymce/config/custom_config.js:
IWTinyMCECustomConfig("config id",
"config item",
The following toolbar configuration items (config item in the preceding syntax
example) are supported.
The following toolbar configuration items (config item in the preceding syntax
example) are disabled:
mode
theme
language
elements
ask
textarea_trigger
docs_language
invalid_elements
debug
toolbarRow
The TinyMCE toolbar set consists of a maximum of three rows of toolbar buttons and
menus displayed on the editor. The buttons/menus that are shown on each row can be
configured.
You can create a new toolbar “row” configuration item by editing custom_config.js,
specifying the config id, the type of configuration item ("toolbarRow" in this case),
and a comma delimited list of button/menu IDs representing the buttons to display on
that particular row:
IWTinyMCECustomConfig("config id","toolbarRow","comma delimited string of
button names");
The value of config id can be any string. It holds information pertaining to a particular
set of toolbar arrangement and custom styles. You can optionally use this configuration
instead of the default configuration. For example:
IWTinyMCECustomConfig("myconfigid","toolbarRow","forecolor,bold,italic,un
derline");
The line above associates a configuration named myconfigid with a toolbar containing
the color, bold, italic, and underline buttons. Each statement like the one above creates a
new toolbar row. You can specify up to three such configuration statements per instance
of config id. Additional configuration statements are ignored.
IWTinyMCECustomConfig("myconfig","toolbarRow","forecolor,|,bold,italic,un
derline");
IWTinyMCECustomConfig("myconfig", "toolbarRow",
"anchor,bullist,charmap,indent,outdent");
IWTinyMCECustomConfig("myconfig", "toolbarRow",
"justifycenter,justifyfull,justifyleft,justifyright");
theme_advanced_buttons<1-3>
You can use the option theme_advanced_buttons<1-3> to replace toolbar rows with
the rows that you want to retain. The theme_advanced_buttons<1-3> is specified in the
custom_config.js, by using the following syntax:
IWTinyMCECustomConfig("config id","theme_advanced_buttons<1-3>","comma
delimited string of button names");
The number n corresponds to the toolbar row number that defines the buttons and menus
that you want to remove. The first toolbarRow corresponds to
theme_advanced_buttons1, the second toolbarRow corresponds to
theme_advanced_buttons2, and the third toolbarRow corresponds to
theme_advanced_buttons3. For example:
IWTinyMCECustomConfig("myconfigid","theme_advanced_button1","forecolor,bo
ld,italic,underline");
The line above specifies that the buttons defined in the first toolbarRow be overwritten
by the toolbarRow that follows this command. In the following example, the buttons
and menus specified in the second line are overwritten by the ones specified in the third
line.
Example
IWTinyMCECustomConfig("myconfig","toolbarRow","forecolor,|,bold,italic,un
derline");
IWTinyMCECustomConfig("myconfig", "theme_advanced_button2",
"anchor,bullist,charmap,indent,outdent");
IWTinyMCECustomConfig("myconfig", "toolbarRow",
"justifycenter,justifyfull,justifyleft,justifyright");
If you define at least one toolbar row and do not define the remaining toolbars by using
either the toolbarRow or theme_advanced_button<1-3> options, only the defined
toolbar(s) is displayed.
The supported button and menu IDs are shown in the following table.
styles
The value of config id is the configuration name to be associated with this styles list.
The value of the styles configuration item must be a semicolon delimited list of
name=value pairs where name is the display label of a style and value is the style name.
These styles are defined in iw-home/httpd/iw/tinymce/config/custom_content.css.
Example
IWTinyMCECustomConfig("myconfig","styles","MyClass=redfont;Example2=examp
le2;TableRow=tablerow1");
You can use the theme_advanced_styles option to replace the defined styles.
TinyMCE allows styles to be associated with specific table elements. The pages for
table properties, table row properties, and table cell properties can display a set of styles
uniquely applicable to the particular element. The general command in
custom_config.js for this is as follows:
The styles list must be semicolon delimited list of name=value pairs where name is the
display label of a style and value is the style name. As with the styles configuration
item, the CSS styles must be defined in
iw-home/httpd/iw/tinymce/config/custom_content.css.
Example 1
The following example defines a list of styles shown on the table properties page.
IWTinyMCECustomConfig("custom1", "tableStyles", "Table Header
1=header1;Table Header 2=header2;Table Header 3=header3");
Example 2
The following example defines a list of styles shown on the table cell properties page.
IWTinyMCECustomConfig("custom1", "tableCellStyles", "Cell Header
1=header1;Cell Header 2=header2;Cell Header 3=header3;Cell
Highlight=tablerow1");
Example 3
The following example defines a list of styles shown on the table row properties page.
IWTinyMCECustomConfig("custom1", "tableRowStyles", "Row Header
1=header1;Row Header 2=header2;Row Header 3=header3;Table
Row=tablerow1");
NOTE
Do not remove the import statement in the first line.
@import url("../jscripts/tiny_mce/themes/advanced/editor_content.css");
/*
* custom_content.css
*
* Custom css definitions should be placed here. Define custom
* class/styles for table/cell/rows and general predefined styles.
*
* Note: Do not change the import statement at the top of this page. It is
* required by TinyMCE.
*/
.header1 {
font-weight: bold;
font-size: 14px
}
.header2 {
font-weight: bold;
font-size: 12px;
color: #FF0000
}
.header3 {
font-weight: normal;
font-size: 12px;
color: #0000FF
}
.example1 {
font-weight: bold;
font-size: 14px
}
.example2 {
font-weight: bold;
font-size: 12px;
color: #FF0000
}
.tablerow1 {
background-color: #BBBBBB;
}
Example:
IWTinyMCECustomConfig("myconfigid","toolbarRow","copyright,|,
bold,italic,underline");
ic,underline");
NOTE
Default configuration items and plug-ins get overwritten by your custom configurations.
Hence, make sure you include the default configuration items that you require in your
custom configurations. For example, insertdatetime plug-in is included by default. If
you do not specify the insertdatetime plug-in in the custom plugins configuration
settings, the insertdate and inserttime buttons are not displayed on the toolbar.
Similarly, to ensure that fonts display appropriately, add the value font[*] in the
comma separated list of the configuration item extended_valid_elements.
Add the following line in the <head> tag of the PT/XSL to link the file:
<LINK REL="StyleSheet" HREF="/iw/tinymce/config/custom_content.css"
TYPE="text/css"/>
Using FormAPI
FormAPI allows you to create data capture forms that dynamically respond to user
actions and other external events. With FormAPI, templates are no longer simple, static
forms: they can become responsive, interactive, highly customized interfaces that
greatly enhance the experience of the user entering content.
FormAPI Features
FormsPublisher FormAPI provides the following functionality to enhance data capture
forms:
Automatically compute the value of one field based on the value of another. For
example, a Totals field is computed from a set of Price fields.
Change the options in a selection element based on the value of another element.
For example, once the user has entered a value in the City and State fields, a
database query automatically populates the ZIP Code field with the valid ZIP codes
for that city.
Make an entry field appear or disappear as needed. For example, the Shipping
Address fields only appear if the user unchecks Same as billing.
Intercept the Save button press to provide custom data validation. For example, a
warning is issued if the user enters a project start date that is after the project end
date.
Automatically set the name of the data record, based on the value of other fields. For
example, the model number of a product description record is used for the file name,
precluding the need to prompt the user for a name.
The template designer enables this functionality by writing a userscript that is included
(either inline or referenced) in the data capture template. A userscript is custom
JavaScript code that uses FormAPI to interact with the data capture form presented by
FormsPublisher. Almost anything that can be done manually by the user entering
content into a form may be scripted through the FormAPI.
FormAPI Considerations
Some important things to note about the FormsPublisher FormAPI:
FormAPI supports both Interwoven and XML data records.
FormAPI is a JavaScript API. Its documentation assumes the user is familiar with
the language syntax, features, and limitations. An excellent reference is JavaScript:
The Definitive Reference, 3rd ed, by David Flanagan, O'Reilly and Associates,
1998.
The userscript does not interact with the browser document object model (DOM)
interface to the HTML form. Instead, FormAPI provides methods to query and set
the values of items in the form.
While userscripts may interact with the user in a number of ways (such as
JavaScript dialogs or new browser windows), FormAPI itself presents no visible
elements to the user.
Code in the <script> element is loaded whenever the user creates a new data record or
edits an existing one. The <script> element is not read when the user views a data
record (so userscripts are not executed).
Using Callouts
This chapter describes an example of using the <callout> element. It contains the
following sections:
The Data Capture Form
The datacapture.cfg File
The example_datacapture_callout.ipl File
The chapter shows an example of the data capture record that contains a callout button.
It also shows the datacapture.cfg and example_datacapture_callout.ipl files that
define and call the CGI.
The <callout> subelement can be used with the <browser>, <checkbox>, <hidden>,
<radio>, <readonly>, <text>, <textarea>, and <select> elements. Refer to the
Chapter 2, “Setting Up Data Capture Templates,” for information.
Figure 20 Data Capture Form with a Callout for the Weather Patterns Item
If the user saves the form as the date (in this example, the form is saved as May10), the
date displays as the Name in the next dialog box. When the user clicks Weather
Patterns, a dialog box displays so the user can select a value.
Figure 21 Selecting a Value for Weather Patterns Using the Data Capture Callout
In this example, the user selects “hot!” from the list and clicks OK. This value is
reflected in the form.
Figure 22 Data Capture Form with Announcement Field Reflecting the Value Selected
using the Weather Patterns Button
<data-capture-requirements type="metadata">
<!-- data-capture-requirements elements contain area elements -->
<ruleset name="Interwoven Information Page">
<description>
Capture announcement to pair with date,weather,stock
</description>
<item name="Announcement">
<textarea cols="15" rows="10" required="t">
<callout
url="/iw-bin/iw_cgi_wrapper.cgi/example_datacapture_callout.ipl/
options.txt" label="Weather Patterns"
window-features="width=320, height=200,
resizable=yes,toolbar=no,scrollbars=yes"/>
</textarea>
</item>
</ruleset>
</data-capture-requirements>
The following value and label pairs are entered in the options.txt file that should be
created in iw-home/local/config. The file format is described in the next section.
These values are in the pull-down for the user selection in the Weather Patterns field.
hot!,hot!
sunny,sunny
cloudy,cloudy
partly cloudy,partly cloudy
drizzle,drizzle
showers,showers
rain,rain
sleet,sleet
snow,snow
The program reads a flat file of selection options and presents them to the user. The
selected option is used to populate the data capture item that launched the callout. The
data capture item must be text or textarea for this example.
The flat file is specified in the PATH_INFO part of the URL. The CGI is designed to
look for the flat file (options.txt) in iw-home/local/config or in the location
specified in iw.cfg. The following URL designates the options.txt flat file to the
example CGI:
/iw-bin/iw_cgi_wrapper.cgi/example_datacapture_callout.ipl/options.txt
value,label
To ensure that any data transfer from the callout window to the data capture form is
reflected on the data capture form, the Javascript in the callout window should make a
call to datacapture.refreshForm(), a function located in the top level of the data
capture window. For example, if the function is being called from the callout window
that was opened by the data capture form (that is, not in a child window of the callout
window), the call would be:
opener.top.datacapture.refreshForm()
This function takes no arguments and should be called before the callout window is
dismissed. One way to do this is to put this call in the onclick handler of the OK
button, as shown in the example on page 129. Another way is to put this call in the
onUnload handler of the callout body so it gets called when the user dismisses the
window. This call could be expensive so it should only be done sparingly.
Alternately, you may wish to update an individual data structure with the value of a
particular form element. You can use datacapture.refreshItem(formElement)
instead of datacapture.refreshForm(). However,
datacapture.refreshItem(formElement) must be called on every form element
whose value was changed by the CGI callout to have all changes updated on the data
capture window; if you choose to call datacapture.refreshForm(), you only need to
call it once. This function is especially useful for large forms where
datacapture.refreshForm is especially expensive. However,
datacapture.refreshItem is not supported on hidden or readonly fields.
Description:
Refreshes the internal data structure of data capture linked to a given form element. This
method should be called if the value of formElement was altered by setting
formElement.value directly and refreshing the whole window with
datacapture.refreshForm() impacts performance.
Argument:
formElement - a JavaScript DOM form element linked to the internal datacapture data
structure to update.
Example:
//This JavaScript resides in the CGI Callout window.
//modifyElement takes a form element object from
//the data capture form and sets its value.
function modifyElement(formElement,value)
{
formElement.value = value;
opener.top.datacapture.refreshItem(formElement);
}
iw_callback_var: The name of the form element that launched this callout.
iw_dcr_path: A file system path to the data record being edited.
iw_dcr_type: The type of the data record being edited.
iw_item_description: The description of the data capture item that launched this
callout.
iw_item_name: The name of the data capture item that launched this callout.
iw_item_value: The current value of the data capture item that launched this
callout. This only applies for text and textarea items. Values of other types of form
instances (check boxes, select menus, etc.) can be obtained through JavaScript.
iw_object_name: The name of the data record being edited.
session: The TeamSite session string for the current session. This is the same as the
custom menu item's session.
task_id: The task ID for the current workflow task, if the data capture form was a
cgitask of a workflow.
user_name: The user name of the current TeamSite user. This is the same as the
custom menu item's user_name.
user_role: The role of the current TeamSite user. This is the same as the custom
menu item's user_role.
example_datacapture_callout.ipl
use TeamSite::CGI_lite;
use TeamSite::Config;
$|=1;
my $cgi = TeamSite::CGI_lite->new();
$cgi->parse_data();
my $form_name = $cgi->{'form'}{'iw_form_name'};
my $element_name = $cgi->{'form'}{'iw_callback_var'};
my $user_name = $cgi->{'form'}{'user_name'};
my $item_name = $cgi->{'form'}{'iw_item_name'};
my $item_description = $cgi->{'form'}{'iw_item_description'};
my $dcr_name = $cgi->{'form'}{'iw_object_name'};
my $flat_file = $ENV{'PATH_INFO'};
if ($flat_file =~ m!^.*/([^/]+)$!) {
$flat_file = $1;
}
{
error_message( 'No available selection options were found.' );
exit 1;
}
print_ui( @options );
exit 0;
sub make_full_filename {
my ($filename) = @_;
my $iw_home = TeamSite::Config::iwgethome();
my $full_filename = $iw_home . "/local/config/" . $filename;
return $full_filename;
}
sub parse_flat_file {
my ($filename) = @_;
my @options;
close FILE;
return @options;
}
sub print_ui {
my (@options) = @_;
print_header();2
print <<"END";
<FORM NAME="callout_form">
<TABLE BORDER="0" CELLPADDING="0" ALIGN="CENTER">
<TR>
<TD VALIGN="TOP" WIDTH="150">
<FONT SIZE="-1">$item_name</FONT>
<BR>
<FONT SIZE="-1"><EM>$item_description</EM></FONT>
</TD>
<TD VALIGN="TOP">
<SELECT NAME="selection_list">
END
foreach my $hash (@options)
{
my $value = $hash->{'value'};
my $label = $hash->{'label'};
if ($label eq '')
{
$label = $value;
}
print "<OPTION VALUE=\"$value\">$label</OPTION>\n";
}
print <<"END";
</SELECT>
</TD>
</TR>
</TABLE>
<CENTER>
<INPUT TYPE="BUTTON" VALUE="OK" onClick="handle_selection()">
<INPUT TYPE="BUTTON" VALUE="Cancel" onClick="self.close()">
</CENTER>
</FORM>
END
print_footer();
return;
}
sub error_message {
my (@msgs) = @_;
print_header();
foreach my $message (@msgs)
{
print $message;
}
print <<"END";
<CENTER>
<FORM>
<INPUT TYPE="BUTTON" VALUE="OK" onClick="self.close()">
</FORM>
</CENTER>
END
print_footer();
return;
}
sub print_header {
print<<"END";
Content-type: text/html
<HTML>
<HEAD>
<TITLE>Example Datacapture Callout</TITLE>
<SCRIPT LANGUAGE="JavaScript">
<!--
return true;
}
function handle_selection()
{
if (callback())
{
if(opener.top.datacapture) {
opener.top.datacapture.refreshForm();
}
self.close();
}
else
{
alert('Please make a selection.');
}
}
function callback()
{
var optionsArray = document.callout_form.selection_list.options;
for ( i = 0 ; i < optionsArray.length ; i++ )
{
if (optionsArray[i].selected)
{
if (!set_datacapture_item_value( optionsArray[i].value ))
{
alert('Fatal callout error. Did you close the
datacapture window?');
}
return true;
}
}
// did not find a selected option!
return false;
}
// -->
c</SCRIPT>
</HEAD>
<BODY BGCOLOR="#C0C0C0">
<TABLE BORDER=0 cellpadding=0 cellspacing=0 WIDTH=100%>
<TR>
<TD ALIGN="LEFT"><B>Example Datacapture Callout</B><BR>
<FONT SIZE="-1"><B>Name: $dcr_name</B></FONT><BR></TD>
<TD ALIGN="RIGHT" VALIGN="TOP">
<IMG SRC="/iw-icons/tslogosmall.gif"></TD>
</TR>
</TABLE>
END
return;
}
sub print_footer {
print <<"END";
</BODY>
</HTML>
END
return;
}
Command-Line Tools
You can generate or regenerate HTML files from the command line as well as from the
FormsPublisher.
Both iwgen and iwregen use an underlying low-level presentation template compiler,
called iwpt_compile.ipl. This compiler is available for your use and is beneficial
when you develop, test, and debug presentation templates.
The iwdtd2dct.ipl CLT is used to create data capture templates from industry-standard
DTDs. Refer to Appendix F, “Creating Data Capture Templates from DTDs” for
examples of using this CLT.
The iwdctverifier.ipl CLT examines a data capture template and flags any potential
errors that may occur in the subsequent edit or save of a form using this data capture
template.
iwdctverifier.ipl
Examines an input data capture template and flags any potential errors that may occur in
a subsequent edit or save of a form in ContentCenter. After writing a new data capture
template or updating an existing data capture template, run iwxml_validate and
iwdctverifier to flag common errors in the data capture template. This CLT should
only be used to verify the correctness of the XML type of data capture templates.
Usage
iwdctverifier.ipl [-h] –i dct-path
Example
The following line verifies the correctness of the input data capture template file
datacapture.cfg.
iwdctverifier.ipl –i datacapture.cfg
iwdtd2dct.ipl
Converts an XML DTD into a data capture template. The resultant data capture template
can be used as is. However, typically it is modified to add presentation-specific elements
as detailed in Chapter 2, “Setting Up Data Capture Templates.” This tool provides an
empty description element for every item and container and an empty text instance
element for every item in the resultant DCT which may then be modified.
Usage
iwdtd2dct.ipl [-h] [-dctName dct-name] [-dtdIdentifier dtd-iden]
-i dtd-path -o dct-path -dcrValidation code
Example
The following line converts the input DTD file simple.dtd into the output data capture
template file datacapture.cfg.
iwdtd2dct.ipl –i simple.dtd –o datacapture.cfg
iwgen
Generates an HTML file based on a presentation template and a data record.
Usage:
iwgen [-h|-v] -t templatevpath -r recordvpath [-e encoding] vpath
NOTE
You can also specify Y:-rooted paths.
Example:
The following example generates an HTML file based on the presentation template
auction.tpl and the data record june_items. The HTML file is written to the file
june_display.html in the current workarea. The current working directory is the user’s
workarea. You should enter this as a single line.
% iwgen -t templatedata/internet/auction/presentation/auction.tpl
-r templatedata/internet/auction/data/june_items june_display.html
iwpt_compile.ipl
Invokes the command-line presentation template compiler to compile presentation
templates into output formats such as HTML, jsp, and asp. By default, the output
encoding of characters is UTF-8, but it can also be ISO-8859-1, if specified with the
-oenc ISO-8859-1 flag.
By default, the output of this program is the final result of compiling a template. If the
-ofile filename flag is used, this output is sent to filename, otherwise it is printed to
STDOUT.
If the -ocode filename.ipl flag is used, instead of writing the normal result of the
compilation process out to file, a stand-alone program that generates the output is
written. This is useful when debugging presentation templates and custom
<iw_xml>-derived tags).
Usage:
iwpt_compile.ipl -pt filename [-ofile filename] [-ocode filename]
[-oenc encoding] [-smartwrite] [-manifest filename] [-umask mask]
[-oprefix ofile_basename_prefix] [-osenc encoding] [tag-specific flags]
iwpt_compile.ipl -v | -h
Example 1
This compilation line uses iw_pt-dcr to obtain data from a single data record named
moo.dcr.
iwpt_compile.ipl -pt -iw_pt moo.tpl -iw_pt-dcr moo.dcr cow.dcr
-iw_include-location . -ofile moocow.html
Example 2
This example shows output that needs to be in UTF-8 format, and the output file should
not be overwritten if the contents have not changed.
iwpt_compile.ipl -pt -iw_pt moo.tpl -iw_pt-dcr moo.dcr cow.dcr
-smartwrite -iw_include-location . -ofile moocow.html -oenc UTF-8
Example 3
When you call the presentation template compiler, you can specify command-line
arguments and flags. Command-line flags are specific to and used by various iw_xml
tags rather than being used directly by the compiler. They are specified as part of the
iwpt_compile.ipl command.
When a presentation template is processed from the presentation template compiler, the
following steps are performed:
1. The presentation template is compiled using the command-line utility
iwpt_compile.ipl. It may use zero or one XML-based data records.
2. An XML parser reads the presentation template. As the parser reads, it encounters
XML tags.
3. A tag object of the appropriate type is created and the parser calls that object's
member functions, passing it relevant information, such as attribute list key, value
data.
4. The tag object's member function emits a snippet of Perl.
5. Collectively, all the snippets of Perl that these tag object member functions emit as
the parser scans the template form a program.
6. This program runs, and the result is the document (typically HTML) that merges
content with look-and-feel instructions.
iwregen
Regenerates an HTML file that was generated by FormsPublisher based on a
presentation template and a data record. Use this command to update a generated HTML
file if either or both the presentation template and the data record that the file is based on
have been modified.
Usage:
iwregen [-h|-v] vpath
NOTE
You can also specify Y:-rooted paths.
Example:
The following example regenerates the HTML file june_display.html, which resides
in the current workarea.
% iwregen june_display.html
iwtmplconfig
Extracts data from templating.cfg.
Usage:
iwtmplconfig -user username -role rolename -area areapath option
Options:
Options (only one may be specified, and the listed arguments are required):
Examples:
iwxml_validate.ipl
Validates a list of XML files against a DTD (and can also check to see if the XML files
are well-formed).
Usage:
iwxml_validate.ipl [-max_errors n] [-d level] [-well] x.xml
[y.xml [...]]
iwxml_validate.ipl -h |-v
Example:
returns with no output and an exit status indicating success since x.xml is a valid XML
file.
upgrade_dct_cfg.ipl
The upgrade_dct_cfg.ipl CLT upgrades datacapture.cfg files from regex5 basic
regular expression syntax to extended regular expression syntax. The meanings of the
original basic regular expressions are preserved, but the extended regex grammar
provides more expressive power for validating user input.
This upgrade is required when moving from the browser-based data capture interface of
TeamSite Templating Classic 4.5 or from any previous version of TeamSite Templating
that uses regular expression syntax. Only validation-regex attributes containing the
following characters are affected: + ? | ( )
CAUTION: You should not run this utility more than once on a particular file (see
-force for details).
Usage:
upgrade_dct_cfg.ipl [-log file] [-inplace] [-n] [-d verbosity] [-force]
[-no_staging_update] [directory_name|file_name]+
upgrade_dct_cfg.ipl -v |-h
-log file The name of the file to which log information is sent. By
default, log information is printed on STDOUT. For example,
if -log xxx is used, all log information is sent to the file
named xxx.
-inplace Do not make backup copies of the datacapture.cfg files;
without this switch, datacapture.cfg.backup files are placed
in the same directories as the datacapture.cfg files.
-n Do not write or modify any datacapture.cfg files; just
determine which ones require an upgrade. Do not modify
/etc/iw.cfg.
-force This utility should run at most once on the root of TeamSite
branching structure (for example, /iwmnt) since the
conversion from basic regexes to extended regexes is one-way.
If use_extended_regex5=true is already set within the
[teamsite_templating] section of iw.cfg, it is assumed that
no further conversion of datacapture.cfg files is required,
and this utility will exit with a diagnostic message. To
override this behavior, use the -force flag.
-no_staging_update Do not attempt to upgrade datacapture.cfg files that are
already in the staging area. By default, datacapture.cfg files
in the staging area are upgraded by creating a temporary
workarea, doing an update of the relevant files, and then
automatically checking in the changes.
Examples:
upgrade_dct_cfg.ipl $iwmount
Upgrades the templating files in the named workarea. The -force option is specified to
override the use_extended_regex5=true statement set within iw.cfg. The
-no_staging_area option is specified to save time since staging area files are read-only
files.
Background:
Character Meaning
+ a single instance of the '+' character
? a single instance of the '?' character
| a single instance of the '|' character
\( and \) used for grouping
\{ and \} used for expressing ranges of instances
Character Meaning
+ one or more instance
? zero or one instance
| either the left or the right hand alternative
( and ) used for grouping
{ and } used for expressing ranges of instances
A basic regex like you+me must now be expressed as you\+me because + means one or
more. Therefore, the extended regex you+me matches strings like youme, youume,
youuume, etc.
You should probably revisit your validation regexes, since the extended regular
expressions now being used allow for stricter input checking.
You can create datacapture.cfg files that define data capture templates (DCTs) from
industry-standard XML DTDs. These data capture templates display as data capture
forms in FormsPublisher. A list of the steps to convert DTDs is outlined here. Refer to
the remainder of this appendix for details and examples of the files at each step in the
process of creating the datacapture.cfg file.
1. Verify that the DTD is correct.
2. Run the iwdtd2dct.ipl CLT to convert the DTD to a DCT. The DCT needs to be
named datacapture.cfg.
3. Make any additional edits to add items such as labels and descriptions to <items>
and save the datacapture.cfg file.
NOTE
After updating a data capture template, you should run the iwxml_validate.ipl
and iwdctverifier.ipl CLTs to flag common errors that may occur.
Save your DTD and the final datacapture.cfg file. It is recommended that these files
be versioned in TeamSite.
Run the iwdtd2dct.ipl CLT on the DTD, specifying the complete path to the input
DTD, to create the file that begins on the next page by changing to the directory
containing the DTD:
cd Y:\default\main\WORKAREA\chris\templatedata\internet\simple-example
(the reference to the Y: drive is not needed for UNIX platforms) and issuing the
command:
iwdtd2dct.ipl -i simple.dtd -o datacapture.cfg
Diagram Key
1. This file maintains a reference to the DTD from which it originated, in the
dtd-system-identifier attribute of the <data-capture-requirements> element.
NOTE
You can manually edit items such as labels and descriptions to this file. For
examples, you may want to edit <label> and <description> elements for <item>.
You may also want to specify min and max values for <item>. You can also modify
instances.
Internationalization
This chapter discusses setting up FormsPublisher for international use. It contains the
following sections:
Encodings
Limitations
Japanese EUC-JP Encoding Support
Encodings
Data capture templates can include multi-byte text (in field names and field
descriptions). The character encoding of data capture templates can be UTF-8 or any of
the native encodings that the Xerces XML parser can parse. These native encodings are:
UTF-8 (Multi-Octet Unicode)
ISO-8859-1 (Western European)
ISO-8859-2
ISO-8859-3
ISO-8859-4
ISO-8859-5
ISO-8859-6
ISO-8859-7
ISO-8859-8
ISO-8859-9
gb2312 (Simplified Chinese)
EUC-JP (Japanese - Extended Unix Code)
iso-2022-jp (Japanese - 7 bit encoding)
Shift-JIS (Japanese - Most common in Japan)
Big5 (Traditional Chinese)
euc-kr (Korean - Extended Unix Code)
koi8-r (Russian)
ebcdic family of encodings
NOTE
Interwoven has certified data capture templates encoded in ISO-8859-1, UTF-8,
Shift-JIS, gb2312, euc-kr, and EUC-JP. The other encodings should work, but they have
not been certified.
These encoding names need to be used literally in XML files (datacapture.cfg). For
example, to include Shift-JIS text in the datacapture.cfg file, the xml header should
be:
<?xml version="1.0" encoding="Shift_JIS" standalone="no"?>
Limitations
Data capture templates can be encoded in non-UTF-8 encoding if these data capture
templates are not used by DataDeploy in DAS mode. DataDeploy in DAS mode parses
data capture templates to generate column names in dd.cfg (DataDeploy configuration
file). DataDeploy's XML parser is limited to parsing two encoding sets: UTF-8 and
ISO-8859-1 encoded data capture templates. If data capture templates need to include
non-ASCII multi-byte field names and need to be used by both DataDeploy and
FormsPublisher, use UTF-8 encoded data capture templates. For DataDeploy in
non-DAS mode, ensure that your dd.cfg is encoded in UTF-8 if it contains multi-byte
column names.
The list of encodings certified for FormsPublisher output engine (presentation templates
and page generation engine, and iw_include tags) are:
CP932—Superset of Shift-JIS. Japanese PC encoding. (CP932 is also known as
MS-SJIS.)
CP936—Superset of GBK. GBK is a superset of GB2312, which is a superset of
GB2312-80. (GB2312 is Simplified Chinese encoding, used in China, Singapore.)
CP950—Superset of Big5. Traditional Chinese encoding pervasive in Taiwan, Hong
Kong.
To include multi-byte text in presentation templates in one of the above encodings, the
encoding name needs to be specified as listed. For example, if a particular presentation
template is encoded in Shift-JIS encoding, the xml header for this presentation template
needs to be:
<?xml version="1.0" encoding="CP932" standalone="no"?>
The presentation template embeds HTML with a <META HTTP EQUIV> header such as the
following:
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
The charset parameter needs to be edited to correspond with the chosen encoding of
page generation. For example, if the default encoding in iwpt_compile.ipl has been
changed to generate pages in Shift-JIS encoding, then the META HTTP EQUIV header
inside the presentation template needs to specify:
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=Shift_JIS">
This charset specification is not necessarily the same as the encoding specification in
the xml header of the presentation template itself. For example, if the presentation
template itself needs to be encoded in EUC-JP, but page generation needs to produce
Shift_JIS encoded pages, then the xml header of the presentation template would
specify:
<?xml version="1.0" encoding="EUC-JP" standalone="no"?>
but the META HTTP EQUIV header of HTML inside the presentation template would
specify:
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=Shift-JIS">
In this scenario, any Japanese text in the presentation template needs to be in EUC-JP
encoding, even if the text is part of the HTML segments. When page generation takes
place (by iwpt_compile.ipl), all text is then converted to the chosen encoding as
specified in iwpt_encoding.ipl (refer to
http://iw-home/iw/help/tst/pt/iwpt_encoding.html and
http://iw-home/iw/help/tst/pt/iwpt_compile.html for more information).
- <td>
<xsl:value-of select="item[@name='General Info']
/value/item[@name='Boat Manufacturer']/value/text()" />
</td>
</tr>
- <tr>
- <td align="right">
<b>Boat Model</b>
</td>
- <td>
<b>:</b>
</td>
- <td>
<xsl:value-of select="item[@name='General Info']
/value/item[@name='Boat Model']/value/text()" />
</td>
</tr>
- <tr>
- <td align="right">
<b>Length (LOA)</b>
</td>
- <td>
<b>:</b>
</td>
- <td>
<xsl:value-of select="item[@name='General Info']
/value/item[@name='Length']/value/text()" />
</td>
</tr>
- <tr>
- <td align="right">
<b>Rig</b>
</td>
- <td>
<b>:</b>
</td>
- <td>
<xsl:value-of select="item[@name='General Info']
/value/item[@name='Rig']/value/text()" />
</td>
</tr>
- <tr>
<td align="right">
<b>Hull Type</b>
</td>
- <td>
<b>:</b>
</td>
- <td>
<xsl:value-of select="item[@name='General Info']
/value/item[@name='Hull Type']/value/text()" />
</td>
</tr>
- <tr>
- <td align="right">
<b>Hull Material</b>
</td>
- <td>
<b>:</b>
</td>
- <td>
<xsl:value-of select="item[@name='General Info']
/value/item[@name='Hull Material']/value/text()" />
</td>
</tr>
- <tr>
- <td>
<hr />
<b>Pricing:</b>
</td>
</tr>
- <tr>
- <td>
- <table border="0" colspan="0">
<xsl:apply-templates select="item[@name
='Pricing']" />
</table>
</td>
</tr>
</table>
</td>
- <td align="right">
- <img>
- <xsl:attribute name="src">
<xsl:value-of select="item[@name='Picture']
/value/text()" />
</xsl:attribute>
</img>
</td>
</tr>
- <tr>
- <td colspan="2">
- <table width="100%" cellspacing="0" cellpadding="0"
border="2">
- <tr>
- <td>
<b>Number of Cabins...</b>
<br />
<xsl:value-of select="item[@name='Number of Cabins']
/value/text()" />
</td>
- <td>
<b>Number of Staterooms...</b>
<br />
<xsl:value-of select="item[@name='Number of
Staterooms']/value/text()" />
</td>
</tr>
- <tr>
- <td>
- <b>
<i>Includes...</i>
</b>
<br />
- <table width="100%" cellpadding="0" cellspacing="0">
- <tr>
- <td>
<xsl:apply-templates select="item[@name
='Included']" />
</td>
</tr>
</table>
</td>
- <td valign="top">
<b>Details...</b>
<br />
<xsl:value-of select="item[@name='Details']
/value/text()" />
</td>
</tr>
</table>
</td>
</tr>
</table>
</center>
</body>
</html>
</xsl:template>
- <xsl:template match="item[@name='Pricing']/value">
- <tr>
- <td>
<b>Season:</b>
</td>
- <td>
<xsl:value-of select="item[@name='Season']/value/text()" />
</td>
</tr>
- <tr>
- <td>
- <table border="0" colspan="0">
<xsl:apply-templates />
</table>
</td>
</tr>
</xsl:template>
- <xsl:template match="item[@name='Pricing']/value/item[@name='Time
Periods']/value">
- <tr>
- <td>
Per
<xsl:value-of select="item[@name='Time Period']/value/text()" />
</td>
- <td>
<xsl:value-of select="item[@name='Price']/value/text()" />
</td>
</tr>
</xsl:template>
- <xsl:template match="item[@name='Included']/value[position()=1]">
<xsl:value-of select="text()" />
</xsl:template>
- <xsl:template match="item[@name='Included']/value[position()>1]">
<xsl:text />
<xsl:value-of select="text()" />
</xsl:template>
</xsl:stylesheet>
E F
eaSaveFormat attribute 44 fields
element collapsing 96
allowed 48, 83, 85 file
and 48, 83, 85 available_templates.cfg 17, 101
branch 83, 86 datacapture.cfg 16, 29, 126, 149, 150
browser 48 datacapture_callout.ipl 127
callout 48 DTD 36, 82
category 82, 84 example_datacaptue_callout.ipl 127
checkbox 49 iw.cfg 26
choice 42, 43, 44, 45 templating.cfg 16, 77, 78
container 42, 43 visualformatconfig.xml 104
cred 48, 83, 85 files 32
data-capture-requirements 41 FormAPI
data-type 82, 84 considerations 120
default 50 features 119
description 42, 43 forms
dialog 42, 43, 58 buttons 85, 90
directory 83, 86 naming 85, 91
inline 49, 57 style sheet 85
item 42, 43, 46 FormsPublisher
itemref 43, 45, 66 activating branches 84
label 42, 43, 48 architecture 14
locations 82, 84 enabling FormAPI 120
not 48, 83, 85 integrating with DataDeploy 99
option 49 integration 100
or 48, 83, 85 overview 13
presentation 82, 84, 86 fullpage attribute 86
radio 49 function attribute 58
readonly 49 function-param attribute 58
root-container 42
ruleset 42 G
script 42, 43, 120 generated HTML files 14, 20
select 50 specifying locations 87
tab 43
template 82, 86
templating 82, 83 H
text 50 hidden attribute 54
textarea 51, 103, 107 HTML pages
url 48 from presentation template compiler 139
viewoptions 82, 88 generating 20, 138
window-features 48 regenerating 142
encoding 153, 157
Japanese 154 I
environment variables 57
example templating environment 22, 24 initial-dir attribute 48
copying 25 inline element 49, 57
instance
example_datacapture_callout.ipl file 127
definition 47, 48
extension attribute 86
integrating 25
external-editor attribute 51, 56, 103, 107
isTitle attribute 46
external-editor-config attribute 103, 108
item element 42, 43, 46
external-editor-inline attribute 51, 103
defined 46
extns attribute 48
itemref element 43, 45, 66
N S
name attribute 41, 43, 46, 84, 86 scoping 64
name-value pairs 128 script element 42, 43, 120
naming forms 85 search
navigation tree 85 enabling 97
showing 95 select element 50
non-located element 45 selection options 127
not element 48, 83, 85 server-side inline callout 57
showtree attribute 85, 95
size attribute 48, 50
O specifying branches 84
option element 49 style sheet 85
or element 48, 83, 85 stylesheet
overview 13 customized 93
P T
page generation subsystem 14, 16, 21 tab element 43
pathid attribute 46, 64 tags
plug-in debugging 139
TinyMCE 116 template
presentation directory 18 component 73
presentation element 82, 84, 86 configuring 74
template element 82, 86
templatedata directory 18 W
copying to workarea 25 window-features element 48
Templating directory 24 workflow 25
templating element 82, 83 initiating 99
templating environment
integrating with TeamSite FormsPublisher 99
example 24, 78
preconfigured 101
templating.cf file 78
schematic of 19, 21
templating.cfg 16
wrap attribute 51
templating.cfg file 20, 77
DTD 82
example 78 X
extracting data 143 XML
text element 50 validating 144
textarea element 51, 103, 107 XML mapping 60
TinyMCE 51, 56, 107 XSLT
configuration properties 108 presentation template 76, 157
configuring 107
custom styles 113
customizing 108
platforms 56
plug-ins 116
toolbar configuration 109
type 17
type attribute 58
U
upgrade_dct_cfg 145
URL access 75
URL Commands 27, 88
url element 48
V
validating XML 30, 144
validation regexes 50
upgrading 145
validation-regex attribute 50
verifying data capture template 30
viewoptions element 82, 85, 88
VisualFormat
configuration 104
configuration file 56
default features 105
inline 51
platforms 56
setting up 51, 103
style sheet 104
visualformatconfig.xml file 104
vpath-regex attribute 86