Netscape Directory Server Gateway Customization Guide: Appendix B Gateway Directives

Gateway Customization Guide
Netscape Directory Server

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

Context-Related Directives

Entry-Related Directives

Miscellaneous Directives

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:

<HTML>
<HEAD>













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="">

<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 (that is, 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 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: 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".

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 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)

Examples












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.

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

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 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?

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. Note that 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. Note that 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.

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	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	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".
`unique`	Enforce uniqueness when adding or editing values.
`quoted`	Applies when using Javascript—to have the value returned be surrounded by quotes.

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?

Last Updated October 31, 2003


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


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.


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