About the Reference (SAP Library - Portal Development Manual)

About the Reference

Structure of the Description

The description of the controls is structured in:

· General description - what is it

· Attributes of the control

· Overview of the attributes with possible values, defaults and the manipulation with the JSP-taglib and classlib.

· Example

The M column in the overview table specifies if the parameter is mandatory. A mandatory parameter is marked with a * in that column.

The values column in the overview table specifies which type of parameter the attribute expects. Possible entries are:

· String

An ASCII string. Usually event handling routines, names, titles etc.

· String (cs)

A case sensitive ASCII string. Usually event handling routines, names, titles etc.

· Units

An integer value specified in web client units. According to the HTML standard units can be specified in:

¡ Pixel (px)

Pixels are the smallest addressable unit on the web client. A web client has a maximum resolution, that is the number of horizontal times vertical pixel (for example, 800x600, 1024x768 etc.) When you specify units in pixel you can make sure that your control is displayed on every web client in the same size.

Pixel is the default unit.

Example

Both expressions set the width of a control to 500 pixel.
width="500"
width="500px"

¡ Percent (%)

The percentage specified is calculated from the visible space of the web client. If for example, a width of a control is specified with 50% the control uses half of the of the web client width. The control changes its width according to the web client dynamically (for example, if the web client window gets scaled).

Example

The width of a control is set to 30% of the web client.
width="30%"

The default value for the attribute is marked with a value in parenthesis, if it applies, for example (100).

· Numeric

A numeric expression.

· Others

If an attribute requires specific values. Booleans require "TRUE" or "FALSE" or text size can only be "LARGE", "MEDIUM" and "SMALL". Default values are marked with (d).

Example

When the default value for the text size is MEDIUM it is depicted as:

LARGE
MEDIUM (d)
SMALL

Controls

General

To use the controls you have to know about the syntax and the attributes of the controls. Every control has different attributes. In the description we describe the attributes and gather the information in a table which shows the usage with the taglib and the classlib.

Import Statments

When you use the methods in a Servlet, Abstract Portal Component or DynPage, you have to import the controls. The IDE, like Eclipse, give you a hint if an import statement is needed and suggest an import statement. A HTMLB control, for example inputField, is defined in two packages, so the IDE will offer you two choices:

com.sapportals.htmlb.InputField

com.sapportals.htmlb.unifiedrendering.controls.InputField

Note

The com.sapportals.htmlb.InputField package is the one to use. The com.sapportals.htmlb.unifiedrendering.controls.* package is for internal use only.

Syntax

Programming with the JSP taglib follows the XML syntax. Each control is "wrapped" in tags. To identify the tags as XML the prefix

hbj: (stands for: HTML-Business for Java)

is used. Some controls (for example, tray, group) also need a tag body. The tag body specifies the controls that are placed "inside" the tag. The syntax would be like:

Tag

   <hbj:control       comment: begin of tag for HTMLB control
         attributes   comment: setting of attributes of HTMLB control
   </hbj:mycontrol>   comment: end of tag for HTMLB control

Tag with "quick" end of tag (only possible when the tag has no body)

   <hbj:control       comment: begin of tag for HTMLB controls
         attributes   comment: setting of attributes of HTMLB control
   />                 comment: end of tag for HTMLB controls

Tag with body

   <hbj:control       comment: begin of tag for HTMLB control
        attributes    comment: setting of attributes of HTMLB control
   <                  comment: end of tag for HTMLB control
     <hbj:a_control_in_the_body
         attributes
     />
     <hbj:next_control_in_the_body
         attributes
     />
     more controls

</hbj:control> comment: end of tag for HTMLB controls with body

Scriptlet

A scriptlet can contain any number of language statements, variable or method declarations, or expressions that are valid in the page scripting language.

Within a scriptlet, you can do any of the following:

· Declare variables or methods to use later in the file.

· Write expressions valid in the page scripting language.

· Use any of the implicit objects or any object declared with a <jsp:useBean> element.

· Write any other statement valid in the scripting language used in the JSP page (if you use the Java programming language, the statements must conform to the Java Language Specification).

Any text, HTML tags, or JSP elements must be written outside the scriptlet.

Scriptlets are executed at request time, when the JSP container processes the client request. If the scriptlet produces output, the output is stored in the out object.

Certain attributes (if the column "JSP taglib" in the attribute table to each control has no entry) can only be assigned using scriptlets. The scriptlet has to be placed in the tag body of the HTMLB control. The scriptlet starts with <% and ends with %>. The following example uses the button control and sets some attributes with a scriptlet.

Example

  <hbj:button
     id="OrderConfirm"
     width="100px"
     tooltip="Click here to confirm order"
     onClick="ProcessConfirm"
     disabled="false"
     design="STANDARD"
     >
     <%       comment: start scriptlet in the tag body
     //  set the text for the button
       OrderConfirm.setText("Confirm");
     // set "width" - this overrides "width" set in attribute section
       OrderConfirm.setWidth("125px");
     %>       comment: end of scriptlet
  </hbj:button>

Result

This graphic is explained in the accompanying text

Enumeration Values

In the classlib column some values have to be set as enumeration values. In the classlib column you find the class name and the enum (separated by a dot).

Example

breadcrumb.setSize(BreadCrumbSize.MEDIUM)

For an executable program you have to add the location of the enum. That is:

com.sap.htmlb.enum.

So according to the example above you have to specify:

Your program:
breadcrumb.setSize(com.sap.htmlb.enum.BreadCrumbSize.MEDIUM);

To save some typing when you enumeration values more often the package can be imported:

<%@ page import="com.sap.htmlb.enum.BreadCrumbSize, ..... " %>

Boolean Values

Taglib:
Boolean values are specified as string and can be lowercase and/or uppercase.

Classlib:
Boolean values are specified as boolean and have to be specified only in lowercase characters.