phpLDAPadmin comes with several built in templates. You may, and are encouraged to, create your own custom templates. Since all templates are stored in the templates/ subdirectory you may want to create your own templates with your own prefix (see server:custom:pages_prefix) used in the file name. We will never ship a distribution of phpLDAPadmin which contains templates with the prefix "custom_" if you want to use that prefix. If you do use "custom_" for your templates, this will ensure that they won't get over written if you are upgrading phpLDAPadmin.
See the config:appearance:custom_templates_only option if you want to completely disable the default templates and use your custom set of templates, without deleting the originals.
TemplateDTD Template DTD Draft Proposed.
There are two types of templates:
- Creation Templates, these templates are used when a new entry is created.
- Modification Templates, these templates are used when you edit an existing entry.
- Make a copy of an existing template in the templates directory. Name the file something like custom_MyTemplateName.xml.
- Start editing this file to suit your needs. Don't worry about any other files or subdirectories (like creation or modification) everything you need for your template will go in the .xml file you are editing.
- The first edit you should make is to ensure that
<title>My template title</title> <visible>1</visible>
are set. Save, goto your phpldapadmin page, select "purge" see the FAQ for why and then check to see if your new template is listed. If you get an error message after clicking the "Create new entry here" link, then it's a 99% sure bet that there is a syntax error in one of the templates in the template directory - most likely your new template!
Once your new template shows up in the template list, it's a just a matter of refining your template until it's working the way you like. There are plenty of examples in the other template files to copy, below is an example for using the "select from directory helper":
<attribute id="attributeID"> <display>Nice name for attributeID</display> <helper> <location>side</location> <value>=php.DrawChooserLink(attributeID,0)</value> </helper> </attribute>
Template Header Configuration
The header describes the template, and its attributes are mainly used to:
- Define the template name when listing all the templates and when creating a new entry,
- Define the icon used to represent this template.
- Define which attributes make up the RDN.
- Define the template state (valid|invalid) and container restrictions (based on regular expression match)
It can have the following items:
|askcontainer||0/1||When set to 1, will enable the user to change the container that the new object will be created in.|
|description||string||Template description, used in the list of templates when you hover over the template.|
|icon||url||This will display an icon next to the title in the list of templates. It is relative to the theme directory see config:appearance:theme.|
|invalid||0/1||Whether to disable this template, and thus it is not selectable in the list of templates.|
| || || |
|noleaf||0/1||Whether this entry represents a leaf. If the entry is a leaf, no child entries can be created beneath it, and the "Create a child entry" link is hidden. (Only applicable in modification templates)|
|rdn||rdn||The RDN for the entry being created. (An objectClass defined in the XML file must provides this attribute.)|
|regexp||regexp||Can be used to limit when a template can be used. For example, you may want to only create posixAccount records under the ou=People part of your tree, so by using a regexp of ^ou=People in posixAccount.xml will mean that template will only be usable if you create an entry from a branch starting with ou=People|
|title||string||Template title, is used when displaying the list of templates, and on the template form itself.|
|visible||0/1||Whether this template should be visible in the list of templates.|
<askcontainer>1</askcontainer> <icon>images/ou.png</icon> <description>t_new_posixgroup</description> <rdn>cn</rdn> <regexp>^ou=.*,</regexp> <title>posix_group</title> <visible>1</visible>
Template Body Configuration
The template engine will automatically prompt the user for all MUST attributes as defined by the ObjectClasses section of the template file. You can override here how those attributes appear, and additionally ask forMAY attributes as well.
This section can be used to:
- Change the description, so that something more meaningful is asked,
- Populate some default values,
- Hide the attribute and populate it automatically,
- Use the value to pre-fill another attribute.
- The attribute must be defined by an objectClass defined in the ObjectClasses section, otherwise it will be silently ignored.
- At least one objectClass must be defined, however, you can list as many as you want.
- One of the objectClass(es) must be a structural objectClass, otherwise the template will be automatically disabled.
- If your LDAP schema doesnt provide the objectClass, then the template will be automatically disabled.
- ObjectClasses must be defined using the id= syntax - please see the example below.
<ObjectClasses> <ObjectClass id="posixGroup"></ObjectClass> </ObjectClasses>
Attributes are optional, as PLA will automatically ask for all the MUST attributes as defined by the ObjectClasses defined in the template (see above).
They can have the following items:
|default||string||Where <value> attributes generate a pick list, this will pre-select the default value.|
|display||string||Display this name instead of displaying the attribute name.|
|helper||Helper attributes are described below.|
|hidden||0/1||Makes the attribute hidden in the form, if you wish to use it remember to provide a default value.|
|hint||string||Used to provide a short hint. Will show to the right of the attribute.|
|icon||url||URL to an icon which will be displayed next to the attribute display (this is relative to the theme directory - see config:custom:theme|
|max||integer||Maximum number of input fields to show (Added in 188.8.131.52)|
|order||int||This can be used to order the attributes on a page. If order is not provide, values will be displayed in order defined in the template.|
|page||int||Will make the template into a multi-page template, and this attribute will be asked for when the user press next and gets to this page number. The parameter is optional. If there are no page attributes, then all attributes will be asked for on 1 page.|
|post||PostValue functions||Call this function when this page is posted (before objectCreation).|
|size||int||Number of rows for a "multiple select field". If set to 0 or omitted, multiple checkboxes will be used instead.|
|spacer||0/1||Will draw a horizontal line after this attribute.|
|type||Force the form to use this HTML input type.|
|value||Value Functions|| Provide a default value for this attribute. The default can be either static: eg: <value>my value</value>, or it can be dynamic calling one of the internal Value Functions, eg: <value>=php.PickList(/;(objectClass=posixGroup);gidNumber;%cn%)</value>.
When using a selection list, the syntax for value is as follows: <value id="value">Display</value> where "value" is what will be stored in the LDAP server, and "Display" is what is presented to the user
Some attributes can also leverage a helper attribute, which is used to get the attribute a value, or alter its appearance on the form, however, the helper's value will not be stored in the LDAP server.
Examples of helpers include:
- Input the encoding type for a password field,
- Draw a DN chooser link, where attributes can accept a DN value
|display||string||Display this name next to the helper value.|
|id||Name this attribute with this HTML post ID, so that it can be used in any post submission, pre object creation functions.|
|location||side||Location of the helper field/icon.|
|value||Value Functions||Can be either a static value eg: md5, or a dynamic value by calling a function using the same syntax and available functions as default above. There can be multiple value statements, which will produce a dropdown list.|
The phpLDAPadmin template engine will perform some basic validation of templates. It will mark templates invalid if:
- There is no structural objectClass,
- There are no attributes defined as RDN attributes.
- The attribute selected as an RDN attribute is not defined by the schema of the objectClass(es),
- the template engine will silently remove attributes that are defined in the template, but not defined by the schema of the objectClass(es),
- automatically include any MUST attributes that the schema defines, but are not included in the template.
User Contributed Templates
User contributed templates are available here