Appendix B Gateway Directives

This appendix describes directives used in gateway HTML object class and search result templates. The appendix contains the following sections:

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:


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:

Structure of an HTML Template for Directory List

Directory entry list templates generally have the following structure:

<HTML>











Please try a different search....

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  directive appears within an URL and is used in the invocation of CGIs through GET operations.  can appear anywhere on a line, and more than once within a line. The gateway CGI reading  replaces it with the gateway context it has at the time.

Arguments

None.

Example

<a href=/clients/dsgw/bin/lang?<?-- GCONTEXT -->&file=auth.html>click</a>

PCONTEXT

The  directive must appear on a line by itself. The gateway CGI reading  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 (its values). This directive must appear within a DS_ENTRYBEGIN...DS_ENTRYEND 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, it is assumed to be syntax=cis. Legal values are described in Table B-1.

Table B-1 DS_ATTRIBUTE: Display of syntax Argument


syntax	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 Table B-2 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.

options=option. Modifies how the attribute is displayed. Legal values are described in Table B-3.

Table B-3 DS_ATTRIBUTE: Dsiplay 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 displays 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 -- embeds delete checkboxes and Javascript array information. Needed for "Find and Add."
unique	Enforce uniqueness when adding or editing values.
quoted	Applies when using Javascript -- to have the value returned be surrounded by quotes.

defaultvalue=default-value. Supplies a default value for the attribute, which is shown if no attribute was read from the Directory 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=Example Corporation,c=US, the output will be James Doe, Example 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 the number is preceded by a greater-than sign, then at least that number of rows is 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 that number of columns. If a plus (+) sign is given before the number, then the attribute is given that number number of extra columns. For example, if the value is 10 characters wide, and the 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 that number of columns.

numfields=number, numfields=+number, numfields=>number. Controls the number of editable fields displayed when editing. If the 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 the number is preceded by a greater-than sign (>), then at least that numberof 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).

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 for which a given template should be used.

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 object class 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.

Example

DS_VIEW_SWITCHER

Display a widget that provides access to all views that are appropriate for this entry. 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_SORTENTRIES

Specifies that entries should be sorted; typically used within list templates. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRYEND 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_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 John Doe, the directive

will produce the following

HTML: VALUE="John Doe"

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_ENTRYEND 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_DELETEBUTTON

Displays a button which, when clicked, allows deletion of an entry. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRYEND 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_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_ENTRYEND 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_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_ENTRYEND 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_NEWPASSWORD

Displays an HTML password INPUT field. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRYEND 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_ENTRYEND block.

Arguments

None.

DS_OLDPASSWORD

Displays an HTML password field for the old password. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRYEND block.

Arguments

None.

DS_HELPBUTTON

Displays a help button.

Arguments

topic=topic_name. Causes the Help System to open the given topic name.

Example

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_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_ENTRYEND block.

Arguments

None.

DS_END_ENTRYFORM

Causes the gateway to emit a </FORM> tag. This directive must appear within a DS_ENTRYBEGIN...DS_ENTRYEND block.

Arguments

None.

DS_EMIT_BASE_HREF

Emit a <BASE> tag that contains the base URL for the CGI that was executed.

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

IF/ ELSE/ ELIF/ ENDIF

Set of directives that can be used to include HTML text conditionally.

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 ENDIF


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?
AttributeHasThisValue	attr syntax value	Does the attribute attr with syntax syntax have value as one of its values?
AdminServer *	none	Are we running under the Administration Server?
DirectoryIsLocalDB *	none	Is the Directory Server using the LDAP local database?
PostedFormValue *	name value	Is a form variable called name present that has value as its value?

Note

Conditions marked with an asterisks (*) are supported in all the directory gateway CGIs, not just dosearch and edit.

Examples

The entry was last modified by 


 // this entry is a mail recipient... do something special here

Miscellaneous Directives

BODY

Emit HTML <BODY> element that includes color information.

Arguments

extrahtml

Examples

COLORS

Set color information to be used in subsequent BODY directives.

Arguments

html-color-info

Example

TITLE

Emit HTML <HEAD>, <TITLE>, and <BODY> elements.

Arguments

title-string

Example

ENDHTML

Emit </BODY></HTML> sequence

Arguments

None.

HELPBUTTON

Display a Help button (same effect as DS_HELPBUTTON directive but can be used from any gateway directory CGI).

Arguments

topic

Example

INCLUDE

Include the contents of another HTML file. You cannot nest include directives.

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

INCLUDECONFIG

Include the contents of an HTML-based configuration file. You cannot nest include directives.

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

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_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.

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_GATEWAY_VERSION

Emit a string containing the version of the directory gateway CGI being executed.

Arguments

None.

Example

IF/ ELSE/ ELIF/ ENDIF

Same as those supported by the dosearch and edit CGIs. However, conditionals marked with an asterisk (*) are supported.

Contents

Index

DocHome

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments

last updated November 26, 2004