439
edits
Module CustomFields Dev: Difference between revisions
Jump to navigation
Jump to search
Added more CustomFields API infos
(Added more CustomFields API infos) |
|||
| Line 161: | Line 161: | ||
$customfields->setExtra('mycustomfield', $fields->mycustomfield->extra); // store the modified extra options back into the database for future usage | $customfields->setExtra('mycustomfield', $fields->mycustomfield->extra); // store the modified extra options back into the database for future usage | ||
</source> | |||
= CustomFields API = | |||
== Introduction to CustomFields API == | |||
This chapter will cover the basics on how to manually and concretely use the CustomFields class to create/update/fetch/manage custom fields. | |||
This will give you a better understanding of how CustomFields works, as well as giving you insights on how to use it for your own applications. | |||
== Prerequisite to use the CustomFields class == | |||
Before using the CustomFields class, you first must instanciate it. This is a necessary preliminary step before using any of the methods that will be covered inside this chapter, and thus will not be repeated, only shown once here. | |||
<source lang="php"> | |||
// Include the CustomFields class (which contains the main API) | |||
require_once(dirname(__FILE__).'/../class/customfields.class.php'); | |||
// Instanciate a CustomFields object | |||
global $db; // the database handler created by Dolibarr | |||
$table_element = 'currentmodule'; // where $table_element is the database's table name for the module, without the Dolibarr prefix (eg: for 'llx_facture', table_element is 'facture'). You can also find it inside the $object properties (just print_r() it). | |||
$customfields = new CustomFields($db, $table_element); // instanciate the CustomFields class inside $customfields object | |||
</source> | |||
CustomFields keeps track of errors that can happen when executing methods and SQL queries inside the '''error''' and '''errors''' properties, which you can print with the printErrors() method: | |||
<source lang="php"> | |||
// Do something with CustomFields before | |||
if (count($customfields->errors) > 0) { // If there is at least one error | |||
$customfields->printErrors(); // print errors | |||
} | |||
// You can also print your own error message, in two manners: | |||
// 1- submit your own message | |||
$customfields->printErrors('Your own error message here'); // this will print ONLY your error message, using the Dolibarr's AJAX error dialog (standard way of printing errors) | |||
// 2- append your message in the customfields errors | |||
$customfields->errors[] = 'Your own error message to be appended with other CustomFields messages'; | |||
$customfields->printErrors(); // Here your error message will be appended, thus all error messages will be printed. This allows you for example to add more intelligible informations on a specific error. | |||
</source> | |||
== General purpose SQL methods == | |||
CustomFields provide an interface to easily execute various common SQL requests, as well as your own custom SQL requests. | |||
* fetchAllTables() fetch a list of all the tables in the database | |||
* fetchPrimaryField($table) fetch the column_name (and only the column_name!) of the primary field of a table. You can then use fetchFieldStruct() with the column_name to get any information you want. | |||
* fetchAny($columns, $table, $where='', $orderby='', $limitby='') allows you to issue any simple SQL query command, for example fetchAny('*', 'sometable') is equivalent to SELECT * FROM sometable; (but then everything is managed automatically and result is returned to you) | |||
* executeSQL($sql, $eventname) to execute any SQL query you want, this will return you a resource (and NOT a processed nuplet like fetchAny!). $eventname can be anything, it's just for Dolibarr logging facility. | |||
* executeMultiSQL($sql, $eventname) to execute multiple SQL queries | |||
* fetchFieldStruct($id=null, $nohide=false, $table=null, $cachepath=null) allows you to fetch the field's SQL structure of not only custom fields, but of any database's column using the $table variable. Eg: fetchFieldStruct('mycolumn', true, 'mytable'); | |||
== Managing CustomFields structure == | |||
The first step into CustomFields is to create and manage the structure of a custom field. | |||
=== Creating a custom field === | |||
To create a custom field, you can use the addCustomField() method. | |||
<source lang="php"> | |||
$rtncode = $customfields->addCustomField($fieldname, $type, $size, $nulloption, $defaultvalue = null, $constraint = null, $customtype = null, $customdef = null, $customsql = null, $fieldid = null, $extra = null); | |||
</source> | |||
This will take care of forging the (complicated) SQL query with the forgeSQLCustomField() method, and will return you an error if there was a problem. | |||
=== Updating a custom field === | |||
To update a custom field, you can use the updateCustomField() method: | |||
<source lang="php"> | |||
$rtncode = $customfields-> | |||
updateCustomField($fieldid, $fieldname, $type, $size, $nulloption, $defaultvalue, $constraint = null, $customtype = null, $customdef = null, $customsql = null, $extra = null); | |||
</source> | |||
Note: the updateCustomField() and addCustomField() methods can both be used since updateCustomField() is in fact an alias for addCustomField(). CustomFields will automatically detect if a custom field already exists, and update it if that's true, or create it. | |||
Note2: updating a custom field will automatically take care of the constraints and foreign keys on its own, thus you can change the foreign key, or remove it altogether if set to null. | |||
=== Delete a custom field === | |||
You can easily delete a custom field by column_name or by ordinal_position: | |||
<source lang="php"> | |||
$rtncode = $customfields->deleteCustomField($id); | |||
</source> | |||
Note: constraints and foreign keys will also be deleted automatically so you shouldn't encounter any error. | |||
=== Fetch one custom field's SQL structure === | |||
To get the SQL structure of a custom field, which can be quite useful to know for example its datatype or if it has a foreign key, or accepts null values, you can use the fetchFieldStruct() method: | |||
<source lang="php"> | |||
$rtncode = $customfields->fetchFieldStruct($id=null, $nohide=false, $table=null, $cachepath=null); // where $id can be a column_name, an ordinal_position from information_schema.columns or null if you want to fetch all the columns at once | |||
</source> | |||
Note: this function will use caching by default to accelerate future results, but you can disable it, or even change the default cache path. For more informations please read the comments in the source code. | |||
=== Fetch several custom fields' SQL structures === | |||
Use the fetchAllFieldsStruct() method, which is an alias for fetchFieldStruct(): | |||
<source lang="php"> | |||
$rtncode = $customfields->fetchAllFieldsStruct($nohide=false, $table=null, $cachepath=null); | |||
</source> | </source> | ||