Appendix B
Gateway Directives
This appendix describes directives used in gateway HTML object class and search result templates. Contents include:
Introduction
The display of LDAP directory information is controlled by HTML template files containing directives. Directives are HTML comments that can be interpreted by the gateway CGIs.
The most commonly used directive is DS_ATTRIBUTE, used to display attributes present in LDAP entries. Here are some other examples of directives:
<!-- DS_HELPBUTTON "topic=HELP-ME-NOW" -->
<!-- DS_ATTRIBUTE "attr=sn" "size=>20" -->
<!-- IF "BoundAsThisEntry" -->
<!-- ENDIF -->
|
Note
|
With the exception of GCONTEXT, each directive must start at the beginning of a line and be contained on a single line in the HTML file. Most of the directory server gateway directives begin with DS_.
|
Structure of an HTML Template
Directory entry display, edit, and add templates generally have the following structure:
<HTML>
<HEAD>
<!-- DS_ENTRYBEGIN -->
<!-- DS_EMIT_BASE_HREF -->
<!-- BODY -->
<!-- DS_LAST_OP_INFO -->
<!-- DS_BEGIN_ENTRYFORM -->
<!-- attribute directives, e.g., -->
<!-- DS_ATTRIBUTE "attr=givenName" "size=>20" -->
<!-- DS_ATTRIBUTE "attr=sn" "size=>20" -->
<!-- etc. -->
<!-- DS_SAVEBUTTON "label= SAVE " -->
<!-- DS_END_ENTRYFORM -->
<!-- DS_ENTRYEND -->
<!-- ENDHTML -->
Structure of an HTML Template for Directory List
Directory entry list templates generally have the following structure:
<HTML>
<!-- TITLE "Search Results" -->
<!-- DS_SEARCHDESC -->
<!-- IF "FoundEntries" -->
<!-- DS_SORTENTRIES "attr=XXX" -->
<!-- DS_ENTRY_BEGIN -->
<!-- stuff that is repeated for each entry found, e.g., -->
<!-- DS_ATTRIBUTE "attr=dn" "syntax=dn" -->
<!-- etc. -->
<!-- DS_ENTRYEND -->
<!-- ELSE -->
<!-- stuff to be rendered if no entries were found, e.g.,-->
Please try a different search....
<!-- ENDIF -->
<!-- ENDHTML -->
Context-Related Directives
The context-related directives GCONTEXT and PCONTEXT appear within a line, and are not required to appear at the beginning of a line. This is an exception to the rule. All other directives must appear at the beginning of a line, to be recognized by the directory server.
GCONTEXT
The <!-- GCONTEXT--> directive appears within an URL and is used in the invocation of CGIs through GET operations. <!-- GCONTEXT--> can appear anywhere on a line, and more than once within a line. The gateway CGI reading <!--GCONTEXT --> replaces it with the gateway context it has at the time.
Arguments
None.
Example
<a href=/dsgw/bin/lang?<?-- GCONTEXT -->&file=auth.html>click</a>
PCONTEXT
The <!-- PCONTEXT--> directive must appear on a line by itself. The gateway CGI reading <!--PCONTEXT --> replaces it with a hidden variable indicating the context it has at the time.
Arguments
None.
Example
<form method=post action=/dsgw.bin/dosearch>
<input type=hidden name=dn valute="">
<!-- PCONTEXT -->
<form>
Entry-related Directives
Entry-related directives are supported by the dosearch and edit CGIs.
DS_ENTRYBEGIN
Delimits the beginning of an entry. The DS_ENTRYBEGIN directive is used in display or edit templates to mark the start of an LDAP entry and in list templates to mark the beginning of a section which should be repeated for each entry which is returned by the search. Always paired with DS_ENTRYBEGIN.
Arguments
None.
DS_ENTRYEND
Delimits the end of an entry. Always paired with DS_ENTRYBEGIN.
Arguments
None.
DS_ATTRIBUTE
The DS_ATTRIBUTE directive is replaced with the contents of an attribute (i.e., its values). This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block.
Arguments
attr=attribute-name. Displays the named attribute. Any attribute may be displayed. The special attribute "dn" is recognized and causes the distinguished name of the entry to be displayed.
syntax=syntax-type. Displays the attribute as if it were of syntax syntax-type. If no syntax= argument is given, syntax=cis is assumed. Legal values are described in the following table:
Table B-1 DS_ATTRIBUTE: Display of syntax Argument
|
syntax type
|
description
|
display as
|
|
tel
|
Display as a telephone number
|
text
|
|
dn
|
Display as a distinguished name
|
href (a link to an LDAP entry)
|
|
mail
|
Display as a mailto: URL
|
href (mailto: URL)
|
|
mls
|
Display as a multi-line string
|
text
|
|
time
|
Display as date/time
|
text
|
|
cis
|
Display as a case-ignore string
|
text
|
|
url
|
Display as a labeled URL
|
href (URL)
|
type=how-to-display. Renders the attribute on-screen in a particular format. Legal values described in the following table correspond roughly to HTML form element names.
Table B-2 DS_ATTRIBUTE: Display of type Argument
|
type
|
display
|
|
text
|
Display as text
|
|
textarea
|
Show as an HTML TEXTAREA
|
|
radio
|
Show as a radio button
|
|
checkbox
|
Show as a check box
|
|
password
|
Show as an HTML password text box (characters are not echoed)
|
|
hidden
|
Show values in hidden form fields (not supported in DS 1.0)
|
options=option. Modifies how the attribute is displayed. Legal values are described in the following table:
Table B-3 DS_ATTRIBUTE: Display of options Argument
|
options
|
display
|
|
sort
|
Sort the attribute values
|
|
nolink
|
Do not attempt to display the attribute as a hyperlink
|
|
dntags
|
Applies only when using syntax=dn - tags are displayed when showing DNs. Normally they are not displayed.
|
|
dateonly
|
Applies only when using syntax=time - only display the date, omitting the time
|
|
readonly
|
When editing, do not allow the user to modify the attribute's value
|
|
dnpicker
|
Applies only when using syntax=dn - embed delete checkboxes and Javascript array information. Needed for "Find and Add" (not supported in DS 1.0).
|
|
unique
|
Enforce uniqueness when adding or editing values (not supported in DS 1.0).
|
defaultvalue=default-value. Supplies a default value for the attribute, which is shown if no attribute was read from the LDAP server.
within=string-to-embed-in. For each value, outputs the text in string-to-embed-in, replacing all occurrences of the string --value-- with an attribute value.
href=href. Specifies the HREF used for the hyperlink. For example, you can specify anonMouseOver JavaScript handler using the "href=" option.
hrefextra=extra-text. Specifies additional text which is inserted after the closing quote of the HREF tag.
dncomponents=number. Gives the number of DN components to show when displaying a DN. For example, if you include "dncomponents=2" and display the DN "cn=James Doe, o=Siroe Corporation, c=US", the output will be "James Doe, Siroe Corporation."
size=number. Same as cols argument.
rows=number, rows=+number, rows=>number. Controls the number of rows used to display the entry. For type=text, this controls the number of editable HTML INPUT fields. For type=textarea, this controls the number of rows in the textarea. If number is preceded by a plus (+) sign, then number extra rows are included. If number is preceded by a greater-than sign, then at least number rows are included.
cols=number, cols=+number, cols=>number. Controls the width of the displayed attribute. If a number is given by itself, then the attribute is displayed with exactly number columns. If a plus (+) sign is given before number, then the attribute is given number extra columns. For example, if the value is 10 characters wide, and number is 10, then 20 columns are used when displaying the number. If a greater-than sign (>) is given before number, then the displayed width is at least number columns.
numfields=number, numfields=+number, numfields=>number. Controls the number of editable fields displayed when editing. If number is preceded by a plus (+) sign, then the number of fields displayed is however many values were read from the server plus number. If number is preceded by a greater-than sign (>), then at least number values are displayed when editing.
true=string. Label used for Boolean values that are true.
false=string. Label used for Boolean values that are false.
value=string. Value associated with an instance of a checkbox that is used to display strings values (not syntax=bool values) (Not supported in DS 1.0)
Examples
<!-- DS_ATTRIBUTE "attr=dn" "syntax=dn" "dncomponents=2"
"options=nolink" -->
<!-- DS_ATTRIBUTE "attr=givenName" "cols=>32" -->
<!-- DS_ATTRIBUTE "attr=sn" "cols=>32" -->
<!-- DS_ATTRIBUTE "attr=uid" "numfields=1" "cols=>16"
"options=unique" -->
<!-- DS_ATTRIBUTE "attr=mail" "syntax=mail" "cols=>20" -->
<!-- DS_ATTRIBUTE "attr=telephoneNumber" "syntax=tel" "cols=>16"
"numfields=+1" -->
<!-- DS_ATTRIBUTE "attr=modifyTimestamp" "syntax=time"
"defaultvalue=N/A" "options=readonly" -->
<!-- DS_ATTRIBUTE "attr=modifiersName" "syntax=dn"
"defaultvalue=N/A" "options=readonly" -->
<!-- DS_ATTRIBUTE "attr=mailDeliveryOption" "type=CHECKBOX"
"value=mailbox" -->
<!-- DS_ATTRIBUTE "attr=mailDeliveryOption" "type=CHECKBOX"
"value=native" -->
<!-- DS_ATTRIBUTE "attr=mailForwardingAddress" "syntax=mail"
"type=textarea" "rows=2" "cols=30" -->
DS_OBJECTCLASS
Describes the type of directory entries a given template should be used for.
Arguments
value=value1,value2,...valueN. Specifies a list of object class values. For a template file to be used to display a given entry, all of the values given must be values in the entry's objectclass attribute.
|
Note
|
The gateway does not read the template files to determine which template to use. Instead, it reads the dsgw.conf file and scans the "template" lines in that file.
You can generate a series of template lines, suitable for inclusion in the dsgw.conf file, by opening the URL http://host/ds/templateindex, where host is the name of the host running the directory server gateway. The templateindex CGI program will scan all the gateway template files and read the DS_OBJECTCLASS attributes, and then will generate a series of "template" lines.
|
Example
<!-- DS_OBJECTCLASS "value=person,inetOrgPerson" -->
DS_VIEW_SWITCHER
Display a widget that provides access to all views that are appropriate for this entry (Not supported in DS 1.0). Usually this directive will be used without any arguments at all, which causes a table that contains one cell for each available view to be displayed.
Arguments
prefix=text. HTML text to emit before view elements (optional)
suffix=text. HTML text to emit after view elements (optional)
curprefix=text. HTML text to emit before the link to the current (active) view element (optional)
cursuffix=text. HTML text to emit after the link to the current view element (optional)
altprefix=text. HTML text to emit before each link to an alternative view element (optional)
altsuffix=text. HTML text to emit after each link to an alternative view element (optional)
Example
<!-- DS_VIEW_SWITCHER -->
DS_SORTENTRIES
Specifies that entries should be sorted; typically used within list templates. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block. Up to two DS_SORTENTRIES directives are honored (the attribute from the first one that appears is used as the primary sort key and the second one is used as a secondary sort key).
Arguments
attr=attrname. Sort the entries in ascending order by attrname.
Example
To sort a list of entries by common name:
<!-- DS_SORTENTRIES "attr=cn" -->
DS_SEARCHDESC
Specifies that text describing the type of search done should be displayed. For example, "Found 14 entries where the phone number ends with '25'".
Arguments
None.
DS_POSTEDVALUE
Echoes the contents of an arbitrary posted form variable within a VALUE= parameter.
Arguments
name=varname. The name of the form variable.
Example
If a variable called searchstring is posted and contains the text Mark Smith, the directive:
<!-- DS_POSTED_VALUE "name=searchstring" -->
will produce the following
HTML: VALUE="Mark Smith"
DS_EDITBUTTON
Displays a button which, when clicked, brings up an editable view of an entry. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block. Typically used in display templates.
Arguments
label=text. Use "text" as the label on the button. If not provided, the text "Edit" is used.
Example
<!-- DS_EDITBUTTON "label=Edit Person" -->
DS_DELETEBUTTON
Displays a button which, when clicked, allows deletion of an entry. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block. Typically used in edit templates.
Arguments
label=text. Use "text" as the label on the button. If not provided, the text "Delete" is used.
Example
<!-- DS_DELETEBUTTON "label=Remove Person" -->
DS_SAVEBUTTON
Displays a button which, when clicked, saves changes to an entry. Typically used in edit templates. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block.
Arguments
label=text. Use "text" as the label on the button. If not provided, the text "Save" is used.
checksubmit=javascript.Submit changes only if javascript expression is true.
Examples
<!-- DS_SAVEBUTTON "label=Save Changes" -->
<!-- DS_SAVEBUTTON "checksubmit=formDataValid()" -->
DS_EDITASBUTTON
Displays a button which, when clicked, allows editing of an entry using a non-default template. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block.
Arguments
label=text. Use "text" as the label on the button. If not provided, the text "Edit As" is used.
template=template-name. Use the template name template-name when editing.
Example
A button to bring up edit-passwd.html template:
<!-- DS_EDITASBUTTON "label=Change Password" "template=passwd" -->
DS_NEWPASSWORD
Displays an HTML password INPUT field. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block.
Arguments
None.
DS_CONFIRM_NEWPASSWORD
Displays an HTML password INPUT field. The gateway compares the value supplied by the user in this field to the value in the DS_NEWPASSWORD field, and saves only the new password value if the two match. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block.
Arguments
None.
DS_OLDPASSWORD
Displays an HTML password field for the old password. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block.
Arguments
None.
DS_HELPBUTTON
Displays a help button.
Arguments
topic=topic_name. Causes the iPlanet Help System to open the given topic name.
Example
<!-- DS_HELPBUTTON "topic=MODIFYPASSWD" -->
DS_CLOSEBUTTON
Displays a Close button, which causes the containing window to be closed.
Arguments
label=text. Use "text" as the label on the button. If not provided, the text "Close Window" is used.
Example
<!-- DS_CLOSEBUTTON "label=Cancel" -->
DS_BEGIN_ENTRYFORM
Causes the gateway to emit an HTML FORM directive, and several hidden form elements which are required for proper operation of the gateway. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block.
Arguments
None.
DS_END_ENTRYFORM
Causes the gateway to emit a </FORM> tag. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRY_END block.
Arguments
None.
DS_EMIT_BASE_HREF
Emit a <BASE> tag that contains the base URL for the CGI that was executed. (Not supported in DS 1.0)
Arguments
None.
DS_DNEDITBUTTON
Used to edit DN-valued attributes, such as group member.
Arguments
label=
template=
attr=
desc=
DS_BEGIN_DNSEARCHFORM
Used to edit DN-valued attributes, such as group member.
Arguments
None.
DS_ATTRVAL_SET
Display an attribute based on an "attrvset" as defined in the dsgw.conf file.
Arguments
set=name. Use information from attribute value set name
prefix=text. HTML text to emit before each attribute value element (optional)
suffix=text. HTML text to emit after each attribute value element (optional)
Plus any of the arguments supported by the DS_ATTRIBUTE directive.
Example
<!-- DS_ATTRVAL_SET "set=CAL" "attr=nsLicensedFor" "type=checkbox"
"prefix=<TR><TD>" "suffix=</TD></TR>" -->
IF/ ELSE/ ELIF/ ENDIF
Set of directives that can be used to conditionally include HTML text
Arguments for IF and ELIF
condition. Boolean condition; if true, include following block of text
!condition. Boolean condition; if false, include following block of text
Arguments for ELSE and ENDIF
None.
Table B-4 Conditions supported for ELSE and ENDI
|
Condition
|
Arguments
|
Description
|
|
FoundEntries
|
none
|
Are there any entries being displayed?
|
|
Adding
|
none
|
Is the entry being edited a new entry?
|
|
Editing
|
none
|
Are we editing an entry?
|
|
Displaying
|
none
|
Are we just displaying an entry?
|
|
Bound
|
none
|
Is the user authenticated?
|
|
BoundAsThisEntry
|
none
|
Is the user authenticated as the entry we are displaying?
|
|
AttributeHasValues
|
attr mincount
|
Does the attribute attr have at least mincount values? (Not supported in DS 1.0)
|
|
AttributeHasThisValue
|
attr syntax value
|
Does the attribute attr with syntax syntax have value as one of its values? (Not supported in DS 1.0.)
|
|
AdminServer *
|
none
|
Are we running under the Administration Server? (Not supported in DS 1.0.)
|
|
DirectoryIsLocalDB *
|
none
|
Is the directory server using the LDAP local database? (Not supported in DS 1.0.)
|
|
PostedFormValue *
|
name value
|
Is a form variable called name present that has value as its value? (Not supported in DS 1.0.)
|
|
Note
|
Conditions marked with an asterisks (*) are supported in all the directory gateway CGIs, not just dosearch and edit.
|
Examples
<!-- IF "!DirectoryIsLocalDB" -->
The entry was last modified by <!-- DS_ATTRIBUTE
"attr=modifiersName" "syntax=dn" "defaultvalue=N/A"
"options=readonly" -->
<!-- ENDIF ---->
<!-- IF "AttributeHasThisValue" "objectclass" "cis" "mailRecipient"
--> // this entry is a mail recipient... do something special here
<!-- ENDIF ---->
Miscellaneous Directives
BODY
Emit HTML <BODY> element that includes color information. (Not supported in DS 1.0).
Arguments
extrahtml
Examples
<!-- BODY -->
<!-- BODY "onLoad=setDefaults()" -->
COLORS
Set color information to be used in subsequent BODY directives. (Not supported in DS 1.0).
Arguments
html-color-info
Example
<!-- COLORS "TEXT=#000000 BGCOLOR=#FFFFFF LINK=#FF0000 VLINK=#8000FF
ALINK=#FF0000" -->
TITLE
Emit HTML <HEAD>, <TITLE>, and <BODY> elements. Supported by all directory gateway CGIs.
Arguments
title-string
Example
<!-- TITLE "Search Results" -->
ENDHTML
Emit </BODY></HTML> sequence
Arguments
None.
HELPBUTTON
Display a Help button (same effect as DS_HELPBUTTON directive, but can be used from any gatewaydirectory CGI) (Not supported in DS 1.0)
Arguments
topic
Example
<!-- HELPBUTTON "MODIFYPASSWD" -->
INCLUDE
Include the contents of another HTML file. Note that you cannot nest include directives. (Not supported in DS 1.0)
Arguments
filename. The name of the file to include. This is relative to the html/ directory where files such as display-inetorgperson.html are located.
Example
<!-- INCLUDE extra.html -->
INCLUDECONFIG
include the contents of an HTML-based configuration file. Note that you cannot nest include directives.(Not supported in DS 1.0)
Arguments
filename. The name of the file to include. This is relative to the config/ directory where files such as dsgw.conf are located.
Example
<!-- INCLUDE dsgw-orgperson.conf -->
DS_LAST_OP_INFO
Display a string that shows the result of the last domodify run. Note that this directive works only when the genscreen or edit CGIs are invoked via domodify's completion_javascript feature.
Arguments
prefix=prefix-text. Text displayed before the last operation info.
suffix=suffix-text. Text displayed after the last operation info.
Example
<!-- DS_LAST_OP_INFO "prefix=<P><FONT SIZE=%2B1>The user "
"suffix=</FONT>" -->
DS_LOCATIONPOPUP
Emit an HTML form element that contains a list of all the o's and ou's that are in the directory. If there is only one, a hidden field is produced; otherwise an HTML select field is produced. (Not supported in DS 1.0)
Arguments
name=varname. The name of the form element that is emitted
prefix=select_prefix. Text that is output before a select element
suffix=select_prefix. Text output after a select element
Example
<!-- DS_LOCATIONPOPUP "name=base" "prefix=Choose a searchbase" -->
DS_GATEWAY_VERSION
Emit a string containing the version of the directory gateway CGI being executed. (Not supported in DS 1.0).
Arguments
None.
Example
<!-- DS_GATEWAY_VERSION -->
IF/ ELSE/ ELIF/ ENDIF
Same as those supported by the dosearch and edit CGIs. However, conditionals marked with an asterisk (*) are supported.