From e8381a166193ac914c65841d1749cdda58551829 Mon Sep 17 00:00:00 2001 From: Roland Gruber Date: Mon, 1 Nov 2004 13:56:54 +0000 Subject: [PATCH] module HowTo --- lam/docs/devel/mod_accountPages.htm | 314 ++++++++++++++++++++++++++++ lam/docs/devel/mod_basics.htm | 109 ++++++++++ lam/docs/devel/mod_general.htm | 198 ++++++++++++++++++ lam/docs/devel/mod_help.htm | 88 ++++++++ lam/docs/devel/mod_index.htm | 55 +++++ lam/docs/devel/mod_upload.htm | 171 +++++++++++++++ 6 files changed, 935 insertions(+) create mode 100644 lam/docs/devel/mod_accountPages.htm create mode 100644 lam/docs/devel/mod_basics.htm create mode 100644 lam/docs/devel/mod_general.htm create mode 100644 lam/docs/devel/mod_help.htm create mode 100644 lam/docs/devel/mod_index.htm create mode 100644 lam/docs/devel/mod_upload.htm diff --git a/lam/docs/devel/mod_accountPages.htm b/lam/docs/devel/mod_accountPages.htm new file mode 100644 index 00000000..93592dd0 --- /dev/null +++ b/lam/docs/devel/mod_accountPages.htm @@ -0,0 +1,314 @@ + + + + Module HowTo - Account pages + + + +
+

Module HowTo - Account pages
+

+
+
+

+

1. Defining pages
+

+You can define multiple subpages for your account page. Usually one +page is enough but you may display certain attribute settings on an +extra page (e.g. Unix group memberships are on a second page).
+
+The page names are set by pages() which +returns an array of names.
+
+Example:
+
+The +ieee802Device +module needs only one page which is called 'attributes'.
+
+ + + + + + +
    /**
+    * This function returns a list of all account pages +in this module.
+    */
+    function pages() {
+        return array('attributes');
+    }
+
+
+
+

2. Page display

+Now that you have defined your subpages you will need one function for +each page to display it. The function must return meta HTML code as defined in the modules specification.
+This function is called display_html_<page +name>() where <page +name> is the name of your subpage.
+
+Example:
+
+The +ieee802Device +module has only one subpage called 'attributes'.
+
+The first half of the code displays the existing MAC addresses and the +second an input field for new values.
+The variable $this->attributes +contains all LDAP attributes of an account.
+
+ + + + + + +
    /**
+    * This function will create the meta HTML code to +show a page with all attributes.
+    *
+    * @param array $post HTTP-POST values
+    */
+    function display_html_attributes($post) {
+        $return = array();
+        // list current MACs
+        for ($i = 0; $i < +sizeof($this->attributes['macAddress']); $i++) {
+            $return[] = +array(
+            +    0 => array('kind' => 'text', 'text' => +_('MAC address')),
+            +    1 => array('kind' => 'input', 'name' => +'macAddress' . $i, 'type' => 'text', 'size' => '17', 'maxlength' +=> '17', 'value' => $this->attributes['macAddress'][$i]),
+            +    2 => array('kind' => 'input', 'type' => +'submit', 'name' => 'delMAC' . $i, 'value' => _("Remove")),
+            +    3 => array('kind' => 'help', 'value' => +'mac'));
+        }
+        // input box for new MAC
+        $return[] = array(
+            0 => +array('kind' => 'text', 'text' => _('New MAC address')),
+            1 => +array('kind' => 'input', 'name' => 'macAddress', 'type' => +'text', 'size' => '17', 'maxlength' => '17', 'value' => ''),
+            2 => +array('kind' => 'input', 'type' => 'submit', 'name' => +'addMAC', 'value' => _("Add")),
+            3 => +array('kind' => 'help', 'value' => 'mac'),
+            4 => +array('kind' => 'input', 'type' => 'hidden', 'value' => +sizeof($this->attributes['macAddress']), 'name' => 'mac_number'));
+        return $return;
+    }
+
+
+
+

3. Processing input data
+

+Every time the user clicks on a submit button while your page is +displayed LAM will call a function in your module.
+This function is called process_<page +name>() where <page +name> is the name of your subpage.
+
+Example:
+
+The +ieee802Device +module has only one subpage called 'attributes' +and therefore only process_attributes().
+
+The function checks the input fields and fills the LDAP attributes. If +all is ok it will enable the user to move to another module page.
+
+ + + + + + +
    /**
+    * Write variables into object and do some regex +checks
+    *
+    * @param array $post HTTP-POST values
+    */
+    function proccess_attributes($post) {
+        $this->triggered_messages = +array();
+        +$this->attributes['macAddress'] = array();
+        // check old MACs
+        if (isset($post['mac_number'])) {
+            for ($i = 0; +$i < $post['mac_number']; $i++) {
+            +    if (isset($post['delMAC' . $i])) continue;
+            +    if (isset($post['macAddress' . $i]) && +($post['macAddress' . $i] != "")) {
+            +        // check if address has correct +format
+            +        if (!get_preg($post['macAddress' +. $i], 'macAddress')) {
+            +            $message = +$this->messages['mac'][0];
+            +            $message[] = +$post['macAddress' . $i];
+            +            +$this->triggered_messages[] = array($message);
+            +        }
+            +        +$this->attributes['macAddress'][] = $post['macAddress' . $i];
+            +    }
+            }
+        }
+        // check new MAC
+        if (isset($post['macAddress']) +&& ($post['macAddress'] != "")) {
+            // check if +address has correct format
+            if +(get_preg($post['macAddress'], 'macAddress')) {
+            +    $this->attributes['macAddress'][] = +$post['macAddress'];
+            }
+            else {
+            +        $message = +$this->messages['mac'][0];
+            +        $message[] = $post['macAddress'];
+            +        $this->triggered_messages[] = +array($message);
+            }
+        }
+        +$this->attributes['macAddress'] = +array_unique($this->attributes['macAddress']);
+        if +(sizeof($this->triggered_messages) > 0) {
+            +$this->inputCorrect = false;
+            return +$this->triggered_messages;
+        }
+        else {
+            +$this->inputCorrect = true;
+            return 0;
+        }
+    }
+
+
+
+

4. Defining that your module is ready for LDAP add/modify

+Before a new account can be created or modified all modules are asked +if they are ready.
+There are two functions which control the module status. The module_ready() function has to +return true if the user may +move to another module page. If it is false +the user will be redirected to your module page. The second function is +module_complete(). The user +cannot do the LDAP operation if one or modules return false.
+
+Example:
+
+The +ieee802Device +module uses a global variable to store the status: $this->inputCorrect. It is set +in process_attributes(). The +variable can be preset to true +because the MAC address is optional.
+
+ + + + + + +
    /** used for +account pages, true if input data is correct */
+    var $inputCorrect = true;
+
+    /**
+    * This function returns true if all needed settings +are done.
+    */
+    function module_complete() {
+        return $this->inputCorrect;
+    }
+   
+    /**
+    * Returns true if all settings on module page are +correct.
+    */
+    function module_ready() {
+        return $this->inputCorrect;
+    }
+
+
+
+

5. Saving the LDAP attributes
+

+
+
+Example:
+
+
+
+ + + + + + +
   
+
+
+
+ +

+
+
+ + diff --git a/lam/docs/devel/mod_basics.htm b/lam/docs/devel/mod_basics.htm new file mode 100644 index 00000000..31103809 --- /dev/null +++ b/lam/docs/devel/mod_basics.htm @@ -0,0 +1,109 @@ + + + + Module HowTo - Basic concepts + + + +
+

Module HowTo - Basic concepts
+

+
+
+

+

1. Licensing

+LAM is licensed under the GNU +General Public License. This means your plugins need a compatible +license.
+LAM is distributed with a copy of the GPL license.
+
+

2. Naming and position in directory structure

+
+Module names are usually named after the object class they manage. +However, you can use any name you want, it should be short and +containing only a-z and 0-9. The module name is only shown in the +configuration dialog, on all other pages LAM will show a provided alias name.
+All account modules are stored in lib/modules. +The filename must end with .inc +and the file must have the same name as its inside class.
+
+Example: +Our example module will provide the class +ieee802Device, +therefore the file will be called lib/modules/ieee802Device.inc.
+
+
+

3. Defining the class

+All module classes have baeModule +as parent class. This provides common functionality and dummy functions +for all required class functions.
+
+Example:
+
+ + + + + + +
/**
+* Provides MAC addresses for hosts.
+*
+* @package modules
+*/
+class ieee802Device + extends baseModule {
+
+}
+
+
+

4. Meta data

+The module interface inludes a lot of required and optional functions. +Many of these functions do not need to be implemented directly in the +module, you can define meta data +for them and the baseModule +will do the rest.
+Providing meta data is +optional, you can implement the required functions in your class, too.
+
+The baseModule reads the meta data by calling get_metaData() in your class.
+
+Example:
+
+ + + + + + +
    /**
+    * Returns meta data that is interpreted by parent +class
+    *
+    * @return array array with meta data
+    */
+    function get_metaData() {
+        $return = array();
+        // manages host accounts
+        $return["account_types"] = +array("host");
+    }
+
+
+You will see this functions several times in the next parts of this +HowTo.
+
+

+
+
+ + diff --git a/lam/docs/devel/mod_general.htm b/lam/docs/devel/mod_general.htm new file mode 100644 index 00000000..56855b03 --- /dev/null +++ b/lam/docs/devel/mod_general.htm @@ -0,0 +1,198 @@ + + + + Module HowTo - General module options + + + +
+

Module HowTo - General module options
+

+
+
+

+

1. Account types
+

+LAM currently provides three account types: users, groups, hosts
+A module can manage one or more account types.
+
+The types are specified with can_manage() +or meta['account_types'].
+
+Example:
+
+Our ieee802Device +module will be used only for host accounts.
+
+ + + + + + +
    /**
+    * Returns meta data that is interpreted by parent +class
+    *
+    * @return array array with meta data
+    */
+    function +get_metaData() {
+        $return = array();
+        // manages host accounts
+     +    $return["account_types"] = array("host");
+        return $return;
+    }
+
+
+
+

2. Alias name

+The module name is very limited, therefore every module has an alias name. This alias name has no limitations and +can be translated. It may contain special characters but make sure that +it does not contain HTML special characters like "<".
+The alias name can be the +same for all managed account types +or differ for each type.
+
+The alias name is specified +with get_alias() +or meta['alias'].
+
+Example:
+
+Our ieee802Device +module will get the alias MAC address.
+
+ + + + + + +
    /**
+    * Returns meta data that is interpreted by parent +class
+    *
+    * @return array array with meta data
+    */
+    function +get_metaData() {
+        $return = array();
+        // manages host accounts
+     +    $return["account_types"] = array("host");
+        // alias name
+     +    $return["alias"] = _("MAC address");
+        return $return;
+    }
+
+
+
+

3. Dependencies

+Modules can depend on eachother. This is useful if you need to access +attributes from other modules or the managed object classes of your +module are not structural.
+
+The dependencies are specified with get_dependencies() +or meta['dependencies'].
+
+Example:
+
+Our ieee802Device +module depends on the account module (because it is the only structural +module at this time).
+
+ + + + + + +
    /**
+    * Returns meta data that is interpreted by parent +class
+    *
+    * @return array array with meta data
+    */
+    function +get_metaData() {
+        $return = array();
+        // manages host accounts
+     +    $return["account_types"] = array("host");
+        // alias name
+        $return["alias"] = _("MAC +address");
+        // module dependencies
+     +    $return['dependencies'] = array('depends' => +array('account'), 'conflicts' => array());
+        return $return;
+    }
+
+
+
+

4. Messages

+There are many situations where you will display messages to the user. +The modules should define such messages at a common place to make it +easier to modify them without searching the complete file.
+The baseModule offers the $messages variable for this. It +should be filled by a function called load_Messages().
+The baseModule will +automatically check if you have implemented this function and call it +at construction time.
+
+Example:
+
+Now let our ieee802Device +module define a message.
+
+ + + + + + +
    /**
+    * This function fills the error message array with +messages
+    */
+    function load_Messages() {
+        $this->messages['mac'][0] = +array('ERROR', 'MAC address is invalid!');  // third array value +is set dynamically
+    }
+
+
+
+


+

+

+
+
+ +

+
+
+ + diff --git a/lam/docs/devel/mod_help.htm b/lam/docs/devel/mod_help.htm new file mode 100644 index 00000000..42efc69f --- /dev/null +++ b/lam/docs/devel/mod_help.htm @@ -0,0 +1,88 @@ + + + + Module HowTo - Help entries + + + +
+

Module HowTo - Help entries
+

+
+
+

+

1. Defining help entries
+

+Your module should provide help for all input fields and other +important things.
+The LAM help system defines an extra ID range for each module. So you +are free in defining your own IDs.
+
+The help entries are specified with get_help() +or meta['help'].
+
+Example:
+
+The ieee802Device +module needs help entries for the MAC address.
+
+ + + + + + +
    /**
+    * Returns meta data that is interpreted by parent +class
+    *
+    * @return array array with meta data
+    */
+    function +get_metaData() {
+        $return = array();
+    +     // help Entries
+     +    $return['help'] = array(
+     +        'mac' => array(
+     +            "Headline" +=> _("MAC address"),
+     +            "Text" => +_("This is the MAC address of the network card of the device (e.g. +00:01:02:DE:EF:18).")
+     +        ),
+     +        'macList' => array(
+     +            "Headline" +=> _("MAC address list"),
+     +            "Text" => +_("This is a comma separated list of MAC addresses.")
+     +        ));
+        return $return;
+    }
+
+
+
+ +

+
+
+ + diff --git a/lam/docs/devel/mod_index.htm b/lam/docs/devel/mod_index.htm new file mode 100644 index 00000000..c3565a01 --- /dev/null +++ b/lam/docs/devel/mod_index.htm @@ -0,0 +1,55 @@ + + + + LAM module HowTo + + + +
+

Module HowTo

+
+
+
+

Basic functions

+
+
+
LAM can be easily extended to support +additional LDAP object classes and attributes.
+This document provides a step-by-step description to build an account +module. The ieee802Device +module which provides MAC addresses for hosts is used as example.
+
+

1. Basic concepts
+

+
+

2. General module options

+
+

3. Account pages

+
+

4. Help entries
+

+
+

5. PDF output
+

+
+

6. File upload

+
+
+
+

+
+

Advanced functions

+This part covers additional functionality of the modules which are only +needed by a minority of modules. The examples are taken from different +existing modules.
+
+

1. Account profiles

+
+

2. Configuration options

+
+
+
+
+
+ + diff --git a/lam/docs/devel/mod_upload.htm b/lam/docs/devel/mod_upload.htm new file mode 100644 index 00000000..deb85f36 --- /dev/null +++ b/lam/docs/devel/mod_upload.htm @@ -0,0 +1,171 @@ + + + + Module HowTo - File upload + + + +
+

Module HowTo - File upload
+

+
+
+

+

1. Defining upload columns
+

+If you want to support account creation via file upload you have to +define columns in the CSV file.
+Each column has an non-translated identifier, a description, help entry +and several other values.
+
+The upload columns are specified with get_uploadColumns() +or meta['upload_columns'].
+
+Example:
+
+The ieee802Device +module has only one attribute and therefore one column: the MAC address.
+
+ + + + + + +
    /**
+    * Returns meta data that is interpreted by parent +class
+    *
+    * @return array array with meta data
+    */
+    function +get_metaData() {
+        $return = array();
+        // manages host accounts
+    +    $return["account_types"] = array("host");
+        // upload fields
+     +    $return['upload_columns'] = array(
+     +        array(
+     +            'name' => +'ieee802Device_mac',
+     +            'description' +=> _('MAC address'),
+     +            'help' => +'mac',
+     +            'example' +=> '00:01:02:DE:EF:18'
+     +        )
+      +   );
+        return $return;
+    }
+
+
+
+

2. Building the accounts
+

+When the user has uploaded the CSV file the modules have to transform +the input data to LDAP accounts.
+
+This is done with build_uploadAccounts(). +The function gets the input data and a list of LDAP accounts as +parameter.
+
+Example:
+
+The ieee802Device +module has only one LDAP attribute - 'macAddress' +- and the 'ieee802Device' +objectClass which is added to all accounts.
+
+ + + + + + +
    /**
+    * In this function the LDAP account is built up.
+    *
+    * @param array $rawAccounts list of hash arrays +(name => value) from user input
+    * @param array $partialAccounts list of hash arrays +(name => value) which are later added to LDAP
+    * @param array $ids list of IDs for column position +(e.g. "posixAccount_uid" => 5)
+    * @return array list of error messages if any
+    */
+    function build_uploadAccounts($rawAccounts, +$ids, &$partialAccounts) {
+        $messages = array();
+        for ($i = 0; $i < +sizeof($rawAccounts); $i++) {
+            // add object +class
+            if +(!in_array("ieee802Device", $partialAccounts[$i]['objectClass'])) +$partialAccounts[$i]['objectClass'][] = "ieee802Device";
+            // add MACs
+            if +($rawAccounts[$i][$ids['ieee802Device_mac']] != "") {
+            +    $macs = explode(',', +$rawAccounts[$i][$ids['ieee802Device_mac']]);
+            +    // check format
+            +    for ($m = 0; $m < sizeof($macs); $m++) {
+            +        if (get_preg($macs[$m], +'macAddress')) {
+            +            +$partialAccounts[$i]['macAddress'][] = $macs[$m];
+            +        }
+            +        else {
+            +            $errMsg = +$this->messages['mac'][1];
+            +            +array_push($errMsg, array($i));
+            +            $messages[] = +$errMsg;
+            +        }
+            +    }
+            }
+        }
+        return $messages;
+    }
+
+
+
+
+
+ +

+
+
+ +