439
edits
Changes
→Custom AJAX Functions: Added description
Line 710:
Line 710:
== Custom AJAX Functions ==
== Custom AJAX Functions ==
+
+CustomFields now supports AJAX to send/receive data and dynamically update HTML form's inputs. This section will describe how you can manually implement AJAX for any field, and then it will explain how you can manually manage a cascading field.
+
+=== Attaching AJAX to any field ===
+
+Note: you can skip this part if you just want to manually manage a cascading field, but this can help you understand the way it works.
+
+An AJAX script can be attached to any field (including non-CustomFields) by using the method:
+
+<source lang="php">
+$customfields->ShowInputFieldAjax($id, $phpcallback, $on_func="change", $request_type="post")
+</source>
+
+Where $id is the HTML id of the field you want to attach the AJAX to, and $phpcallback the relative path from Dolibarr's htdocs root folder to the php script that will receive and send back data.
+
+The AJAX script will automatically manage sending/receiving of data:
+
+* automatically send all form's inputs values, as well as the current calling field's name and value. The sending happens on change by default, but another event can be set using the $on_event argument. Data will be sent using standard GET or POST.
+* Upon reception of data from the php script, the AJAX script will automatically parse the data and update the HTML fields.
+
+The PHP callback script must send back to AJAX the data in JSON encoded format, and with with a specific format:
+
+* the data must be an associative array, where each entry's key is the name (not ID!) of an HTML field to update.
+* each entry's value is an associative array, where each sub-entry's key is the action to do. Available actions: 'options', 'value', 'html', 'alert'.
+* each sub-entry's value is the value for this action and HTML field.
+
+Thus, this approach allows to generically support a wide range of updating actions, managed automatically.
+
+You, the implementer, have just to edit the PHP callback script and return an associative array defining what action you want for each field you want to update. This is exactly what has been implemented in the Custom AJAX Functions library, which simplifies even more your job by managing automatically the step described here (generating AJAX and formatting data), so that you can focus on '''making the data'''.
+
+=== Custom cascading ===
+
+To manage cascading manually, a very similar system to the Overloading Functions was implemented: you just have to define a function, with the name including the module and the field's name you want to manage, and CustomFields will call your function instead of managing automatically the AJAX for this field.
+
+Note also that you have to enable the Cascade Custom option for this field in the admin panel, else your function won't be called.
+
+To make your own Custom Ajax Functions, first rename the following file: /customfields/fields/customfields_fields_ajax_custom.lib.php.example
+
+Into (just remove the .example at the end): /customfields/fields/customfields_fields_ajax_custom.lib.php
+
+Then open it with your text/php editor.
+
+You will find inside all the information you need, here is an excerpt:
+
+<source lang="php">
+/* Description: here you can define your own interactive manipulation of the customfields on create pages, which will then be sent back to user's browser via AJAX.
+ *
+ * Guidelines:
+ * You can use and modify any variable, CustomFields will then use them afterwards (except for 'full' functions which completely overload CustomFields, so that you must take care of everything on your own).
+ * If not using full method, just return an array $result which contain an entry for each of your customfields, and inside the manipulation you want. Eg: $result = array('cf_mycustomfieldname' => array('options'=>array('option1'=>'optiontitle1', 'option2'=>'optiontitle2'));
+ * If using a full method, you have to print the JSON encoded $result array yourself (eg: print(json_encode($result)); ). Please also be aware that it will stop any other printing, thus you can't use more than one full method per module (the other fields will just be silenced, because, well, there's no way to json reencode an array that is already printed, thus it's not possible to append data to what you print).
+ *
+ * The $result array works this way:
+ * - At the first array level, the keys define which customfield's HTML field will be modified. The value contains an array defining the changes that will be done (see 2nd array level).
+ * - At the second array level, the keys define what kind of change you will do, and the value is the value of the change. Available change actions are: 'options' to just define the options for a select dropdown list type (the value must be an array where the keys will be the html value, and the value will be the title displayed for this option), 'html' change the whole html, 'value' change the currently selected value, 'alert' shows an error message to the user.
+ * You can also store all your alert messages directly at first level, in an array of messages to show, they will all be shown, eg: $results['alert'][] = 'Error message1'; $results['alert'][] = 'Error message2';
+ *
+ * To access the database using Dolibarr's core functions, you can use:
+ * global $db;
+ * then you can: $db->query('SELECT * FROM table'); or use the equivalent $customfields->fetchAny('*', 'table') for added security against injection.
+ *
+ * $_POST is sanitized (except when using a full method, then there's no sanitization) and available in the variable $data, but you still should sanitize your inputs if it's coming from users, so please resanitize $_POST depending on your usage (eg, by typing your variables with filter_var() or filter_var_array()).
+ *
+ * You can also access a variety of other things via globals, like:
+ * $conf - contain all Dolibarr's config
+ * $user - current user's loggued (can access his rights to check security)
+ * $langs - current language of the user (for internationalization)
+ *
+ * Lastly, you can access the raw GET and POST variables using:
+ * $myvar = GETPOST('myvar');
+ *
+ *
+ * Format for the name of your functions:
+ * All ajax custom functions must be named with the following convention ($fieldname is the field's name without the prefix 'cf_'):
+ * customfields_field_ajax_$module_$fieldname
+ *
+ * You can also make a generic function that will be called for all fields of the module if there's no specific function for the current customfield
+ * customfields_field_ajax_$module_all
+ *
+ * For example, for the module invoice (called 'facture' in Dolibarr, see conf_customfields.lib.php) and a field named 'myfield', you can use:
+ * customfields_field_ajax_facture_myfield
+ *
+ * And a generic function for the invoice module:
+ * customfields_field_ajax_facture_all
+ *
+ * This generic function will be called for all customfields in the invoice module, except for myfield which will use the specific function defined just above.
+ *
+ * A list of modules can be found in conf_customfields.lib.php in the $modulesarray variable.
+ *
+ * IMPORTANT: for a field to call a function here, the option cascade MUST be enabled for this field in the CustomFields admin panel. Also note that these functions will only be called at creation sheet, for editing sheet (when editing a customfield on an object already created), you should also create a custom overloading function of type 'edit'.
+ *
+ */
+</source>
== Adding a new sql data type ==
== Adding a new sql data type ==