Commit fcbc8ee8 authored by bmortier's avatar bmortier

Merge branch 'master' into 'master'

Added documentation pages from Dokuwiki dev docs

See merge request !2
parents 451a4d72 731fadd0
......@@ -51,8 +51,8 @@ master_doc = 'index'
# General information about the project.
project = u'FusionDirectory development'
copyright = u'2017, Benoit Mortier Come Chilliet'
author = u'Benoit Mortier Come Chilliet'
copyright = u'2017, Benoit Mortier Côme Chilliet'
author = u'Benoit Mortier Côme Chilliet'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
......@@ -262,7 +262,7 @@ latex_elements = {
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'FusionDirectorydevelopment.tex', u'FusionDirectory development Documentation',
u'Benoit Mortier Come Chilliet', 'manual'),
u'Benoit Mortier Côme Chilliet', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
......
......@@ -2,7 +2,15 @@
.. |folder| image:: /_static/images/folder.png
:alt:
.. |file| image:: /_static/images/file.png
:alt:
.. |phpfile| image:: /_static/images/php_file.png
:alt:
.. role:: php(code)
:language: php
.. role:: shell(code)
:language: bash
.. _attributes:
Attributes Types
================
Here is a detailed description about each available attribute type for simple plugin.
StringAttribute
---------------
.. image:: /_static/images/attributes/string.png
The most simple class, allows to handle an LDAP attribute which is a string.
Specific constructor parameter :
as last parameter you can pass a pattern that the string must match in order to be valid
There are some attributes that are just like this one but with specific check for validity : MailAttribute, HostNameAttribute, IPv4Attribute, IPv6Attribute, MacAddressAttribute, IPAttribute (accepts both v4 and v6)
PasswordAttribute
-----------------
.. image:: /_static/images/attributes/password.png
Same thing as StringAttribute but input form is a hidden password input (html password input type). No specific constructor parameters
IntAttribute
------------
.. image:: /_static/images/attributes/int.png
Allow to handle an int.
Specific constructor parameters : min and max. Use "FALSE" to disable either one of them.
"intval" will be used on user input in order to convert it.
html5 "number" input type is displayed.
FloatAttribute
--------------
.. image:: /_static/images/attributes/float.png
The same that IntAttribute but for floats.
"floatval" will be used.
SelectAttribute
---------------
.. image:: /_static/images/attributes/select.png
Specific constructor attributes : an array containing the available choices.
An html select is displayed.
BooleanAttribute
----------------
.. image:: /_static/images/attributes/boolean-false.png
or
.. image:: /_static/images/attributes/boolean-true.png
Allow to handle booleans. No specific constructor parameters.
A checkbox is displayed.
ObjectClassBooleanAttribute
---------------------------
Special kind of boolean that adds or removes object classes from the object.
FileAttribute
-------------
.. image:: /_static/images/attributes/file.png
Allow the user to upload a file, store the file content in the LDAP.
If you need to do something else with the uploaded file, you'll have to inherit this class and the readFile function.
DateAttribute
-------------
.. image:: /_static/images/attributes/date1.png
Show a text input with a calendar in order for the user to choose a date.
You need to pass the wanted date format in LDAP in its constructor
BaseSelectorAttribute
---------------------
.. image:: /_static/images/attributes/base.png
Allow the user to select the base of the object.
Usually in the main tab of most objects.
ArrayAttribute and SetAttribute
-------------------------------
.. image:: /_static/images/attributes/set.png
Allow to handle a multi-valuated attribute.
The constructor takes only two parameters:
* An attribute, which is one of the above.
* An array of default values.
A multiple select will be used for displaying values, with remove and add buttons.
SetAttribute is the same, but does not allow several identical values.
CompositeAttribute
------------------
Allow to handle several UI attributes which are stored as only one LDAP field.
For instance let's say you store an FTP connection URL in an LDAP field as "ftp://user:password@host:port" but you want to display 4 inputs for the 4 parts.
That would look like :
.. code-block:: php
<?php
new CompositeAttribute (
_('Informations for ftp login'),
'ftpLoginInfo',
array(
new StringAttribute (_('Login'), _('Login for FTP'), 'ftpLogin'),
new StringAttribute (_('Password'), _('Password for FTP'), 'ftpPassword'),
new StringAttribute (_('Host'), _('Host for FTP'), 'ftpHost'),
new IntAttribute (_('Port'), _('Port for FTP'), 'ftpPort', FALSE, 0, FALSE, 21),
),
'ftp://%[^@:]:%[^@:]@%[^@:]:%d', // sscanf format
'ftp://%s:%s@%s:%d' // sprintf format
)
(If you need something else than scanf and printf for composition, you have to inherit CompositeAttribute in a new attribute class and write your own readValues and writeValues functions)
OrderedArrayAttribute
---------------------
This is an OrdreredArrayAttribute of CompositeAttribute (itself composed of a String and a Select attribute)
.. image:: /_static/images/attributes/orderedarray.png
Like a SetAttribute, but shows values as a table with button for removing entries and changing order.
It stores the order as "indice:value" in the LDAP.
You can pass FALSE as second parameter to disable the ordering if you just want a SetAttribute that looks different.
UsersAttribute
--------------
Allow the user to select a lists of users.
Their dn are stored in the LDAP.
A dialog is available to add users:
Before:
.. image:: /_static/images/attributes/users1.png
Selection:
.. image:: /_static/images/attributes/users2.png
After:
.. image:: /_static/images/attributes/users3.png
.. include:: /globals.rst
Plugin folder organization
==========================
The directories in a FusionDirectory plugin look like this:
* |folder| `addons`: used if the plugin put things in the addons menu category
* |folder| `admin`: main dir for all plugins going into the admin menu category
* |folder| `config`: configuration dir, used if the plugin need to store option in ldap
* |folder| `contrib`: used to put all the contributed files like schema, docs, manpages etc..
* |folder| `openldap`: Schemas for the openldap server
* |folder| `docs`: Documentation how to use the plugin
* |folder| `html`: used to put all the images or other public files
* |folder| `plugins`
* |folder| `plugin_name`
* |folder| `images`: images which are not icons
* |folder| `themes`
* |folder| `breezy`
* |folder| `icons`: icons to add to default breezy theme
* |folder| `48`: sorted by size, for instance 48x48
* |folder| `apps`: then by category, use apps for application icons
* |file| `myapp.png`: format should be png. This example file would be used as *geticon.php?context=applications&icon=myapp*
* |folder| `ihtml`: used to put all the smarty template files
* |folder| `themes`
* |folder| `breezy`: smarty templates
* |folder| `locale`: used for localization of the plugin
* |folder| `en`: language iso code
* |file| `fusiondirectory.po`: message file
* |folder| `personal`: used when plugin is to be used to manage user properties
* |folder| `includes`: used for files available for inclusion for other plugins
addons, admin, config, personal
-------------------------------
These directories should contain a subdirectory named as the plugin, or as an other plugin which we extend.
For instance, argonaut plugin contains *admin/systems/argonaut/class_argonautClient.inc*
Installation of a plugin
------------------------
For **addons**, **admin**, **config**, and **personal** folders, the content should go into *<fd_dir>/plugins/<dir>*/
For **html**, **ihtml**, **include**, the content should go into *<fd_dir>/<dir>*/
For **contrib/openldap**, the content should go into *<ldap_schemas_dir>/fusiondirectory*/
For **contrib/etc**, the content should go into */etc/fusiondirectory/<plugin_name>*.
For **contrib/doc**, the content may go into *<doc_dir>/fusiondirectory-plugin-<plugin_name>*.
Special cases:
* in **html/themes/<theme_name>**, svg folder may be ignored
* content of **locale** goes into *<fd_dir>/locale/plugins/<plugin_name>/locale*/
......@@ -16,42 +16,42 @@ There are some attributes that you can set in your class or in your constructor
custom template
^^^^^^^^^^^^^^^
By default simplePlugin does a template for you, but if you want to add some elements to the template, or just render the sections in a different order, or that kind of things, here's what to do:
Change **templatePath** value to your custom template path (usually in the constructor, using get_template_path).\\
Change **templatePath** value to your custom template path (usually in the constructor, using get_template_path).
In your template, you'll be able to use the $sections array that contains each section render.\\
For instance:\\
In your template, you'll be able to use the **$sections** array that contains each section render.
For instance:
.. code-block::
.. code-block:: smarty
<h1>Hello world!</h1>
<div class="plugin_sections">
{$sections.section1}
{$sections.Mysection}
</div>
<input name="{$hiddenPostedInput}" value="1" type="hidden"/>
<!-- Place cursor -->
<script language="JavaScript" type="text/javascript">
<!-- // First input field on page
focus_field('{$focusedField}');
-->
</script>
You need to add the hidden input at the end in order for the POST analysis to work.\\
You need to add the **hidden** input at the end in order for the POST analysis to work.
The script is needed if you want the auto-focusing of first field to work.
simplePlugin attributes values and methods
simplePlugin attributes values and methods
------------------------------------------
In all of these methods, you can access the attributes by using **$this->attributesAccess** as follows:
$this->attributesAccess['attributeldapname']
Don't forget to look at the documentation of the Attribute classes to know who to use them.
For instance they offer a **setDisabled** method if you need to disable some of them, **hasChanged**
will allow you to know if an attribute has been modified, etc…\\
You can also easily access their value using **$this->attributeldapname**. Be aware that
this is not a real class attribute, accessing it will call the **getValue** and **setValue** methods of the attribute.
Don't forget to look at the documentation of the Attribute classes to know who to use them.
For instance they offer a **setDisabled** method if you need to disable some of them, **hasChanged**
will allow you to know if an attribute has been modified, etc…
You can also easily access their value using **$this->attributeldapname**. Be aware that
this is not a real class attribute, accessing it will call the **getValue** and **setValue** methods of the attribute.
That means you can't create reference to it or call method that needs references like the array ones (array_push, …).
The [] operator for arrays do not work either.
......@@ -75,7 +75,7 @@ You can change it, doing something that look like that:
return $this->header;
}
}
You can fetch any template but usually **$this->templatePath** is used, just remember to add **$this->header** at the beginning if you activated the display header feature.
Please avoid doing heavy things in the execute function as it is just the render function, it's not supposed to compute anything.
......@@ -96,7 +96,7 @@ You can inherit it as follows:
// your code goes here
}
}
ldap_save
^^^^^^^^^
......@@ -154,12 +154,12 @@ An other method, often simpler, is to modify your attributes after being constru
function __construct(&$config, $dn = NULL, $object = NULL)
{
parent::__construct($config, $dn, $object);
$array = array('node1','node2'); // some dummy array
// After simplePlugin constructor, you must access attributes by their ldap name
$this->attributesAccess['myattributeLdapName']->setChoices($array);
}
is_this_account
^^^^^^^^^^^^^^^
......@@ -194,7 +194,7 @@ Please don't touch the fieldset, legend and table, just replace the foreach by w
You need to use the attributes array, which contain for each attribute, indexed by its ldap name, its label and its input html code.
For instance, for the above section, doing the following would have the same result than the default template:
.. code-block::
.. code-block:: smarty
<fieldset id="{$sectionId}" class="plugin_section{$sectionClasses}">
<legend>{$section}</legend>
......@@ -211,7 +211,7 @@ You need to use 'eval' for label and HTML input as it contains some smarty code
Managed attributes
------------------
In some case you want some attributes to be enabled/disabled depending on a checkbox or select state.\\
In some case you want some attributes to be enabled/disabled depending on a checkbox or select state.
For this, you can use the **setManagedAttributes** method as follow:
.. code-block:: php
......@@ -226,7 +226,7 @@ For this, you can use the **setManagedAttributes** method as follow:
)
)
);
'disable' means that the attributes will be disabled but still saved into the LDAP.
you can use 'erase' instead if you want those to be remove from the LDAP.
FALSE means that when the value is FALSE, they'll be disabled.
......@@ -249,5 +249,5 @@ You can also use this method with selectattributes:
)
)
);
Note the **multiplevalues** special key in order to specify several values that disable the same attributes.
Writing a plugin for FusionDirectory
==========
====================================
You can write plugins for FusionDirectory using our simplePlugin class.
.. toctree::
:maxdepth: 2
folders
start
further
plinfo
attributes
.. _pl-info:
plInfo
======
plInfo is a static function that must be present on all plugin classes that want to appear in FusionDirectory in one of these ways:
* In FusionDirectory main menu: use plSection
* In an object tabs: use plObjectType
* In ACL settings: use plProvidedAcls
This static method returns an array containing keys from the following table. Some may be safely omitted. Do not fill a key if you intend to use the default value for it. Use translated strings (use the _() function) for all displayable strings.
.. csv-table:: plInfo keys
:header: key, value, used in, default
plShortName, "A short name for this class", "Used in main menu and ACL summaries or such", **mandatory**
plTitle, "A short title for this class", "Used in FD page header at top of the page if this plugin have its own page", plShortName value
plDescription, "A short description", "Used as tooltip in the menus and description in ACL management", **mandatory**
plIcon, "A big icon (48x48)", "Used for main menu and header at top of the page", no icon
plSmallIcon, "A small icon (16x16)", "Used in listings", "empty icon"
plSelfModify, "TRUE for user tabs, omitted for others", Define if it should appear in «my account» menu section for logged in users, FALSE
plPriority, "an integer (safe to omit most of the time)", Defines tab order and menu items order, "no prority (at the end, in no specific order)"
plDepends, "Array of tabs this tab depends on", Listed tabs will need to be activated before this one can be used , empty
plCategory, "Array of ACL categories", Should be omitted if you’ve listed objectTypes , categories of objectTypes and managed objects
plObjectType, "Array of objectTypes", See full documentation below , empty
plSection, "menu section key or array (see below)", See full documentation below , empty
plProvidedAcls, "Array of acls", See full documentation below , empty
plForeignKeys, "Array of foreign keys", See full documentation below , empty
plManages, "Array of managed objectTypes (only for management classes)", Used to create links to objects of these types, empty
plSection
---------
**plSection** can be used if your plugin should appear in the menu. Default menu sections are "*accounts*", "*systems*", "*conf*", "*reporting*" and "*personal*".
Usually the **plSection** is set on the management class if there is any.
No need to set any **plSection** on plugins with objectType *user* and selfModify TRUE,
they'll appear in the 'My account' section anyway.
You can also create a new menu section in this attribute using the following syntax:
.. code-block:: php
<?php
array('mysection' => array('name' => _('My section'), 'priority' => 100))
Replace *mysection* with a lowercase id for your section and *My section* with the name to display in the menu.
The existing sections are:
.. csv-table:: Menu sections
:header: key, name, priority
accounts, Users and groups, 0
systems, Systems, 10
conf, Configuration, 20
reporting, Reporting, 30
personal, My account, 40
So you can for instance use a priority between 0 and 10 create a section between *accounts* and *systems*.
plObjectType
------------
**plObjectType** is used to know which object type should have this plugin in its tabs.
If this tab is the main tab of a new objectType, **plObjectType** must contain the definition for this object type.
ObjectType definition is an array containing the following keys:
.. csv-table:: ObjectType properties
:header: key, value, default
name, Displayable name for this object type, **mandatory**
description, Displayable description for this object type, **mandatory**
filter, LDAP filter to find objects of this type, **mandatory**
mainAttr, LDAP attribute to use in dn, cn
nameAttr, LDAP attribute to use in object links, *mainAttr*
tabClass, PHP class to use for tab handling, simpleTabs
icon, Small icon (16x16), no icon
ou, RDN for the LDAP branch to store these objets in, empty string
aclCategory, The ACL category this objectType is in, *key*
aclCategory should be the name of an existing ACL category. Most of the time omit this and a category will automagically be created for you.
For instance, this is the plObjectType of the user class:
.. code-block:: php
<?php
'plObjectType' => array(
'user' => array(
'description' => _('Users'),
'name' => _('User'),
'filter' => 'objectClass=gosaAccount',
'mainAttr' => 'cn',
'icon' => 'geticon.php?context=types&amp;icon=user&amp;size=16',
'ou' => get_ou('userRDN'),
)
),
plForeignKeys
-------------
plForeignKeys is to be used if some of your fields are foreign keys to fields of other objects.
For instance the manager field in a department is a foreign key on the dn of a user.
The syntax for this is:
.. code-block:: php
<?php
'plForeignKeys' => array(
'myfield' => array(
array('class', 'hisfield', 'filter'),
)
)
But you can omit *filter* most of the time (defaults to '*myfield*=%oldvalue%') and *hisfield* if it is the *dn*, and if there is only one field you are referring to you can omit the array, so for our department example this gives us:
.. code-block:: php
<?php
'plForeignKeys' => array(
'manager' => 'user'
)
Which is pretty straight forward.
Declaring a foreignKey ensure you that:
* If the referred field is modified through FD your object will be updated as well
* If the referred object is deleted your field will be emptied if possible (or the specific value referring the object will be removed in case of multi-value attributes)
* Your objects will appear in the references tab of referenced objects
plCategory
----------
ACL categories will be filled automagically if you use either **plManages** or **plObjectType**. This is the recommanded way to go.
If you do need to specify ACL categories, you can create an acl category by specifying a descriptive array for it:
.. code-block:: php
<?php
'plCategory' => array(
'acl' => array(
'description' => _('ACL'),
'objectClass' => array('gosaAcl','gosaRole')
)
),
An ACL category only contains a description and a list of LDAP objectClasses (for some historical reason)
.. include:: /globals.rst
Getting started
===============
This page is a how-to to help you write a dummy plugin.
......@@ -19,9 +21,10 @@ Your plugin should have a *main.inc* file if you intend it to display on its own
Icons
-----
If your plugin packs some icons, they need to be placed in the default icon theme:
*{fd-directory}/html/themes/default/icons/{size}/{category}*
Most of the time your icons are those of an application and should therefore be placed in the //apps// folder, which is for the category *applications*.
*{fd-directory}/html/themes/default/icons/{size}/{category}*
Most of the time your icons are those of an application and should therefore be placed in the *apps* folder, which is for the category *applications*.
For instance if the small icon for apache goes in *{fd-directory}/html/themes/default/icons/16/apps/apache.png* and is used in the code as *geticon.php?context=applications&icon=apache&size=16*
Basic plugin writing
......@@ -37,10 +40,10 @@ This is the code for an empty plugin:
// We set displayHeader to FALSE, because we don't want a header allowing to activate/deactivate this plugin,
// we want it activated on all objects
var $displayHeader = FALSE;
// Here we indicate which LDAP classes our plugin is using.
var $objectclasses = array('demoPlugin');
// We need this function that returns some information about the plugin
static function plInfo ()
{
......@@ -50,12 +53,12 @@ This is the code for an empty plugin:
'plDescription' => _('Edit some useless personal information'),
'plSelfModify' => TRUE, // Does this plugin have an owner that might be able to edit its entry
'plObjectType' => array('user'),
// simplePlugin can generate the ACL list for us
'plProvidedAcls' => parent::generatePlProvidedAcls(self::getAttributesInfo())
);
}
// The main function : information about attributes
static function getAttributesInfo ()
{
......@@ -63,14 +66,15 @@ This is the code for an empty plugin:
);
}
}
With this code you'll have an empty plugin, just adding the "demoPlugin" objectClass.
The [[en:documentation_dev:plInfo|plInfo]] static function must provide informations about your plugin.
The :ref:`pl-info` static function must provide informations about your plugin.
Please fill **plShortName** and **plDescription** with something meaningful (and **plTitle** as well if your plugin have its own page).
See [[en:documentation_dev:plInfo|plInfo]] for more details about other fields
See :ref:`pl-info` for more details about other fields
Attributes
----------
You might have noticed the empty getAttributesInfo method. This is where the magic happens.
You should fill this function with an array of sections containing attributes.
Available attribute types are BooleanAttribute, IntAttribute, FloatAttribute, StringAttribute, SelectAttribute, PasswordAttribute…
......@@ -79,7 +83,7 @@ There are also three special kind of attributes, SetAttribute, ArrayAttribute an
SetAttribute and ArrayAttribute might both be used for multi-valuated attribute. Array will allow several identical values while Set won't.
A composite attribute is a unique LDAP attribute composed of several displayed attributes. You'll see one in the following example.
For more information about each type of attribute, see [[en:documentation_dev:simple_plugin_attributes|Simple Plugin Attributes]]
For more information about each type of attribute, see :ref:`attributes`
Example
-------
......@@ -156,21 +160,25 @@ Example
);
}
As you can see, attribute constructor take 5 arguments being label, description,
As you can see, attribute constructor take 5 arguments being label, description,
ldap name, whether this attribute is mandatory or not, default value.
Some attributes takes other arguments before and after the default value.
For each section you might also specify keys 'icon' with a section icon path, or 'class' with an array of css class this section should have. (Only useful class for now is 'fullwidth' which means your section will fill the whole page width)
Displaying the plugin in FusionDirectory
----------------------------------------
Put the plugin code into a directory FusionDirectory is reading (see above).
Run <code>"fusiondirectory-setup --update-cache"</code> as root.
Log out, log in.
A tab should now show in user edition mode, with the attributes we specified:
{{:en:documentation_dev:demoplugin.png?800|}}
* Put the plugin code into a directory FusionDirectory is reading (see above).
* Run :shell:`fusiondirectory-setup --update-cache` as root.
* Log out, log in.
A tab should now shows in user edition mode, with the attributes we specified:
.. image:: /_static/images/demoplugin.png
Displaying the plugin in the "My account" menu
----------------------------------------------
You may also want the plugin to show in the "My Account" menu, if your plugin is for users and you've set plModifySelf to TRUE.
For this, you need your plugin to have a main.inc PHP file.
Just put this in it:
......@@ -179,4 +187,4 @@ Just put this in it:
<?php
simplePlugin::mainInc('demoPlugin', $ui->dn);
?>
\ No newline at end of file
?>
LDAP schemas
============
If your plugin needs a new schema or stores data in config back-end, the following rules apply
.. toctree::
:maxdepth: 2
schemaname
numberrules
namerules