Declaring parameters that take elements
When a function or method in Formulize takes an element as one of its parameters, by its handle, its id
or the element object, its docblock says so with an @formulizeElement line. Anyone adding a function
or method like that, person or AI, should add the line too.
Formulize reads these lines. When someone renames an element, it updates the handle wherever code passes it, as a quoted string, to a parameter declared this way: in custom code files, formulas, save procedures, screen templates and code kept in the database. A parameter without the line is invisible to this, so after a rename, code that calls it with the old handle is left calling it with a handle that no longer exists.
How to write it
Put one line for each parameter after the @param lines, naming the parameter and the shape the
elements take in it:
/**
* Retrieve data from forms, based on their connections ...
* @param int fid - The id number of the main form ...
* @param array elementHandles - Optional. An array of arrays, that defines the form elements to include ...
* @param string sortField - Optional. The element that should be used to sort the entries ...
* @return array Returns the dataset as an array ...
* @formulizeElement $elementHandles lists
* @formulizeElement $sortField commas
*/
function gatherDataset($fid, $elementHandles = array(), ..., $sortField = "", ...) {
The shapes are:
| Shape | The argument is | For example |
|---|---|---|
one |
one element | display($entry, 'year') |
commas |
a string of elements separated by commas | gatherDataset(5, sortField: 'year, price') |
list |
an array of elements | array('year', 'price') |
lists |
an array of arrays of elements, keyed by form id | gatherDataset(5, array(5 => array('year', 'price'))) |
keys |
an array whose keys are elements | formulize_writeEntry(array('year' => 1990)) |
map |
an array whose keys and values are both elements | $dataHandler->cloneData(5, array('year' => 'year_copy')) |
A parameter that can be given more than one kind of argument is declared with the shape that has elements
in it. For example, the $operator of
findFirstEntryWithAllValues is either
one operator as a string, or an array of operators keyed by element. It is declared keys. A shape only
applies when the argument is written that way, so a string passed to it is left as it is.
When to declare a parameter
- When every quoted string that can be passed to it is an element. An element’s handle, or one of the
metadata fields such as
entry_idorcreation_uid, which are never an element’s handle. A parameter that sometimes takes something else, like a column of another table or free text, is not declared. - When the method name is unique. The method must be identifiable by its name alone, so if any
other method in Formulize has the same name, do not declare
@formulizeElementin its docblock. For example,get()is a common method name used by several classes, so it cannot take a@formulizeElementdeclaration.writeEntry()is a name only the data handler uses, so it can. - When the code is in one of the locations Formulize pays attention to. Declarations are only read from
modules/formulize/class/,modules/formulize/include/andmodules/formulize/include/functions/.
What a rename leaves for a person
Only a quoted string written right there in the call is updated:
formulize_writeEntry(array('year') => 1990));
If code builds the argument first and passes it in, it is not updated:
$values = array('year' => 1990);
formulize_writeEntry($values);
In this case, the array might be used for something else as well, and the code analysis quickly becomes intractable. Instead, the file will be listed in the notice shown after the rename so someone can update it manually as appropriate.
ID numbers are never changed
Only element handles are updated. Element ID numbers are always left alone.
Checking your declarations
Run this test against your local Formulize, which has to be installed:
docker exec formulize-web-1 php /var/www/html/tests/element_handle_code_test.php
It fails if a declaration names a parameter the function doesn’t have, or a shape that doesn’t exist, or if a declared method shares its name with another method. It also has a list of the functions and methods that must be declared. If you add one that should always be declared, add it to that list, so the declaration can’t be lost by accident.
Other things with handles
For now this is only for elements. Forms, screens and other things that have handles may get tags of their own in time, following the same pattern.