Canvas development

Return to developer
documentation index

Canvas is a developer feature to replace screens to create, update or view a card (products, thirdparties, contacts, ...).

For example, you can replace the input form to create a new third party, or to edit it, or replace the card used to view it.

Conditions

Canvas feature is available with Dolibarr 3.2 or higher.

It is for the moment available only for :

• create form of products, contacts and third parties
• edit form of products, contacts and third parties
• view tab of products, contacts and third parties. In most cases, it's only the first tab when you open the card of an object. But you can have a look at new module creation documentation Module_development#The_tab_management to know how to disable other tabs or add yours if you really want to change other tabs too.

Replace a creation form with your own template

First thing to do is to find the URL of standard creation form you want to replace and add the parameter canvas=mycanvas@mymodule. To find url, you can go on page and get URL found at top of your browser.

For example, imagine you want to replace the creation form of third parties with your own form. The url is something like

http://mydomain/societe/soc.php?action=create&leftmenu=customers

After adding the canvas parameter, URL will look like

http://mydomain/societe/soc.php?action=create&leftmenu=customers&canvas=mycanvas@mymodule

When you add a parameter canvas=mycanvas@mymodule on a create page, Dolibarr will use the template file into htdocs called

/mymodule/canvas/mycanvas/tpl/tabname_create.tpl.php

where

• mymodule directory is value mymodule found into canvas parameter (you choose this value and create directory with same value. use lower case values).
• mycanvas is value mycanvas found into canvas parameter (you choose this value and create directory with same value. use lower case value).
• tabname is name of tab or page where initial form was stored. In most cases it is value "card".

For example, we will use value "company@societe" for canvas parameter. This is a value of an already coded demo canvas template for third parties, not used in a standard usage of Dolibarr but provided as "demo". So URL to create a third party using this alternative template is now:

http://mydomain/societe/soc.php?action=create&leftmenu=customers&canvas=company@societe

This means the form to create the third party will be found into template file:

/societe/canvas/company/tpl/card_create.tpl.php

So to use you own template, just choose a value for mymodule, mycanvas, copy and paste a demo template found into Dolibarr directories with new directory and new file name and then edit the template like you want. Template contains all the part under the top menu and at right of left menu. You can change look, field order, add your javascript controls, remove or add your own fields. The only requirement is to keep mandatory fields with same name to avoid errors when you will submit the page. Fields removed will be filled with null or 0 into database. New fields for the moment are ignored. We will see later how we can add code to save them.

Once this is done, you must now add the new create URL into Dolibarr menus or replace the existing one with new one. For this take a look at page Menus_system.

Note that when a record is saved using a canvas, the canvas name mycanvas@mymodule is also stored into database. This is important because this means, Dolibarr will be able to know that this record is a canvas and not the other so it will be able to them suggest a view or edit form dedicated for this record only and keep using standard forms for other records. See next chapters.

Replace an edit form with your own template

Using your own edit form for a record saved using your own create form is as simple as adding a file called

/mymodule/canvas/mycanvas/tpl/tabname_edit.tpl.php

where

• mymodule directory is value mymodule you used as canvas parameter to create record (see previous chapter).
• mycanvas is value mycanvas you used as canvas parameter to create record (see previous chapter).
• tabname is name of tab or page to edit record. In most cases it is value "card".

With our canvas demo company@societe, edit template will be into file

/societe/canvas/company/tpl/card_edit.tpl.php

Note that for edit, changing URL is not necessarly required. Dolibarr can detect your record is a personalized canvas record and automatically scan for this template file to show it if found. If not, standard form will be used. So all you have to do to use your own edit template is copy and paste an existing demo edit template file and rename it with correct value of mymodule and mycanvas and edit it to match your need. Like for creation, all mandatory fields must be kept to avoid errors when submitting the form to save change.

Replace a view form with your own template

Using your own view form for a record saved using your own create form is as simple as adding a file called

/mymodule/canvas/mycanvas/tpl/tabname_view.tpl.php

where

• mymodule directory is value mymodule you used as canvas parameter to create record (see previous chapter).
• mycanvas is value mycanvas you used as canvas parameter to create record (see previous chapter).
• tabname is name of tab or page to edit record. In most cases it is value "card".

With our canvas demo company@societe, view template will be into file

/societe/canvas/company/tpl/card_view.tpl.php

Note that for view, changing URL is not necessarly required. Dolibarr can detect your record is a personalized canvas record and automatically scan for this template file to show it if found. If not, standard form will be used. So all you have to do to use your own view template is copy and paste an existing demo view template file and rename it with correct value of mymodule and mycanvas and edit it to match your need.

Add code to manage new fields

Page waiting to complete. To complete, create an account, go back and clic on "Modify". Page en attente d'être complété. Pour compléter, créez un compte, revenez et cliquez sur "Modifier". Página a completar. Para completarla, cree una cuenta, vuelva a la página y haga clic en "editar" Seite wartet auf Vervollständigung. Um zu helfen, erstelle ein Konto, gehe zurück und klicke auf "Bearbeiten". 待完成，欲帮助完成，注册帐号，点击“编辑" ページは未完成の状態です。完成させるにはアカウントを作成し、ページに戻って「編集」をクリックして下さい。

Example into external module cabinetmed.