Add Extrafields on PDF Models

This page give you some advises how to integrate complementary attributes (extrafields) into PDF models of Dolibarr.

This is a exemple done on the Invoice template and may needs to be adapted to your needs. It is based on billing document but it will be the same for the others documents on other modules (propal/order...)

New starting from Dolibarr V12

Since Dolibarr V12, new PDF templates are available that display automatically complementary attributes (extrafields) into PDF

The list of PDF Models with extrafields :

Module PDF Model name Dolibarr min version
Shipping espadon V12
Order eratosthene V12
Invoice sponge V12
Quotation cyan V12
Supplier order cornas V12
Delivery storm V13

Prerequisite

You may need to read the following links before starting to read this one, some paragraph will come from these links :

The extrafield used here for the example is: my_extra or my_line_extra

Create a Complementary Attributes on Invoices Module

First you need to create your complementary attribute. This complementary attributes can be of two types :

  • Module complementary attribute
  • Line complementary attribute

Access to the configuration

Go on the Dolibarr application > Setup > Modules/Applications

Click on the parameter icon   of the Invoices module Then you can create Module or Line complementary attribute

Module complementary attribute

Go on the Complementary attributes (invoices) tab

Put the all the mandatory fields, especially the Attribute code that will be used in the next chapters

You should end up with something like that :

Line complementary attribute

Go on the Complementary attributes (lines) tab

Put the all the mandatory fields, especially the Attribute code that will be used in the next chapters

You should end up with something like that :

Verification on the Invoices Module

Clic on Billing|Payement and select New invoice

If you have created a Module complementary attribute, you should have that :

If you have created a Line complementary attribute, you should have that :


Create a new invoice template

All the steps are describes there Create a PDF document template

  • Open the core\modules\facture\doc\ directory
  • Copy the pdf_crabe.modules.php in the same directory
  • Rename the copy as pdf_my_template.modules.php
  • Edit and make the following changes in the code:
  1. Rename class pdf_crabe to class pdf_my_template
  2. Rename constant $this->name = "crabe"; to $this->name = "my_template";
  3. Update the $this->description with your description
  4. Save file. Now the template will be available in the list of models in Dolibarr
  5. Test this model (by generating a pdf) before going further ...

Modify the new invoice template

  • Open the new template pdf_my_template.modules.php
  • Look for the last require_one lines ate the beginning of the template
  • Add the line
    require_once DOL_DOCUMENT_ROOT.'/core/class/extrafields.class.php';
    

Module complementary attribute

  • Find the
    function write_file
    
  • Just before the
    // Affiche notes
    
  • Add the code to load extrafield array in object
    $extrafields = new ExtraFields($this->db);
    $extralabels=$extrafields->fetch_name_optionals_label($object->table_element);
    
  • Add the code to load extrafield into object
    $object->fetch($rowid);
    $object->fetch_optionals($rowid,$extralabels);
    
  • Add the code to print the extrafield
    $pdf->writeHTMLCell (190,3, $this->posxdesc-1, $tab_top-5, $outputlangs->convToOutputCharset($object->array_options['options_my_extra']),0,1);
    
     
  • Result :

Line complementary attribute

  • Find
    $object->fetch_thirdparty();
    
  • Add, just after, the code to load extrafield array in object
    $extrafieldsline = new ExtraFields($this->db);
    $extralabelsline=$extrafieldsline->fetch_name_optionals_label($object->table_element_line);
    
     
  • Find
    // Loop on each lines
    for ($i = 0; $i < $nblignes; $i++)
    {
    
  • Add, just after, the code to load line extrafield into object
    $object->lines[$i]->fetch_optionals($object->lines[$i]->rowid,$extralabelsline);
    
     
  • Find
    $posYAfterDescription=$pdf->GetY();
    
  • Add, just before, the code to display the line extrafield
    $pdf->MultiCell(0, 3, $outputlangs->convToOutputCharset($object->lines[$i]->array_options['options_my_line_extra']), 0, 'L', 0);
    
     
  • Result :

Special Case for Extrafields type "Select list"

Configuration

You can create a line or a module extrafield with the type Select list

Verification on the Invoices Module

You should have a Module or Line extrafield (on this print screen this a Module)

Invoice Template

On the php invoice template, if you use the classical php code to print the extrafield, you will print the code (1 or 2 in our exemple) instead of printing the label (Hello Word or Hello Alone in our exemple).

To display the label instead of the code, you should replace the :

$outputlangs->convToOutputCharset($object->array_options['options_my_extra'])

by :

$extrafields->showOutputField('my_extra', $object->array_options['options_my_extra'], '', $object->table_element)

Special Case for Extrafields type "Date"

Configuration

You can create a line or a module extrafield with the type Date

Verification on the Invoices Module

You should have a Module or Line extrafield (on this print screen this a Module)

Invoice Template

On the php invoice template, if you use the classical php code to print the extrafield, you will print the timestamp (1570450273 for exemple) instead of printing the date in human readable format (10/7/2019 12:11:13).

To display the date in human readable format, you should replace the :

$outputlangs->convToOutputCharset($object->array_options['options_my_extra'])

by :

dol_print_date($object->array_options['options_my_extra'],"dayhour",false,$outputlangs,true)

Special Case for Product extrafields on Invoice Line

If you have defined a Product complementary attribute and you use that product on a Invoice Line, you may would like to be able to display product complementary attribute. In that case you should include the following code:

Invoice Template

Include Product Extrafield

  • Find
    // Loop on each lines
    for ($i = 0; $i < $nblignes; $i++)
    {
    
  • Just after add :
					if ($object->lines[$i]->fk_product)
					{
						require_once (DOL_DOCUMENT_ROOT."/product/class/product.class.php");
						$product = new Product($this->db);
						$product->fetch($object->lines[$i]->fk_product);

						$extrafields_product = new ExtraFields($this->db);
						$extralabels_product = $extrafields_product->fetch_name_optionals_label($product->table_element);

						$product->fetch_optionals($product->rowid, $extralabels_product);
					}

Display Product Extrafield

Instead of using that :

$outputlangs->convToOutputCharset($object->array_options['options_my_extra'])

Should be replace by :

$outputlangs->convToOutputCharset($product->array_options['options_my_product_extra'])

Special Case for Third party extrafields

If you have defined a Third party complementary attribute, the attribute is automatically loaded on the object, you can directly use it

Display Third party Extrafield

$pdf->writeHTMLCell (190,3, $this->posxdesc-1, $tab_top-5, $outputlangs->convToOutputCharset($object->thirdparty->array_options['options_my_third_party_extra']),0,1);


Manage the Position of the extrafield in the pdf

To change the position on the PDF work on :

  • Manage horizontal position $this->posxdesc-1 / $this->posxdesc+1
  • Manage vertical position $tab_top-1 / $tab_top+1