9 Designing Attribute Editors

Attribute editors are displayed in flex and flex parent assets’ New and Edit forms. Through attribute editor you define how users will enter attribute data. To help you create attribute editors, WebCenter Sites provides the presentationobject.dtd file that defines the input types, the attribute editor asset whose XML code provides the values of the input type's options such as check boxes, radio button, and attribute editor elements that receive input values and supply the logic behind the format and behavior of the attribute.

Topics:

9.1 About Attribute Editors

Attribute editors are like any other assets, so you edit, approve, and manage them the way you would any other asset. Through attribute editors you can define how users enter data for attributes on New or Edit forms for flex or flex parent assets.

When you assign an attribute editor to an attribute, it replaces the default input mechanism (style) for that attribute. The default input style is based on the data type of the attribute. Attribute editors format the input mechanism for attributes, so you design your attribute editors as you design your flex attributes. You can use the workflow and revision tracking features to manage attribute editors.

There are three parts to an attribute editor, with an optional fourth and fifth:

  • The presentationobject.dtd file, located in the WebCenter Sites installation directory (Required). This is the DTD file that defines all the possible input styles (presentation objects) for flex attributes and their style tags.

  • The attribute editor asset (Required). It holds or points to XML code that provides input options for the attribute it is associated with. You use the style tags defined in the DTD to create this XML code.

  • An element that formats the attribute, or, displays an edit mechanism, when that attribute displays in a New or Edit form (Required). This element must be located in the OpenMarket/Gator/AttributeTypes directory in the ElementCatalog table to be able to find it. Its name must exactly match the name of the style tag that invokes it from the attribute editor.

  • An element that formats the attribute value when it displays in an Inspect form (Optional). This element must also be located in the OpenMarket/Gator/AttributeTypes directory in the ElementCatalog table.

    The name of the element must use the convention DisplayStyleTag, where StyleTag represents and must exactly match the name of the style tag that invokes it from the attribute editor.

  • An element that formats the attribute data before it is saved in the database (Optional). This element must also be located in the OpenMarket/Gator/AttributeTypes directory in the ElementCatalog table.

    The name of the element must use the convention StyleTagFlexAssetGather, where StyleTag represents and must exactly match the name of the style tag that invokes it from the attribute editor.

WebCenter Sites provides the following items, by default, to support the development of your attribute editors:

  • The presentationobject.dtd file. It defines several input styles (presentation objects) that you can use in your attribute editors. This means you do not have to define your own unless the nine that are included do not cover your needs.

  • Nine text files with sample XML that you can use to create attribute editor assets. You can cut and paste the sample XML into your attribute editor assets. These files are located in the installation directory under Samples/Attribute_Editors.

  • Ten display elements that work with the sample XML code for attribute editor assets. They are located in the OpenMarket/Gator/AttributeTypes directory in the ElementCatalog table.

When you do not use attribute editors, WebCenter Sites uses default input styles for the attributes, based on their data types. See Default Input Styles for Attributes. Create attribute editors only when the default input styles are not sufficient for your attributes.

Topics:

9.1.1 The presentationobject.dtd File

The presentationobject.dtd file defines all of the input types (presentation objects) that you can implement through attribute editors. The default presentationobject.dtd file defines nine input style tags and the arguments that they can pass from the attribute editor to the display elements (described in The Attribute Editor Elements).

Following is the entire presentationobject.dtd file. It is located in the WebCenter Sites installation directory:

<!-- PRESENTATIONOBJECT: An editor
-- PRESENTATIONOBJECT defines the presentation object for
-- instances of Gator attribute types. A presentation object
-- defines the properties of an editor for one of the following
-- controls: Text field, Text area, Pulldown menu
-- For additional information, refer to
-- com.openmarket.gator.interfaces.IPresentationObject.
-- You must specify one of TEXTFIELD, TEXTAREA, or PULLDOWN
-- elements.
-->
<!ELEMENT PRESENTATIONOBJECT (TEXTFIELD | TEXTAREA | PULLDOWN |
RADIOBUTTONS | CHECKBOXES | PICKASSET | FIELDCOPIER | DATEPICKER |
IMAGEPICKER | CKEDITOR | FCKEDITOR | IMAGEEDITOR | TYPEAHEAD |
UPLOADER)>
<!ATTLIST PRESENTATIONOBJECT NAME CDATA #REQUIRED>
<!-- TEXTFIELD: A text field of a specific width
-- You must specify the x dimension; the maximum number of
-- allowable characters defaults to 255.
-->
<!ELEMENT TEXTFIELD ANY>
<!ATTLIST TEXTFIELD XSIZE CDATA #IMPLIED>
<!ATTLIST TEXTFIELD WIDTH CDATA #IMPLIED>
<!ATTLIST TEXTFIELD MAXCHARS CDATA "255">
<!ATTLIST TEXTFIELD BLANKED (YES | NO) "NO">
<!ATTLIST TEXTFIELD MAXVALUES CDATA #IMPLIED>
<!-- TEXTAREA: A text area of a specific size
-- The wrap style defaults to soft.
-->
<!ELEMENT TEXTAREA ANY>
<!ATTLIST TEXTAREA XSIZE CDATA #IMPLIED>
<!ATTLIST TEXTAREA YSIZE CDATA #IMPLIED>
<!ATTLIST TEXTAREA WIDTH CDATA #IMPLIED>
<!ATTLIST TEXTAREA HEIGHT CDATA #IMPLIED><!ATTLIST TEXTAREA WRAPSTYLE (OFF | SOFT | HARD) "SOFT">
<!ATTLIST TEXTAREA DEPTYPE CDATA #IMPLIED>
<!ATTLIST TEXTAREA MAXVALUES CDATA #IMPLIED>
<!ATTLIST TEXTAREA RESIZE CDATA #IMPLIED>
<!-- PULLDOWN: A pulldown menu with an enumeration of items
-- You can specify zero or more list items; the fontsize defaults
-- to relative fontsize 3.
-->
<!ELEMENT PULLDOWN ((ITEM)* | QUERYASSETNAME)>
<!ATTLIST PULLDOWN FONTSIZE CDATA #IMPLIED>
<!-- RADIOBUTTONS: Radio buttons with an enumeration of items
-- You can specify zero or more list items; the fontsize defaults
to relative fontsize 3.
-->
<!ELEMENT RADIOBUTTONS ((ITEM)* | QUERYASSETNAME)>
<!ATTLIST RADIOBUTTONS FONTSIZE CDATA #IMPLIED>
<!ATTLIST RADIOBUTTONS LAYOUT (HORIZONTAL | VERTICAL) "VERTICAL">
<!-- CHECKBOXES: Check boxes with an enumeration of items
-- You can specify zero or more list items; the fontsize defaults
-- to relative fontsize 3.
-->
<!ELEMENT CHECKBOXES ((ITEM)* | QUERYASSETNAME)>
<!ATTLIST CHECKBOXES FONTSIZE CDATA #IMPLIED>
<!ATTLIST CHECKBOXES LAYOUT (HORIZONTAL | VERTICAL) "HORIZONTAL">
<!-- ITEM: A list item
-- You can specify zero or more characters of text.
-->
<!ELEMENT ITEM (#PCDATA)*>
<!-- SQL: Query to populate list of items
-- You can specify zero or more characters of text. Query must
-- return a 'value' column.
-->
<!ELEMENT QUERYASSETNAME (#PCDATA)*>
<!ELEMENT CKEDITOR ANY>
<!ATTLIST CKEDITOR ALLOWEDASSETTYPES CDATA #IMPLIED>
<!ATTLIST CKEDITOR SCRIPT CDATA #IMPLIED>
<!ATTLIST CKEDITOR IMAGEPICKERID CDATA #IMPLIED>
<!ATTLIST CKEDITOR IMAGEASSETTYPE CDATA #IMPLIED>
<!ATTLIST CKEDITOR TOOLBAR CDATA #IMPLIED>
<!ATTLIST CKEDITOR DEPTYPE CDATA #IMPLIED>
<!ATTLIST CKEDITOR WIDTH CDATA #IMPLIED>
<!ATTLIST CKEDITOR HEIGHT CDATA #IMPLIED>
<!ATTLIST CKEDITOR MAXVALUES CDATA #IMPLIED>
<!ATTLIST CKEDITOR RESIZE CDATA #IMPLIED>
<!ATTLIST CKEDITOR CONFIG CDATA #IMPLIED>
<!ATTLIST CKEDITOR CONFIGOBJ CDATA #IMPLIED>
<!-- Deprecated in Oracle WebCenter Sites 11gR1 release. -->
<!ELEMENT FCKEDITOR ANY>
<!ATTLIST FCKEDITOR XSIZE CDATA #IMPLIED>
<!ATTLIST FCKEDITOR YSIZE CDATA #IMPLIED>
<!ATTLIST FCKEDITOR LAZYLOAD CDATA #IMPLIED>
<!ATTLIST FCKEDITOR ALLOWEDASSETTYPES CDATA #IMPLIED>
<!ATTLIST FCKEDITOR SCRIPT CDATA #IMPLIED>
<!ATTLIST FCKEDITOR IMAGEPICKERID CDATA #IMPLIED>
<!ATTLIST FCKEDITOR TOOLBAR CDATA #IMPLIED>
<!ATTLIST FCKEDITOR DEPTYPE CDATA #IMPLIED>
<!ATTLIST FCKEDITOR WIDTH CDATA #IMPLIED>
<!ATTLIST FCKEDITOR HEIGHT CDATA #IMPLIED>
<!ATTLIST FCKEDITOR MAXVALUES CDATA #IMPLIED>
<!-- PICKASSET: When the tree is active, it's the "add from tree"
-- button.
-- When the tree is disabled, it's The Content Centre remember
-- widget. -->
<!ELEMENT PICKASSET ANY>
<!ATTLIST PICKASSET MAXVALUES CDATA #IMPLIED>
<!ATTLIST PICKASSET DISPLAYELEMENT CDATA #IMPLIED>
<!-- TYPEAHEAD: Type And Select the asset. -->
<!ELEMENT TYPEAHEAD ANY>
<!ATTLIST TYPEAHEAD MAXVALUES CDATA #IMPLIED>
<!ATTLIST TYPEAHEAD DISPLAYELEMENT CDATA #IMPLIED>
<!ATTLIST TYPEAHEAD PAGESIZE CDATA #IMPLIED>
<!-- UPLOADER: Upload a file from local disc. -->
<!ELEMENT UPLOADER ANY>
<!ATTLIST UPLOADER MAXVALUES CDATA #IMPLIED>
<!ATTLIST UPLOADER MAXFILESIZE CDATA #IMPLIED>
<!ATTLIST UPLOADER FILETYPES CDATA #IMPLIED>
<!ATTLIST UPLOADER MINWIDTH CDATA #IMPLIED>
<!ATTLIST UPLOADER MAXWIDTH CDATA #IMPLIED>
<!ATTLIST UPLOADER MINHEIGHT CDATA #IMPLIED>
<!ATTLIST UPLOADER MAXHEIGHT CDATA #IMPLIED>
<!-- FIELDCOPIER: A hidden field whose value is set from another
-- field.
-- ex. If you want an attribute whose value is always the name of
-- the asset:
-- <FIELDCOPIER SOURCEFIELD="name"/>
-->
<!ELEMENT FIELDCOPIER ANY>
<!ATTLIST FIELDCOPIER SOURCEFIELD CDATA #REQUIRED>
<!-- This describe the Date Picker -->
<!ELEMENT DATEPICKER ANY>
<!ATTLIST DATEPICKER COMPARETOFIELD CDATA #REQUIRED>
<!ATTLIST DATEPICKER MAXVALUES CDATA #IMPLIED>
<!-- This describe the ImagePicker -->
<!ELEMENT IMAGEPICKER ANY>
<!ATTLIST IMAGEPICKER ASSETTYPENAME CDATA #REQUIRED>
<!ATTLIST IMAGEPICKER ATTRIBUTETYPENAME CDATA #REQUIRED>
<!ATTLIST IMAGEPICKER ATTRIBUTENAME CDATA #REQUIRED>
<!ATTLIST IMAGEPICKER CATEGORYATTRIBUTENAME CDATA #IMPLIED>
<!ATTLIST IMAGEPICKER RESTRICTEDCATEGORYLIST CDATA #IMPLIED>
<!ATTLIST IMAGEPICKER MAXVALUES CDATA #IMPLIED>
<!-- Image Editor -->
<!ELEMENT IMAGEEDITOR ANY>
<!ATTLIST IMAGEEDITOR EDITORTYPE (oie | clarkii) "oie">
<!ATTLIST IMAGEEDITOR HEIGHT CDATA #REQUIRED>
<!ATTLIST IMAGEEDITOR WIDTH CDATA #REQUIRED>
<!ATTLIST IMAGEEDITOR FITIMAGE (true | false) "true">
<!ATTLIST IMAGEEDITOR SNAPSHOTPANEL (true | false) "false">
<!ATTLIST IMAGEEDITOR LIMITCROPPING (true | false) "false">
<!ATTLIST IMAGEEDITOR CROPHEIGHT CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR CROPWIDTH CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR ENABLEOIEFORMAT (true | false) "false">
<!ATTLIST IMAGEEDITOR LIMITSIZE (true | false) "false">
<!ATTLIST IMAGEEDITOR MAXHEIGHT CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR MAXWIDTH CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR MINHEIGHT CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR MINWIDTH CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR AUTORESAMPLE (true | false) "false">
<!ATTLIST IMAGEEDITOR AUTORESAMPLEPROPORTIONAL (true | false)
"false">
<!ATTLIST IMAGEEDITOR DEFAULTTEXTFONT CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR DEFAULTTEXTSIZE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR DEFAULTTEXTCOLOR CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR ASSETTYPE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR ATTRIBUTE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR ATTRIBUTETYPE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR CATEGORYATTRIBUTE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR RESTRICTEDCATEGORYLIST CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR ENABLEIMAGEPICKER (true | false) "false">
<!ATTLIST IMAGEEDITOR OIEASSETTYPE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR OIEATTRIBUTE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR OIEATTRIBUTETYPE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR OIECATEGORYATTRIBUTE CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR OIERESTRICTEDCATEGORYLIST CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR OIEENABLEIMAGEPICKER (true | false) "false">
<!ATTLIST IMAGEEDITOR TAGEDIT (true | false) "false">
<!ATTLIST IMAGEEDITOR BASE64JPEGQUALITY CDATA "95">
<!ATTLIST IMAGEEDITOR ASKTOSAVELOCALLY (true | false) "false">
<!ATTLIST IMAGEEDITOR DEFAULTSAVINGTYPE (gif | jpg | jpe | png | 
tif | bmp | oie) "gif">
<!ATTLIST IMAGEEDITOR ENABLEGIFSAVING (true | false) "true">
<!ATTLIST IMAGEEDITOR ENABLEJPEGSAVING (true | false) "true">
<!ATTLIST IMAGEEDITOR ENABLEPNGSAVING (true | false) "true">
<!ATTLIST IMAGEEDITOR ENABLETIFFSAVING (true | false) "true">
<!ATTLIST IMAGEEDITOR ENABLEBMPSAVING (true | false) "true">
<!ATTLIST IMAGEEDITOR GRIDVISIBLE (true | false) "false">
<!ATTLIST IMAGEEDITOR GRIDSNAP (true | false) "true">
<!ATTLIST IMAGEEDITOR GRIDSPACINGX CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR GRIDSPACINGY CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR MAXTHUMBNAILHEIGHT CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR MAXTHUMBNAILWIDTH CDATA #IMPLIED>
<!ATTLIST IMAGEEDITOR THUMBNAILFORMAT (gif | jpg | jpe | png | tif 
| bmp | oie) "gif">
<!ATTLIST IMAGEEDITOR MAXVALUES CDATA #IMPLIED>

To create custom attribute editors other than the ones made possible by default, you must first define an XML input style tag, a PRESENTATIONOBJECT tag, in the presentationobject.dtd file. To define a new PRESENTATIONOBJECT tag, you must do the following:

  • Add the new tag (presentation object) to the list in the <!ELEMENT PRESENTATIONOBJECT...> statement.

  • Add a <!ELEMENT...> section that defines the new tag (presentation object) and the arguments that it takes. Follow the normal syntax rules for a .dtd file and follow the conventions used in the presentationobject.dtd file.

9.1.2 The Attribute Editor Asset

The attribute editor asset either holds XML code or points to an .xml file. That XML code provides the values of the input type's options such as check boxes, radio options, drop-down lists, and so on. Although WebCenter Sites provides nine text files with sample code that you can use to create attribute editor assets, it does not provide any attribute editor assets because you have to customize the sample code so that any options are appropriate for your data.

When you create your attribute editors, either cut and paste the code from HTML version of this book (samples follow this section) or use the text files located in the Samples subdirectory of the installation directory on your system.

This section includes the following topics:

9.1.2.1 The Syntax and the Default Tags

The code in an attribute editor asset has the following basic format:

<?XML VERSION="1.0"?>
<!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd"> 

<PRESENTATIONOBJECT NAME="SomeName">
...
...
...

</PRESENTATIONOBJECT>

The tag that describes the format of the input style (presentation object) is embedded between the pair of PRESENTATIONOBJECT tags. This tag can have additional nested tags in it. Although the NAME attribute is required for the PRESENTATIONOBJECT tag, it is reserved for future use.

The name of any PRESENTATIONOBJECT tag that you include in the code for an attribute editor asset must be defined in the presentationobject.dtd file. This .dtd file has the following PRESENTATIONOBJECT tags defined by default (listed in alphabetic order):

  • CHECKBOXES

  • CKEDITOR

  • DATEPICKER

  • FIELDCOPIER

  • IMAGEEDITOR

  • IMAGEPICKER

  • PICKASSET

  • PICKFROMTREE (Deprecated; use PICKASSET instead.)

  • PULLDOWN

  • RADIOBUTTONS

  • TEXTAREA

  • TEXTFIELD

  • TYPEAHEAD

  • UPLOADER

Note that the PRESENTATIONOBJECT tag that you use in the attribute editor code must exactly match the name of the display element that you want to use for the attribute editor. Therefore, to define a new tag for a custom attribute editor, the element that you create must use the same name as the tag.

For a description of the elements, see The Attribute Editor Elements. For code samples for attribute editors, see the following sections:

9.1.2.2 CHECKBOXES

The presentationobject.dtd defines a CHECKBOXES tag, an attribute editor that uses the tag to invoke the CHECKBOXES element, which creates a set of check boxes for the attribute.

The CHECKBOXES tag takes the following parameters:

  • ITEM or QUERYASSETNAME: The source of the names listed next to the check boxes. To specify the names, use the ITEM parameter. To specify a query asset that obtains the names dynamically from a database table, use the QUERYASSETNAME parameter.

    Note the following:

    • Whether you use the ITEM parameter or the QUERYASSETNAME parameter as the source of the names listed next to the check boxes, ensure the parameter specifies multiple values. A single value creates radio buttons instead of check boxes.

    • You must use a query asset to use a query. You cannot use a SQL statement.

    • The SQL in the query asset must return a value column. For example: select name as value from shippingtype.

    • If the data type of the attribute using the attribute editor is asset, the query must also return the assets IDs. For example: select name as value, id as assetid from Product where...

  • LAYOUT: Whether the check boxes should be positioned in a vertical list or spread out in a horizontal row. Valid options are HORIZONTAL or VERTICAL. The default is HORIZONTAL.

  • MAXVALUES: Limits the number of values that can be added to a multi-valued attribute. For example, if MAXVALUES is set to 10, then only ten values can be added. No default value.

The following attribute editor code specifies that the CHECKBOXES element should use the results of a query asset named A Prods for the names of a vertical list of check boxes:

<?XML VERSION="1.0"?>
<!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd"> 
<PRESENTATIONOBJECT NAME="CheckBox">
 <CHECKBOXES LAYOUT="VERTICAL">
  <QUERYASSETNAME>A Prods</QUERYASSETNAME>
 </CHECKBOXES>
</PRESENTATIONOBJECT>

For example code that shows the use of the ITEM parameter, see PULLDOWN Example.

Notes about data types:

A CHECKBOXES attribute editor is appropriate for attributes with the following data types:

  • date

  • float

  • integer

  • money

  • string

  • asset (If asset, you must supply the name of the query asset that returns the names of the assets.)

9.1.2.3 CKEditor

The presentationobject.dtd defines a CKEDITOR tag. An attribute editor that uses the tag invokes the CKEDITOR element, which launches the CKEditor. The person creating the flex asset enters the value for the attribute in that window.

  • You must have the CKEditor application installed and configured correctly.

  • It is highly recommended that you use CKEditor only when the data type of the attribute is set to blob. You don't have to worry about sizing the field for the blob data type.

The CKEDITOR tag takes the following parameters:

The following code includes a CKEDITOR tag that creates a text box that is 400 pixels wide by 200 pixels high:

  • EMBEDDEDLINKS: The YES value lets users create links to other assets. Default value: NO.

  • ALLOWEDASSETTYPES: Lets you define which asset types can be included or linked to by means of CKEditor. Default value: ALL.

  • DEPTYPE: The approval dependency between the main asset and an embedded asset. Valid options are EXISTS and EXACT. Default value: EXACT.

  • MAXVALUES: This parameter limits the number of values that can be added to a multi-valued attribute. For example, if MAXVALUES is set to 10, then only ten values can be added. No default value.

  • MAXLENGTH: The number of characters in the CKEditor's source view (displayed when you click the CKEditor Source button). Default value: -1 (unlimited).

  • INSTRUCTION: Used to provide help for the field.

The CKEDITOR tag also takes parameters for customizing the appearance of CKEditor instances. One set of parameters is defined in WebCenter Sites. The other set is available on the CKEditor website.

Parameters defined in WebCenter Sites must be added directly to the XML field of a CKEditor instance:

  • TOOLBAR: The name of the toolbar, which is read from the configuration file specified in the CONFIG parameter. For example, CONFIG="myconfig.js".

  • WIDTH: The text box width in pixels. If you do not specify a value for WIDTH, WebCenter Sites sets a default width. Sample value: 700px.

  • HEIGHT: The text box height in pixels. If you do not specify a value for HEIGHT, WebCenter Sites sets a default height. Sample value: 300px.

    Note:

    The WIDTH and HEIGHT parameters replace the deprecated XSIZE and YSIZE parameters. Setting XSIZE and YSIZE has no effect.

  • RESIZE: The true value allows users to resize the text area. Default value: false.

Parameters listed on the CKEditor website must be specified either in a configuration file, named in the CONFIG parameter, or in the CONFIGOBJ parameter. Except for the TOOLBAR parameter, they are not recognized when they are added to the CKEditor's XML field. The following is a description of the CONFIG and CONFIGOBJ parameters:

  • CONFIG: Specifies the relative path to the default or custom CKEditor configuration file. For example, setting CONFIG="myconfig.js" will load the custom myconfig.js file from the CKEditor base path (CKEditor source folder). For a custom configuration file, users can also specify a URL to the config.js file in the CONFIG attribute. The base path is defined in the xcelerate.ckeditor.basepath property, in the wcs_properties.json file.

    Within the configuration file is a CKEDITOR.editorConfig function, where you specify the CKEditor parameters listed at http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.html#.editorConfig. The list includes the TOOLBAR parameter.

  • CONFIGOBJ: Takes a JSON string, which can contain any of the parameters listed at http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html. (The list includes the TOOLBAR parameter.)

    The JSON string format uses double quotes:

    '{foo1:"value1",foo2:"value2"}' ...
    

    For example:

    CONFIGOBJ='{width:"300px",height:"300px",toolbar:"SITES",fullPage:true}'
    

Note:

CKEditor parameters are recognized and used in the following hierarchical order:

Parameters in the CKEditor's XML field override parameters in CONFIGOBJ, which override parameters in the configuration file named in the CONFIG parameter. For example, the TOOLBAR parameter in a CKEditor's XML field overrides the toolbar parameter in CONFIGOBJ='{toolbar: "SITES",fullPage:true}', which overrides the toolbar parameter in the configuration file myconfig.js (specified as CONFIG='myconfig.js'). The fullPage parameter in CONFIGOBJ overrides the same parameter in myconfig.js.

To avoid potential conflicts, specify each parameter only once in the place where it is recognized: either in the editor's XML field, in the CONFIGOBJ parameter, or in the configuration file that is specified in the CONFIG parameter.

The following code includes a CKEDITOR tag that creates a CKEditor box 400 pixels wide by 200 pixels high:

<?XML VERSION="1.0"?>
<!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd">

<PRESENTATIONOBJECT NAME="CKEditorTest">
  <CKEDITOR WIDTH="400px" HEIGHT="200px">
  </CKEDITOR>
</PRESENTATIONOBJECT>

Notes about data types:

The best choice for the data type of an attribute that uses a CKEDITOR attribute editor is blob. You can use string or text but it is problematic because it is hard to predict how large the data entered into the attribute's field will be because each HTML marker counts toward the limit. The string data type is limited to 256 characters and text is limited to 2000. It is recommended that you use blob as the data type for attributes that use CKEDITOR as their input mechanism.

9.1.2.4 PICKASSET

The presentationobject.dtd defines a PICKASSET tag. An attribute editor that uses the tag invokes the PICKASSET element, which creates a Drop Zone field into which a user can drag and drop an asset from a tree or search results list. When an asset is dropped into the Drop Zone field, the name of the asset is displayed in a box outlined with a dashed border. When you point to the name of the asset, a tooltip opens displaying information about the asset. To change the behavior of the PICKASSET attribute editor, for example, to customize the look and feel of the tooltip, see Building an Attribute Editor.

This tag can take the MAXVALUES parameter. The MAXVALUES parameter limits the number of values that can be added to a multi-valued attribute. For example, if MAXVALUES is set to 10, then only ten values can be added. No default value.

For information about customizing the PICKASSET attribute editor, see Building an Attribute Editor.

Below is the code to create a PICKASSET attribute editor:

<?XML VERSION="1.0"?>
<!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd">
<PRESENTATIONOBJECT NAME="PickAsset">

  <PICKASSET>
  </PICKASSET>
</PRESENTATIONOBJECT>

Notes about data types:

A PICKASSET attribute editor is only appropriate for attributes with a data type of asset.

9.1.2.5 PULLDOWN Example

The presentationobject.dtd defines a PULLDOWN tag. An attribute editor that uses the tag invokes the PULLDOWN element, which formats a field with a drop-down list of values.

This tag takes the ITEM and QUERYASSETNAME: parameters which are the source of the names in the drop-down list. To specify the names, use the ITEM parameter. To specify a query asset that obtains the names dynamically from a database table, use the QUERYASSET parameter.

Note the following:

  • You must use a query asset to use a query. You cannot use a SQL statement.

  • The SQL in the query asset must return a value column. For example: select name as value from shippingtype.

  • If the data type of the attribute using the attribute editor is asset, the query must also return the assets' IDs. For example: select name as value, id as assetid from Product where...

  • If you want to include date options, they must be in the format: YYY-MM-DD HH:MM:SS.

The following attribute editor code specifies that the list holds the items red, green, and blue:

<?XML VERSION="1.0"?>
<!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd"> 

<PRESENTATIONOBJECT NAME="PulldownTest">
<PULLDOWN>
  <ITEM>Red</ITEM>
  <ITEM>Green</ITEM>
  <ITEM>Blue</ITEM>
</PULLDOWN>

For sample code that shows how to use the QUERYASSETNAME parameter rather than ITEM, see CHECKBOXES.

Notes about data types:

A PULLDOWN attribute editor is appropriate for attributes with the following data types:

  • date

  • float

  • integer

  • money

  • string

  • asset

A drop-down list is the default input style for attributes of type asset. The list displays all the assets of that type. Use a PULLDOWN attribute editor when you want to further restrict the items in the drop-down list with a query asset so that the list doesn't display every asset of that type.

9.1.2.6 RADIOBUTTONS

The presentationobject.dtd defines a RADIOBUTTONS tag. An attribute editor that uses the tag invokes the RADIOBUTTONS element, which creates a set of radio options for the attribute.

The RADIOBUTTONS tag takes the following parameters:

  • ITEM or QUERYASSETNAME: The source of the names listed next to the radio options. To specify the names, use the ITEM parameter. To specify a query asset that obtains the names dynamically from a database table, use the QUERYASSET parameter.

    Note the following:

    • You must use a query asset to use a query. You cannot use a SQL statement.

    • The SQL in the query asset must return a value column. For example: select name as value from shippingtype.

    • If the data type of the attribute using the attribute editor is asset, the query must also return the assets' IDs. For example: select name as value, id as assetid from Product where...

  • LAYOUT: Whether the buttons should be positioned in a vertical list or spread out in a horizontal row. Valid options are HORIZONTAL or VERTICAL. The default is HORIZONTAL.

The following attribute editor code specifies that the RADIOBUTTONS element should use the results of a query asset named A Prods for the names of a vertical list of buttons:

<?XML VERSION="1.0"?>
<!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd"> 

<PRESENTATIONOBJECT NAME="RadioButtonTest">
  <RADIOBUTTONS LAYOUT="VERTICAL">
    <QUERYASSETNAME>A Prods</QUERYASSETNAME>
  </RADIOBUTTONS>
</PRESENTATIONOBJECT>

For example code that shows the use of the ITEM parameter, see PULLDOWN Example.

Notes about data types:

A RADIONBUTTON attribute editor is appropriate for attributes with the following data types:

  • date

  • float

  • integer

  • money

  • string

  • asset (If asset, you must supply the name of the query asset that returns the names of the assets.)

Note:

The RadioButton attribute editor of type date would interpret the date values entered in the presentation.dtd in server's timezone (or the timezone set in the JVM). This value will be converted to user's timezone when the asset form is rendered.

To see the same date value irrespective of the timezone, consider using an attribute editor of type string.

9.1.2.7 TEXTAREA

The presentationobject.dtd defines a TEXTAREA tag. An attribute editor that uses the tag invokes the TEXTAREA element, which creates a text box field for the attribute, and a pair of radio buttons that allows users to specify whether that attribute should display embedded link buttons.

The TEXTAREA tag takes the following parameters:

  • WIDTH: The text box width, in pixels. If you do not specify a value for WIDTH, WebCenter Sites sets a default width. Sample value: 700px.

  • HEIGHT: The text box height, in pixels. If you do not specify a value for HEIGHT, WebCenter Sites sets a default height. Sample value: 300px.

    Note:

    The WIDTH and HEIGHT parameters replace the deprecated XSIZE and YSIZE parameters. Setting XSIZE and YSIZE has no effect.

  • RESIZE: The true value allows users to resize the text area. The default value is false.

  • WRAPSTYLE: Whether the text in the box wraps at all, and, if it does, whether it wraps automatically (soft) or only when the user presses the Enter key (a hard return). Valid options are SOFT, HARD, and OFF. The default is OFF.

  • DEPTYPE: The approval dependency between the main asset and an embedded asset. Valid options are EXISTS and EXACT. The default is EXACT.

    • EXISTS: When the main asset is edited, approved, and re-published, the embedded asset does not have to be approved and re-published while a version of the asset exists at the destination.

    • EXACT: When the main asset is edited, approved, and re-published, the embedded asset, if it was edited, must be approved and re-published as well.

  • MAXVALUES: Limits the number of values that can be added to a multi-valued attribute. For example, if MAXVALUES is set to 10, then only ten values can be added. No default value.

The following attribute editor code defines the XSIZE as 40 pixels, the YSIZE as 5 pixels, disables text wrapping by setting WRAPSTYLE to OFF, and sets the approval dependency for embedded assets to EXISTS:

<?XML VERSION="1.0"?>
<!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd"> 

<PRESENTATIONOBJECT NAME="TextAreaTest">
  <TEXTAREA XSIZE="40" YSIZE="5" WRAPSTYLE="OFF" DEPTYPE="EXISTS">
  </TEXTAREA>
</PRESENTATIONOBJECT>

Notes about data types:

A TEXTAREA attribute editor is appropriate for attributes with the data type of text and blob. Use the text data type when you have to store up to 2000 characters. To store more than 2000 characters, use the blob data type.

9.1.2.8 TEXTFIELD

The presentationobject.dtd defines a TEXTFIELD tag. An attribute editor that uses the tag invokes the TEXTFIELD element from the New and Edit forms to create a text field for the attribute. When the attribute is displayed on the Inspect form, however, it uses the DisplayTEXTFIELD element.

The TEXTFIELD tag takes the following parameters:

  • XSIZE: The length of the field, in characters.

  • MAXCHARS: The number of characters, up to 256, allowed in the field.

  • BLANKED: Whether the attribute's value is replaced with a string of asterisks when it is displayed in the Inspect form. For example, for a password attribute, the value of the password should not be displayed in an Inspect form. Valid options are YES and NO. The default is NO.

    Because using the BLANKED parameter automatically means that you need the field to behave differently on the New and Edit forms than it does on the Inspect form, the TEXTFIELD tag is delivered with both of the two possible elements by default.

  • MAXVALUES: Limits the number of values that can be added to a multi-valued attribute. For example, if MAXVALUES is set to 10, then only ten values can be added. No default value.

The following attribute editor code defines the XSIZE as 60 and the maximum number of characters as 80:

<?XML VERSION="1.0"?>
<!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd"> 

<PRESENTATIONOBJECT NAME="TextFieldTest">
  <TEXTFIELD XSIZE="60" MAXCHARS="80">
  </TEXTFIELD>
</PRESENTATIONOBJECT>

Notes about data types:

A TEXTFIELD attribute editor is appropriate for attributes with the following data types:

  • float

  • integer

  • money

  • string

  • url

9.1.2.9 TYPEAHEAD

The presentationobject.dtd defines a TYPEAHEAD tag. An attribute editor that uses the tag invokes the TYPEAHEAD element, which creates a type ahead input box with a drop-down menu attribute. When the attribute is displayed in the New and Edit views of an asset, and the down-arrow in the drop-down field is clicked, the drop-down menu lists the names of the assets from which the user can choose.

The TYPEAHEAD tag takes the following parameters:

  • PAGESIZE: Limits the number of results that are shown in the drop-down menu at one time for each type ahead search. For example, if PAGESIZE is set to 5, then only five assets are displayed in the drop-down menu at one time. The default value is 10.

  • MAXVALUES: Limits the number of values that can be added to a multi-valued attribute. For example, if MAXVALUES is set to 10, then only ten values can be added. No default value.

The PAGESIZE parameter can be used to limit the number of results shown in the drop-down at one time. This paginates the results listed in the drop-down menu. For example, if the PAGESIZE parameter is set to show 10 assets at a time in the drop-down menu, a user can see the next 10 assets in the list by clicking More choices. Similarly, to go back to the last 10 assets that were listed, the user can click the Previous choices link.

The list of results can also be filtered by typing the first couple of letters that an asset starts with into the input box. For example, if Ski is typed into the input box, the results that are displayed in the drop-down menu (in alphabetic order) will all start with Ski. This is similar to running the query Ski*, which finds all assets that begin with the letters or word Ski. As you type into the type ahead input box, it auto-fills with the first result in the drop-down menu, as shown in this figure:

Figure 9-1 Related Content Dialog

Description of Figure 9-1 follows
Description of "Figure 9-1 Related Content Dialog"

To select the auto-filled asset, users can press Enter on their keyboards. Users can also select any result, one at a time, from the drop-down menu, either by selecting an asset (navigating the drop-down menu with the up and down arrow keys on the keyboard) and then pressing the Enter key or by using your mouse to click an asset. After you select an asset, it is displayed below the drop-down menu. When a user points to a selected asset, a tooltip is shown, as in this figure:

To change the behavior of the TYPEAHEAD attribute editor, for example, to customize the look and feel of the tooltip, see Building an Attribute Editor.

Notes about data types:

A TYPEAHEAD attribute editor is appropriate only for attributes of data type asset.

9.1.2.10 UPLOADER

The presentationobject.dtd defines an UPLOADER tag. An attribute editor that uses the tag invokes the UPLOADER element, which creates an upload attribute. The Upload field can upload files of any type. However, to restrict the types of files that can be uploaded, use the FILETYPES parameter.

When a user clicks to upload a file, the progress of the upload is shown in the asset's toolbar, as shown in this figure:

A thumbnail image for each uploaded file is displayed in the Uploader field. When a user clicks the thumbnail of an uploaded image file, the image is displayed in an overlay at its actual size. For file types other than images, WebCenter Sites displays a thumbnail image specific to file type in the Uploader field. When a thumbnail image for a particular file type is not available, an arbitrary image is shown, instead.

When a user points to the thumbnail image of an image file, the file's name, type, and dimensions are displayed in a tooltip. The file's name and type is displayed in a tooltip of a file that is not an image, as shown in this figure:

The UPLOADER tag takes the following parameters:

  • MAXFILESIZE: Lets you specify the maximum size of the files that can be uploaded. Valid units for this parameter are B, KB, MB, and GB. Default value: 1024KB. Default unit: KB.

  • FILETYPES: Lets you specify the types of files that can be uploaded. For example, *.jpg*. If you do not specify a value for this parameter, the default value is any (*.*).

  • MINWIDTH: Lets you specify the minimum width (in pixels) of the files that can be uploaded. For example, if MINWIDTH is set to 700px, then users can only upload files with a width that is no less than 700px. If you do not specify a value for this parameter, the default value is any width. Valid unit: px.

  • MAXWIDTH: Lets you specify the maximum width (in pixels) of the files that can be uploaded. For example, if MAXWIDTH is set to 700px, then users can only upload files with a width that is no more than 700px. If you do not specify a value for this parameter, the default value is any width. Valid unit: px.

  • MINHEIGHT: Lets you specify the minimum height (in pixels) of the files that can be uploaded. For example, if MINHEIGHT is set to 700px, then users can only upload files with a height that is no less than 700px. If you do not specify a value for this parameter, the default value is any height. Valid unit: px.

  • MAXHEIGHT: Lets you specify the maximum height (in pixels) of the files that can be uploaded. For example, if MAXHEIGHT is set to 700px, then users can only upload files with a height that is no more than 700px. If you do not specify a value for this parameter, the default value is any height. Valid unit: px.

  • MAXVALUES: Limits the number of values that can be added to a multi-valued attribute. For example, if MAXVALUES is set to 10, then only ten values can be added. No default value.

Notes about data types:

A UPLAODER attribute editor is appropriate only for attributes of data type blob.

9.1.3 The Attribute Editor Elements

The elements that take the input values passed to them from their attribute editor counterparts, supply the logic behind the format and behavior of the attribute when it is displayed on a form. For example, it might perform a loop sequence for multivalue attributes so that additional values can be entered in the field.

Table 9-1 lists the default flex attribute display elements located in the ElementCatalog table under OpenMarket/Gator/AttributeTypes. The names of these elements match exactly the names of the custom XML tags defined in the presentationobject.dtd file.

Table 9-1 Attribute Editor Elements

Element Description

CHECKBOXES

Formats the input style of the attribute as a set of check box options. The attribute editor must either define the names of the options or provide the name of a query asset to use to obtain the names.

CKEDITOR

Invokes the CKEditor text editor. The attribute editor must specify the height and width pixel dimensions for the text box.

PULLDOWN

Formats the input style of the attribute as a select field with a drop-down list. The attribute editor must either specify the items that are displayed in the list or provide the name of a query asset to use to obtain the values.

RADIOBUTTONS

Formats the input style of the attribute as a set of radio options. The attribute editor must define the names of the options or provide the name of a query asset to use to obtain the names.

TEXTAREA

Formats the input style of the attribute as a text box and displays radio buttons that allow the user to specify whether the text box will allow embedded links. The attribute editor must define the x and y dimensions of the box.

TEXTFIELD

Formats the input style of the attribute as a text field. The attribute editor must define the length of the field and the number of characters that are allowed in the field.

DisplayTEXTFIELD

Formats the appearance of the text field attribute's value when it is displayed on the Inspect form. If the attribute editor sets the BLANKED parameter to YES, this element displays the value from the field as a string of asterisks. Typically used for password fields.

PICKASSET

Formats the input style of the attribute as a Drop Zone field into which a user can drag and drop an asset from a tree or search results list.

PICKFROMTREE

Deprecated. Use PICKASSET.

TYPEAHEAD

Formats the input style of the attribute as a type ahead input box with a drop-down menu. When the asset is displayed in the New or Edit view of an asset, and the down-arrow in the drop-down field is clicked, the drop-down menu lists the names of the assets from which the user can choose. Use the PAGESIZE parameter to limit the number of results shown in the drop-down menu at one time.

UPLOADER

Creates an upload attribute. The upload field can upload files of any type. Use the FILETYPES parameter to restrict the types of files that can be uploaded.

9.1.4 Conventions for the Attribute Editor Elements

WebCenter Sites can use an element for an attribute editor when that element conforms to the following rules:

  • It must have the same name as the input style tag that calls it from the attribute editor code. For example, the default CHECKBOXES tag has a default CHECKBOXES.xml element.

  • The element must be placed in the ElementCatalog using the following naming conventions: OpenMarket/Gator/AttributeTypes/name.

To create your own display elements for custom attribute editors, find one that is the closest to the attribute editor element that you want to create and then copy as much of it as possible. For help, examine the code in the default attribute editor elements and read the following descriptions of the variables and syntax in them:

Variables:

When WebCenter Sites loads a form that uses the attribute editor, it calls the element with the computer name. It passes the information in the following variables to the display element:

  • PresInst: The instance of the current presentation object.

  • AttrName: The name of the current attribute.

  • AttrType: The data type of the current attribute.

  • EditingStyle: Whether the attribute can take multiple values (based on the value in the Number of Values field for the attribute). This variable is set to either single or multiple.

  • RequiredAttr: Whether the attribute is required for the current asset. The variable is set to either true or false.

  • MultiValueEntry: Instructs WebCenter Sites how to handle the values for an attribute that can take multiple values.

    When this value is set to yes, the display element is called once, under the assumption that the widget created by the element enables the user to select multiple values in it (a multi-select drop-down list, for example).

    When this value is set to no, WebCenter Sites calls the display element once for each possible value for the attribute and displays one widget for each value that can be stored.

    Note that this value is always set to yes initially.

  • doDefaultDisplay: Whether to use the default input style for an attribute of this type. For a list, see Default Input Styles for Attributes. When WebCenter Sites calls the display element, this variable is initially set to yes. To use the input widget created by the element, the element must reset this variable to no.

  • AttrValueList: The list of all the values for this attribute.

  • TempVal: The value of a single attribute value.

Other required syntax:

The code in the display element must also use the following conventions:

  • It must store information about how to validate the attribute values in a variable named RequireInfo. WebCenter Sites passes this variable to elements that use JavaScript to validate the attribute values. Those elements are:

    OpenMarket/Gator/FlexibleAssets/FlexAssets/ContentForm1
    OpenMarket/Gator/FlexibleAssets/FlexGroups/ContentForm1
    

    This JavaScript performs prescribed error checking and validation based on the type of control, the data type, and other predictable characteristics. The information passed in the RequireInfo variable informs the JavaScript about the custom requirements for the attribute editor.

  • The name of the widget in the display element (the INPUT NAME) must use the following convention:

    • For a single-value attribute, the name of the attribute.

    • For a multi-value attribute, it must use a 1-based counter prepend the attribute name for each attribute value (for example, 1color, 2color, 3color).

For an example, see Customizing Attribute Editors.

9.2 Creating Attribute Editors

To give you a hands-on experience of creating an attribute editor, the sample XML is provided in the Samples subdirectory. If you’re creating an attribute editor that you’ll add to a flex or flex parent asset’s form of your online site, write your own XML code or edit the sample code suitably.

  1. Open the Admin interface.
  2. Click New and then select New Attribute Editor from the shortcut list.

    The Attribute Editor form opens.

    Figure 9-5 Attribute Editor Dialog

    Description of Figure 9-5 follows
    Description of "Figure 9-5 Attribute Editor Dialog"
  3. In the Name field, enter a unique name of up to 64 characters, excluding spaces.
  4. In the Description field, enter a short phrase that describes the purpose of the attribute editor.
  5. In the XML field, either paste the appropriate sample XML attribute editor code from the HTML version of this guide or from the sample text files provided in the Samples subdirectory of the installation directory.
  6. Edit the code as needed. For example, for a CHECKBOXES or a RADIOBUTTONS attribute editor, you must provide names for the check boxes or radio buttons. If you are creating a PULLDOWN attribute editor, you must provide the values for the drop-down list.
  7. Click Save.

    Note:

    Another option is to code the XML for the attribute editor in a separate .xml file. In this case, rather than entering the code directly into the XML field, click Browse next to the XML in file field and select the file.

  8. Approve this attribute editor so that it can be published to the management system.

    Note:

    If you are using a query asset with this attribute editor, be sure to approve both the attribute editor and the query asset.

    Because the dependency between an attribute editor and its query asset is specified in the XML code in the attribute editor, the approval system cannot detect the dependency and verify that the query asset exists on the management system.

9.3 Customizing Attribute Editors

Your custom attribute editor may be similar to the sample editor in many ways. So, you can modify the sample code and display elements to use them for your custom editor. The presentationobject.dtd file needs a new PRESENTATIONOBJECT tag for a new input style. You can’t use any of the default tags.

When you create a custom PRESENTATIONOBJECT tag, you must also supply the appropriate display elements for it:

  • Required: An element that formats the attribute (displays an edit mechanism) when that attribute displays in a New or Edit form.

  • Optional: An element that formats the attribute when it displays in the Inspect form.

  • Optional: An element that formats the attribute data before it is saved in the database.

For information about the variables and conventions used in the display elements for an attribute editor, see The Attribute Editor Elements.

To create or customize an attribute editor into which a file can be uploaded (for example, if you are customizing the UPLOADER attribute editor), add custom logic to the attribute editor code which will ensure that the file being uploaded is valid. See Adding Custom Logic to Validate an Uploaded File.

9.3.1 Example: Customized Attribute Editor

This example demonstrates how to customize the description of the TEXTAREA tag in the presentationobject.dtd file and the TEXTAREA element to create an attribute editor that disables a text box for the user who does not have the proper permissions.

There are three steps:

  • Step 1: Editing the description of the TEXTAREA tag in the presentationobject.dtd to support a new parameter named PERMISSIONS.

  • Step 2: Writing the code for the attribute editor and creating the attribute editor.

  • Step 3: Editing the TEXTAREA element to check the value of PERMISSIONS.

9.3.1.1 Step 1: Editing the presentationobject.dtd File

To support the new parameter, you add a single line of code to the TEXTAREA description in the presentationobject.dtd.

  • Add the new line added to the end of the default description of the TEXTAREA tag, as the following code shows:

    <!-- TEXTAREA: A text area of a specific size. You must specify
    -- the x and y dimensions; the wrap style defaults to soft.
    -->
    <!ELEMENT TEXTAREA ANY>
    <!ATTLIST TEXTAREA XSIZE CDATA #REQUIRED>
    <!ATTLIST TEXTAREA YSIZE CDATA #REQUIRED>
    <!ATTLIST TEXTAREA WRAPSTYLE (OFF | SOFT | HARD) "SOFT">
    <!ATTLIST TEXTAREA PERMISSION CDATA>
    

9.3.1.2 Step 2: Specifying Permission for the Example Attribute Editor

Here is the example code with the new parameter.

  • Specify that a user must have Administrators as the value for PERMISSION to see the field, as the following code shows:

    <?XML VERSION="1.0"?>
    <!DOCTYPE PRESENTATIONOBJECT SYSTEM "presentationobject.dtd"> 
    
    <PRESENTATIONOBJECT NAME="TextAreaTest">
      <TEXTAREA XSIZE="40" YSIZE="10" WRAPSTYLE="SOFT" PERMISSION="Administrators">
      </TEXTAREA>
    </PRESENTATIONOBJECT>
    

9.3.1.3 Step 3: Editing the TEXTAREA Element

The third step is editing the TEXTAREA element.

  • Add the lines shown in bold in the following code to enable or disable the field, based on the value of the PERMISSION parameter:

    <?XML VERSION="1.0" ?>
    <!DOCTYPE FTCS SYSTEM "futuretense_cs.dtd">
    <FTCS Version="1.1">
    <!-- OpenMarket/Gator/AttributeTypes/TEXTAREA
    --
    -- INPUT
    --
    -- OUTPUT
    --
    -->
    
    <!-- Display one TEXTAREA per attribute value -->
    <IF COND="Variables.MultiValueEntry=no">
    <THEN>
    
    <!-- Don't want default display field  -->
    <setvar NAME="doDefaultDisplay" VALUE="no"/>
    
    <!-- Get all parameters from Attribute Editor xml -->
    <presentation.getprimaryattributevalue
    NAME="Variables.PresInst"
    ATTRIBUTE="FONTSIZE" VARNAME="FONTSIZE"/> 
       <if COND="Variables.errno!=0">
    <then>
    <setvar NAME="FONTSIZE" VALUE="2"/>
    </then>
    </if>
    
    <presentation.getprimaryattributevalue
    NAME="Variables.PresInst"
    ATTRIBUTE="WRAPSTYLE" VARNAME="WRAPSTYLE"/> 
    <if COND="IsVariable.WRAPSTYLE!=true">
    <then>
    <setvar NAME="WRAPSTYLE" VALUE="OFF"/>
    </then>
    </if>
    
    <presentation.getprimaryattributevalue
    NAME="Variables.PresInst"
    ATTRIBUTE="XSIZE" VARNAME="XSIZE"/> 
    <if COND="IsVariable.XSIZE!=true">
    <then>
    <setvar NAME="XSIZE" VALUE="24"/>
    </then>
    </if>
    
    <presentation.getprimaryattributevalue
    NAME="Variables.PresInst" 
    ATTRIBUTE="YSIZE" VARNAME="YSIZE"/> 
    <if COND="IsVariable.YSIZE!=true">
    <then>
    <setvar NAME="YSIZE" VALUE="20"/>
    </then>
    </if>
    
    <setvar NAME="disableTextArea" VALUE="no"/>
    <presentation.getprimaryattributevalue
    NAME="Variables.PresInst" 
    ATTRIBUTE="PERMISSION" VARNAME="PERMISSION"/> 
    <if COND="IsVariable.PERMISSION=true">
    <then>
    <setvar NAME="errno" VALUE="0"/>
    <USERISMEMBER GROUP="Variables.PERMISSION"/>
    <IF COND="Variables.errno=0">
    <THEN>
    <setvar NAME="disableTextArea" VALUE="yes"/>
    </THEN>
    </IF>
    </then>
    </if>
    
    <tr> 
    
    <!-- Standard element to display attribute name or description
    -->
    <callelement NAME="OpenMarket/Gator/FlexibleAssets/Common
    /DisplayAttributeName"/>
    <td></td>
    <td>
    
    <!-- Single valued attributes -->
    <if COND="Variables.EditingStyle=single">
    <then>
    
    <!-- Special case: TEXTAREA for URL attributes -->
    <IF COND="Variables.AttrType=url">
    <THEN>
    <setvar NAME="errno" VALUE="0"/>
    <BEGINS STR="AttrValueList.urlvalue"
    WHAT="AttrValueList."/>
    <IF COND="Variables.errno=1">
    <THEN>
    <setvar NAME="filename" VALUE="CS.UniqueID.txt"/>
    </THEN>
    <ELSE>
    <setvar NAME="filename"
    VALUE="AttrValueList.urlvalue"/>
    </ELSE>
    </IF>
    
    <INPUT TYPE="hidden" NAME="Variables.AttrName_file"
    VALUE="Variables.filename" 
    REPLACEALL="Variables.AttrName,Variables.filename"/>
    
    <setvar NAME="errno" VALUE="0"/>
    <BEGINS STR="AttrValueList.@urlvalue"
    WHAT="AttrValueList."/>
    <IF COND="Variables.errno=1">
    <THEN>
    <setvar NAME="MyAttrVal" VALUE="Variables.empty"/>
    </THEN>
    <ELSE>
    <setvar NAME="MyAttrVal"
    VALUE="AttrValueList.@urlvalue"/>
    </ELSE>
    </IF>
    </THEN>
    </IF>
    
    <!-- Display a TEXTAREA with all parameters from Attribute
    --Editor xml -->
    <!-- The NAME of the input must be the attribute name -->
    <IF COND="Variables.disableTextArea=yes">
    <THEN>
    <TEXTAREA DISABLED="yes" NAME="Variables.AttrName"
    ROWS="Variables.YSIZE" COLS="Variables.XSIZE"
    WRAP="Variables.WRAPSTYLE"
    REPLACEALL="Variables.AttrName,Variables.XSIZE,
    Variables.YSIZE,Variables.WRAPSTYLE,Variables.empty">
    
    <!-- For most single valued attrs, the value is contained in
    MyAttrVal -->
    <csvar NAME="Variables.MyAttrVal"/>
    </TEXTAREA>
    </THEN>
    <ELSE>
    <TEXTAREA NAME="Variables.AttrName"
    ROWS="Variables.YSIZE" COLS="Variables.XSIZE"
    WRAP="Variables.WRAPSTYLE"
    REPLACEALL="Variables.AttrName,Variables.XSIZE,
    Variables.YSIZE,Variables.WRAPSTYLE,Variables.empty">
    <!-- For most single valued attrs, the value is
    contained in MyAttrVal -->
    <csvar NAME="Variables.MyAttrVal"/>
    </TEXTAREA>
    </ELSE>
    </IF>
    </then>
    <else>
    <!-- Multiple valued attributes -->
    <!-- For single value attributes we can usually use the
    default RequireInfo -->
    <!-- For multiple value attributes we need to append to
    RequireInfo for each value -->
    <if COND="Variables.RequiredAttr=true">
    <then>
    <setvar NAME="RequireInfo"
    VALUE="Variables.RequireInfo*Counters.TCounterVariables.
    AttrName*ReqTrue*Variables.AttrType!"/>
    </then>
    <else>
    <setvar NAME="RequireInfo"
    VALUE="Variables.RequireInfo*Counters.TCounterVariables
    .AttrName*ReqFalse*Variables.AttrType!"/>
    </else>
    </if>
    
    <!-- Display a TEXTAREA with all parameters from Attribute
    Editor xml -->
    <!-- The NAME of the input must be the attribute name
    prepended by the TCounter counter -->
    <IF COND="Variables.disableTextArea=yes">
    <THEN>
    <TEXTAREA DISABLED ="yes" NAME="Counters.TCounterVariables.AttrName"
    ROWS="Variables.YSIZE" COLS="Variables.XSIZE"
    WRAP="Variables.WRAPSTYLE"
    REPLACEALL="Counters.TCounter,
    Variables.AttrName,Variables.XSIZE,
    Variables.YSIZE,Variables.WRAPSTYLE">
    <csvar NAME="Variables.tempval"/> </TEXTAREA>
    </THEN>
    <ELSE>
    <TEXTAREA NAME="Counters.TCounterVariables.AttrName"
    ROWS="Variables.YSIZE" COLS="Variables.XSIZE"
    WRAP="Variables.WRAPSTYLE"
    REPLACEALL="Counters.TCounter,
    Variables.AttrName,Variables.XSIZE,
    Variables.YSIZE,Variables.WRAPSTYLE">
    <csvar NAME="Variables.tempval"/> </TEXTAREA>
    </ELSE>
    </IF>
    </else>
    </if>
    </td>
    </tr>
    </THEN>
    </IF> <!-- MultiValueEntry -->
    </FTCS>
    

9.3.2 Adding Custom Logic to Validate an Uploaded File

To validate an uploaded file, you add custom logic to an attribute editor's code.

  1. Create a JSP element with the name ValidateFileUpload in the path CustomElements/fatwire/ui/util.
  2. In the JSP element, retrieve the file name and the byte array containing the uploaded file data in the request scope by calling ics.GetCgi("fileBytes") which returns an FTVAL, from which you can call the getBlob() method to get the byte[] for the uploaded blob.
    byte[] fileBytes = null;  
    if(ics.GetCgi("fileBytes") != null){  
    fileBytes = ics.GetCgi("fileBytes").getBlob();         
    } 
    
  3. (Optional) Write your custom logic to ensure that the uploaded file data is valid:
    • If the file data is valid, set the variable fileValidated to true by calling ics.SetVar("fileValidated","true"). This ensures that the file will be uploaded to the WebCenter Sites server.

    • If the file data is invalid, set the fileValidated variable to false by calling ics.SetVar("fileValidated","false"). Additionally, set the custom validation failure message in the fileUploadFailureMessage variable by calling ics.SetVar("fileUploadFailureMessage",<CustomErrorMessage>) in custom element. This rejects the data uploaded by the user and displays the custom error message adjacent to progress bar for the file being uploaded. If the fileUploadFailureMessage variable is not set but fileValidated is set to false, WebCenter Sites shows a generic message Upload Failed: <fileName>.

Note:

Sample code (except validation logic) is available in the base element fatwire/ui/util/ValidateFileUpload. This element should not be modified and the custom code must be written in the CustomElements path as specified in step 1.

9.4 Considerations About Editing Attribute Editors

Some changes to the attribute editors don’t cause data loss, while others may affect the data.

  • You can change the Name without causing a schema change.

  • You can change the Description without causing data loss.

  • If you change code in the attribute editor:

    • You can add input options.

    • If you have existing data, you should not remove input options. If you do, some of your existing data will no longer be valid and you will have to search through the database and fix it.

    • If you change the input style, you risk a data mismatch.