MpLDAP Documentation Version 1.4.3 directory up  
 
 

Configuration


Directories and files

After extracting you will find the following directory structure (depending on what package you downloaded):

directory file description package
MpLDAP MpLDAP-add MpLDAP-devel
. *.* This is the main application directory X X X
  index.php Central file that displays the search form and the result table. X X X
  messages.ini.php MpLDAP General Language Dependent Messages (MGLDMF)
(i.e. info and error messages)
X X X
  mpldap.ini.php MpLDAP Main Configuration File (MMCF) X X X
  readme.txt Short readme file. X X X
_customer *.*

This directory is for your (the customer's) use. This directory will never get overwritten when updating to a new release.

X X  
_customer/css *.* Your MpLDAP CSS Files (MCF) that you create.
(i.e. "_customer/css/my-mpldap.css")
X X  
_customer/resources *.* Your MpLDAP Resource Definition Files (MRDF) that you create.
(i.e. "_customer/resources/my-resource.ini.php")
X X  
_customer/extensions *.* Include files for extending MpLDAP functions. X X  
css *.* This directory contains MpLDAP CSS Files (MCF). MpLDAP uses only one at a time but which to be used is defined in the resource definition files. X X X
  mpldap.css Reference CSS file. It contains all possible definitions with their explanation. Copy this file, edit it and change the entry "css_filename" in a MRDF file so the new css file is linked and used. X X X
docs *.* This directory contains the documentation (i.e. this file) X X  
images *.* Images and icons. X X X
js *.* Javascript file(s) X X X
mpldap *.* This directory contains PHP files (i.e. classes) X X X
  mpldap.php The main MpLDAP class X X X
  mpldap-constants.php Defining constants X X X
  mpldap-utils.php Utility functions X X X
phpdoc *.* API / PHPDocumenation   X  
resources *.* This directory contains some sample MpLDAP Resource Definition Files (MRDF). X X X
  !resource-template.ini.php Reference definition file. It contains all possible definitions with their explanation. Copy this file and change it for a new resource (ldap server and / or query). X X X
templates *.* Only templates. They are not used by MpLDAP. You may copy these files into the appropriate _customer subdirectory X X  
templates/extensions *.* Example include files for extending MpLDAP functions. X X  

 


Terms and definitions

term definition
configuration file

MpLDAP is configurated by three different kinds of configuration files (aka INI files). All are Windows like INI files with sections in it:

  • MpLDAP Main Configuration File (MMCF)
  • MpLDAP General Language Dependent Messages (MGLDMF)
  • MpLDAP Resource Definition Files (MRDF)
message

A message is a language dependent string displayed to the user. Messages are defined in

  • MpLDAP General Language Dependent Messages (MGLDMF)
    Messages that are common to all resources (i.e. LDAP error messages or info messages)
  • MpLDAP Resource Definition Files (MRDF)
    Eech resource may have independant messages like the table headers for the attributes that the LDAP server sends.

 


Quick and dirty configuration

  • Resource Definition File (MRDF)
    • Identify a working resource definition file ("resources/*.ini.php")
    • Copy this file in the directory "_customer/resources" with a new appropriate name
      (i.e. "_customer/resources/mydefinition.ini.php")
    • Use the TaE (try and error) method to edit this new file. Especially look at these entries
      • [options] => filters_mandatory: best to leave it empty
      • [options] => filters
      • [options] => attributes
      • [ldap] => server: enter the correct server name
      • [ldap] => port: normally you should leave it blank, otherwise enter the port number for that server)
      • [ldap] => user, [ldap] => password: Leave blank for anonymous access, otherwise...
      • [basedn]: edit the values for the correct base DN
      • [messages] => basedn_x: edit this to reflect the values you entered above
      • [messages] => attributes_x: edit this according your changed / new attributes
      • [messages] => filters_x: edit this according your changed / new filters
  • Main Configuration File (MMCF), normally "mpldap.ini.php"
    • Create a new entry in the section [resources] that points to your new resource definition file
      (i.e. mydefinition = "_customer/resources/mydefinition.ini.php"
  • General Language Dependent Messages (MGLDMF), normally "messages.ini.php"
    • Create a new entry in the section [messages]
      (i.e. resources_mydefinition = "MyDefinition: This is my first new LDAP query definiton")

Now open MpLDAP and try!


Step by step configuration incl. update

If you run into problems: Don't hesitate to drop a mail to fwhamm@users.sourceforge.net.

1. When updating: make a backup / copy your MpLDAP installation

Move or copy the complete MpLDAP application directory to another place (i.e. from "htdocs/mpldap" to "copydir/mpldap").

2. Extract the new version

Extract the MpLDAP archive (i.e. mpldap-1.4.2.zip) to your designated or already existing MpLDAP application directory (i.e. "htdocs/mpldap").

When updating

Existing files should be overwritten.

3. MpLDAP Main Configuration File (MMCF)

Edit the file "mpldap.ini php" and correct the values to your need according to the comments in that file. You should especially change the following entries:

  • [options] => "session..."
    You should change the session settings to your domain, path etc.
  • [defaults] => "resource"
    change that value to point to one of your MpLDAP Resource Definition Files (MRDF) in the "_customer/resources" directory
  • [resources]
    Each entry (row) must point to one of your MpLDAP Resource Definition Files (MRDF) that you want to offer your users as setting (see below). Uncomment those you don't want to offer.

When updating

Look at your old "copydir/mpldap.ini php" file for your old settings.

4. MpLDAP Resource Definition Files (MRDF)

A MpLDAP resource has or may have unique settings:

  • the connection to a LDAP server
  • the filters the use may apply
  • the attributes MpLDAP will retrieve from the server
  • different colors, fonts (because of different style sheets)

All settings for a resource are made within one resource definition file - or at least this file points to another resource. There are some resource files in the folder "mpldap/resources" (working if you have access to the internet).

  • The file "resources/!resource-template.ini.php" is a template wherein all entries are documented (it is a reference file).
  • Resource files beginning with "ads-" only work if you have access (rights) to an ADS server, if you change the connection info in the resource file. You also may have to change some of the attribute / filter settings (see below).
  • All other MRDF' should work if you have a connection to the internet!

If there is a file that you want to use: copy it to the folder "_customer/resources" and change the appropriate entry in the [resource] section in the MMCF (see above).

If you want to create a new one: copy the file "resources/!resource-template.ini.php" to the directory "_customer/resources", and rename it and add an appropriate entry in the [resource] section in the MMCF (see above).

Be sure to edit at least the following entries:

[...] to be done

When updating

  • Search in the file "resources/!resource-template.ini.php" for entries that are marked with a newer version number than you had installed (i.e. "@since 1.4.8"). Copy that entries into your old MpLDAP Resource Definition Files (MRDF) and change them. Pay attention copying the entries to the correct section!
  • Be sure that all of your MRDF's are referenced by the [resources] section in the MMCF (see above)

5. MpLDAP CSS File (MCF)

Do you want your own colors and / or styles of MpLDAP? You should be familiar with CSS:

  • Copy the file "css/mpldap.css" to the directory "_customer/css/"
    (you may have to create the directory first)
  • Rrename the file as you like
  • Open the appropriate MRDF's: edit the [options] => css_filename so it points to the new file.
  • Edit the CSS file.

Repeat this as often as you like. Remember: many MRDF's can share the same MCF.

When updating

  • Search in the file "css/mpldap.css" for entries that are marked with a newer version number than you had installed (i.e. "@since 1.4.8").
  • Open your old MCF in the directory "_customer/css"
  • Copy the new entry / entries into your old MpLDAP CSS Files (MCF)
  • Edit those entries.

6. MpLDAP Extensions

In version 1.4.3 the concept of extending MpLDAP functions by you (the "customer") was introduced. When a MpLDAP function is extension enabled you can edit its corresponding extension function in a file (following a defined filename syntax). This extension function is called at the end of the original function. The sourcecode of the extension file will remain untouched by a newer version. This way you can have your own modifications without modificating original source code.

You should be familiar with programming PHP!

The directory "templates/extensions" contains files of all available function extensions. Each file has only one function within it: the function you can extend the original function with.

This is the way you extend a function:

  1. List all files in the directory "templates/extensions"
  2. The files for extending functions follow this syntax:
    • "function_": prefix for extending functions
    • functionname: the name of the function to be extended
    • ".inc": suffix
  3. Locate the file of the function you want to extend.
  4. Copy the appropriate file into the directory "_customer/extensions".
  5. Example: extending the enabled function "thisDummyFunction()" means that you copy the file "function_thisDummyFunction.inc" from the directory "templates/extensions" to the directory "_customer/extensions".
  6. Edit the copied file. There may be some example in that code you may delete or edit as you like to.
  7. TEST YOUR MODIFICATION!
  8. Voila - that's all!

When updating

Normally there should no actions be done when updating - that's why we have these extensions :-)

When anything changed concerning existing extensions you will find a highlighted note in the change log.