Extrafields

Return to developer
documentation index

Extrafields

Extrafields allow to add others datas to Dolibarr standard database schema. Introduced in version 3.2, extrafields are now implemented in most business objects :

• Thirdparties & contacts
• Users
• Events
• Proposal
• Customer Invoices
• Orders
• Supplier Proposal
• Supplier Invoices
• Supplier Orders
• Products & services
• Member & member type
• Projects & project tasks (since 3.4)
• Categories
• Expense Report

Technical implementation

Each object has its table in database to store values of extrafields.

Datatables extrafield tables models

 llx_BaseTableNAme_extrafields
 rowid                     integer AUTO_INCREMENT PRIMARY KEY,
 tms                       timestamp,
 fk_object                 integer NOT NULL,
 import_key                varchar(14)

An example of mysql definition file for extrafields implementation on an object :

 create table llx_place_room_extrafields
 (
   rowid                     integer AUTO_INCREMENT PRIMARY KEY,
   tms                       timestamp,
   fk_object                 integer NOT NULL,
   import_key                varchar(14)                          		-- import key
 ) ENGINE=innodb;

The "Unique" property of extrafield create a `UNIQUE INDEX` on this field, forcing objects to have a unique value for their extrafield (two objects cannot have the same value).

Usage

Object Link filters

An Object Link extrafield can filter the objects shown in its selection list. The descriptor format is:

ObjectName:classPath:<showempty>:(field:operator:value)

For example, to show objects whose status is 1:

ObjectName:classPath:1:(status:=:1)

The segments are:

• ObjectName: the Dolibarr object name to link to.
• classPath: the path to the PHP class for that object.
• <showempty>: use 0 or 1 in this slot. Current code has a nuance: extrafield rendering derives whether to offer an empty choice from the field's Required and default-value settings, while the link-field parser treats a numeric third segment as its add-create-button flag. Do not rely on this slot to override the empty-choice setting.
• (field:operator:value): a filter in Dolibarr's Universal Filter Syntax. Keep it in parentheses, with the field name, operator, and value separated by colons.

Supported operators are =, !=, <, >, <=, >=, in, notin, like, notlike, is, and isnot. For example, (status:=:1) means status = 1. Criteria can be combined with AND or OR.

Placeholders and object context

• $ID$ is the ID of the current object. For an extrafield on an invoice line, it is the line ID, not the parent invoice ID or its third party.
• $MODE$ is replaced with the current display mode, such as list or view.
• $ENTITY$ is replaced with the current entity ID.
• $SEL$ can represent SELECT in a subquery only when the PHP global $dolibarr_allow_unsecured_select_in_extrafields_filter is enabled. This permits unsecured SELECT subqueries and is disabled unless explicitly enabled. Enabling it is an administrator security decision; a subquery should not be presented as the default workaround.

The issue's example, Contact:contact/class/contact.class.php:*:fk_soc=:__THIRDPARTY_ID__, is malformed: the filter needs parentheses and the field:operator:value format. A syntactically corrected form using the supported current-object placeholder is:

Contact:contact/class/contact.class.php:1:(fk_soc:=:$ID$)

On an invoice-line extrafield, however, $ID$ is the line ID, so this does not filter contacts by the parent invoice's third party. __THIRDPARTY_ID__ is a template substitution token, not a placeholder supported by this extrafield-filter path. The parent third party is not directly exposed to this filter.

Load class for extrafields

To use extrafields all pages need include

require_once DOL_DOCUMENT_ROOT.'/core/class/extrafields.class.php';

Load extrafield array in object

$extrafields = new ExtraFields($db);
$extralabels=$extrafields->fetch_name_optionals_label($object->table_element);

$extralabels will be an array with code and label of extrafields. This code must be placed into the class for example into the function "write_file".

Load extrafield into object

Extrafields are loaded in $object->array_options array.

$object->fetch($rowid);
$object->fetch_optionals($rowid,$extralabels);

This code must be placed just after the above.

Display extrafield value into PDF or HTML

After load extrafields

HTML Exemple

print $object->array_options ['options_XXX'];

Where XXX is the code of the extrafields

PDF example

$pdf->MultiCell (0,5, $outputlangs->convToOutputCharset($object->array_options ['options_XXX']),0,'L'); )

Where XXX is the code of the extrafields

A dedicated page to show how to integrate extrafileds into PDF can be found there : Add Extrafields on PDF Models

Display extrafield value of lines into PDF or HTML

After load extrafields

HTML Exemple

print $object->lines[$i]->array_options['options_XXX'];

Where XXX is the code of the extrafields

PDF example

$pdf->MultiCell (0,5, $outputlangs->convToOutputCharset($object->lines[$i]->array_options['options_XXX']),0,'L');

Where XXX is the code of the extrafields

How to change the labels of the columns when using models (propals, etc.)

In the PHP code of the model you can change the labels of your extrafield by changing into the function named "_tableau(...)"

Before call $object->create() or $object->update()

Values of extrafields sent by form need to be retrieve. For doing that, use this method :

$ret = $extrafields->setOptionalsFromPost($extralabels,$object);

Inside edit page to display extrafields

$reshook=$hookmanager->executeHooks('formObjectOptions',$parameters,$object,$action);    // Note that $action and $object may have been modified by hook
if (empty($reshook) && ! empty($extrafields->attribute_label))
{
      print $object->showOptionals($extrafields,'edit');
}

Inside view page to display extrafields

$reshook=$hookmanager->executeHooks('formObjectOptions',$parameters,$object,$action);    // Note that $action and $object may have been modified by hook
if (empty($reshook) && ! empty($extrafields->attribute_label))
{
      print $object->showOptionals($extrafields);
}

After fetch method of this object class

require_once(DOL_DOCUMENT_ROOT.'/core/class/extrafields.class.php');
$extrafields=new ExtraFields($this->db);
$extralabels=$extrafields->fetch_name_optionals_label($this->table_element,true);
if (count($extralabels)>0) {
	$this->fetch_optionals($this->id,$extralabels);
}

After Update method of this object class :

// Actions on extra fields (by external module or standard code)
// FIXME le hook fait double emploi avec le trigger !!
$hookmanager->initHooks(array('HookModuleNamedao'));
$parameters=array('socid'=>$this->id);
$reshook=$hookmanager->executeHooks('insertExtraFields',$parameters,$this,$action);    // Note that $action and $object may have been modified by some hooks
if (empty($reshook))
{
	if (empty($conf->global->MAIN_EXTRAFIELDS_DISABLED)) // For avoid conflicts if trigger used
	{
            $result=$this->insertExtraFields();
            if ($result < 0)
            {
            	$error++;
            }
        }
}
else if ($reshook < 0) $error++;

After delete method of this object class

// Removed extrafields
if (! $error)
{
      if (empty($conf->global->MAIN_EXTRAFIELDS_DISABLED)) // For avoid conflicts if trigger used
      {
      $result=$this->deleteExtraFields();
      if ($result < 0)
      {
        $error++;
        dol_syslog(get_class($this)."::delete erreur ".$errorflag." ".$this->error, LOG_ERR);
      }
   }
}

Admin pages

$elementtype='facture'; //Must be the $table_element of the class that manage extrafield

Repair Database

Search and find definition of $listofmodulesextra add the new extrafield declaration

$listofmodulesextra=array('societe'=>'societe','adherent'=>'adherent','product'=>'product',
			'socpeople'=>'socpeople', 'commande'=>'commande', 'facture'=>'facture',
			'commande_fournisseur'=>'commande_fournisseur', 'actioncomm'=>'actioncomm',
			'adherent_type'=>'adherent_type','user'=>'user','projet'=>'projet', 'projet_task'=>'projet_task');

Related videos

Extrafields: (vocal in french but subtitles are available and review in this language)