NAME

SYNOPSIS

  $config = AddressBook::Config->new(config_file=>$filename);

AddressBook::Config looks for a configuration file in /etc/AddressBook.conf if no config_file parameter is present.

DESCRIPTION

  <?xml version="1.0"?>
  <!DOCTYPE AddressBook_config [
    <!ELEMENT fields (field)>
    <!ELEMENT field  (db)>
    <!ELEMENT db (EMPTY)>
    <!ELEMENT databases (LDAP,LDIF,DBI,PDB,Text,HTML)>
    <!ELEMENT LDAP (EMPTY)>
    <!ELEMENT LDIF (EMPTY)>
    <!ELEMENT DBI (EMPTY)>
    <!ELEMENT PDB (EMPTY)>
    <!ELEMENT Text (EMPTY)>
    <!ELEMENT HTML (EMPTY)>

    <!ATTLIST field     name            CDATA   #REQUIRED
                        order           CDATA   #IMPLIED
                        type            (text|textblock|phone|email|url|lurl|boolean) #IMPLIED
                        values          CDATA   #IMPLIED
                        non_multiple    CDATA   #IMPLIED
                        read_only       CDATA   #IMPLIED
                        calculate       CDATA   #IMPLIED
                        calc_order      CDATA   #IMPLIED>

    <!ATTLIST db        name            CDATA   #REQUIRED
                        type            CDATA   #REQUIRED
                        order           CDATA   #IMPLIED
                        calculate       CDATA   #IMPLIED
                        calc_order      CDATA   #IMPLIED>

    <!ATTLIST LDAP      key_fields      CDATA   #IMPLIED
                        hostname        CDATA   #IMPLIED
                        objectclass     CDATA   #IMPLIED
                        base            CDATA   #IMPLIED
                        dn_calculate    CDATA   #IMPLIED
                        username        CDATA   #IMPLIED
                        password        CDATA   #IMPLIED>

    <!ATTLIST LDIF      key_fields      CDATA   #IMPLIED
                        filename        CDATA   #IMPLIED
                        objectclass     CDATA   #IMPLIED
                        base            CDATA   #IMPLIED
                        dn_calculate    CDATA   #IMPLIED>

    <!ATTLIST DBI       key_fields      CDATA   #IMPLIED
                        table           CDATA   #IMPLIED
                        dsn             CDATA   #IMPLIED>

    <!ATTLIST PDB       write_format    CDATA   #IMPLIED
                        intra_attr_sep  CDATA   #IMPLIED
                        form_format     CDATA   #IMPLIED>

    <!ATTLIST HTML      key_fields      CDATA   #IMPLIED
                        filename        CDATA   #IMPLIED
                        phone_display   CDATA   #IMPLIED>
  ]>

For example,

  <AddressBook_config>
    <fields>
      <field name="firstname" type="text" order="1">
        <db type="LDAP" name="givenname" />
        <db type="HTML" name="First Name" order="2" />
      </field>
      <field name="lastname" type="text" order="2">
        <db type="LDAP" name="sn" />
        <db type="HTML" name="Last Name" order="1" />
      </field>
      <field name="fullname" type="text" order="3" 
             calculate="$firstname . ' ' . $lastname">
        <db type="LDAP" name="cn" />
        <db type="HTML" name="Full Name" />
      </field>
    </fields>
    <databases>
      <LDAP objectclass="inetOrgPerson"
            base="o=abook"
            dn_calculate="'cn='.$cn"
            username="cn=Manager,o=abook"
            password="secret"
            key_fields="cn"
      />
    </databases>
  </AddressBook_config>

This defines three attributes with cannonical names "firstname", "lastname", and "fullname". These are accessed in the LDAP backend context as "givenname", "sn" and "cn", and in the HTML backend context as "First Name", "Last Name" and "Full Name" respectively.

The default attribute ordering is "firstname", "lastname", "fullname", however the HTML backend overrides this and in that context attributes are ordered: "lastname", "firstname", "fullname". All other meta-attributes may be similarily overriden by specific backends

"fullname" is a calculated attribute. Calculation strings may reference the names of other attributes by "$<attr_name>".

Backend databases may also be named and then tied to a source type by using the 'driver' attribute. This technique is useful for defining multiple backends of the same type. For example,

  <AddressBook_config>
    <fields>
      <field name="firstname" >
        <db type="ldap_server_1" name="givenname" />
        <db type="ldap_server_2" name="givenname" />
      </field>
      <field name="lastname" >
        <db type="ldap_server_1" name="sn" />
        <db type="ldap_server_2" name="sn" />
      </field>
    </fields>
    <databases>
      <ldap_server_1 driver="LDAP"
                     hostname="server_1"
                     objectclass="inetOrgPerson"
                     base="o=abook"
                     dn_calculate="'cn='.$cn"
                     username="cn=Manager,o=abook"
                     password="secret"
                     key_fields="cn"
      />
      <ldap_server_2 driver="LDAP"
                     hostname="server_2"
                     objectclass="inetOrgPerson"
                     base="o=abook"
                     dn_calculate="'cn='.$cn"
                     username="cn=Manager,o=abook"
                     password="secret"
                     key_fields="cn"
      />
    </databases>
  </AddressBook_config>

See the various backend man pages for information on the <database> configuration attributes. See also the sample configuration files in the 'examples' directory.

  %meta = %{$config->getMeta(attr=>$attr)}
  %meta = %{$config->getMeta(attr=>$attr,db=>$db)}

AUTHOR

SEE ALSO