update_form_code

Write one of the four procedures that Formulize runs at moments in the life of an entry in a form. To write the shared code library that belongs to an application rather than to a form, use update_application_code instead.

The code you send replaces that procedure completely. It is not added to what is there. Call get_custom_code first, and if you are adding to existing logic, include the existing code in what you send. Sending an empty string removes the procedure altogether.

Your code is placed inside a function that Formulize generates, so write the statements only - do not write a function declaration.

In the three save and delete procedures, the entry’s values arrive as variables named after the element handles: the value to be saved in an element with the handle ‘artifacts_year’ is available as $artifacts_year. This does not apply to form_custom_edit_check, which is about permission rather than about data and receives no element values.

The $currentValues array is how you tell what changed. In the save procedures the values that were in the database before this save operation started, are available as $currentValues[‘handle_name’]. For example, this lets you compare $currentValues[‘artifacts_year’] with $artifacts_year to see whether what’s in the database now is different from what is being/has been saved.

The values of the element handle variables, and of the $currentValues array, are all formatted for storage in the database. For example, a linked element’s value will be the entry_id of the selected entry or entries, not the human readable value the user selected. This is the opposite of how the other tools work. create_entries and update_entries accept readable values and convert them for you, and get_entries_from_form lets you filter on readable values too. Custom code has no such conversion in either direction: you read the stored values and you write the stored values, so you have to know how the data is actually held. For complete details of the functions and formulizeDataHandler methods available to this code, use the get_documentation tool, if it is available.

What each procedure receives, and what it should do:

• form_on_before_save - runs before the entry is written. Variables: the element handle variables and the $currentValues array (see above), $form_id, and $entry_id which is the string ‘new’ when the entry does not exist yet. Assign to the element handle variables to change what gets written, for example to force a certain value for one element based on the value of another element. Return false to stop the save from happening at all.
• form_on_after_save - runs after the entry is written. Variables: the element handle variables and $currentValues (see above), $form_id, $entry_id which is always the actual saved entry id (never ‘new’) since the save operation has completed now, and $newEntry which is a boolean that will be true if this was the first time the entry was saved, and false otherwise for existing entries being resaved. Use this procedure for any bookkeeping or updates that need to happen in the system after a successful save.
• form_on_delete - runs when an entry is deleted. Variables: $entry_id, $form_id, and the element handle variables holding the values that were in the database before the deletion. There is no $currentValues array here.
• form_custom_edit_check - decides whether someone may edit an entry. Variables: $form_id, $entry_id, $user_id, and $allow_editing, which is a boolean indicating whether the user would normally be able to edit the entry, based on the Formulize permission settings. Alter $allow_editing to control whether the user will actually be able to edit the entry; its value at the end of the code will be respected. No element values are available here.

There is no syntax checking when you save. A mistake will not be reported here - it will surface when someone next uses the form, so re-read what you wrote before finishing.