• ⌂ request
• Methods
  • Constructor
  • cookie()
  • file()
  • filename()
  • get()
  • header()
  • is_ajax_request()
  • post()
  • request()
  • server()
  • set_cookie()
  • set_get()
  • set_post()
  • set_request()
  • update()

request::update()

Update an object from an HTML form.  The object will be updated in memory, and optionally created/updated in the repository (see 'write' option below).

"Other" Fields
If an object field Style is set to 'drop-down with "Other"', the form input value will be checked and used as usual.  However, if the value is set to "-Other", another input with the same form input name followed by "-Other" will be checked for the value.  This makes it easier to use a <select name="field_name"> input for the normal field values with a final <option value="-Other">, and then to have an <input type="text" name="field_name-Other" /> where unique values can be entered.

Validation Errors
The in-memory object will be updated as much as possible, even if there are validation errors.  This is useful so that if the form is displayed again, the (potentially invalid) values from the in-memory object are available and can be included for modification.  If the 'write' option was specified as 'store', the working copy in the repository will be updated, even if there is a validation error because working copies can have invalid values for the same reason.  If the 'write' option was specified as 'approve' or 'save', the repository will not be updated if there was an error.

Email Options
If the email_to and related options are set, mail::mail_object() will be called on the updated object if it is able to be updated successfully, without errors.

Prototype

boolean update(\io_comand_repo\models\Object $object, array $options = [])

Parameters

• object - The object to be updated based on the HTML form submission.  The object does not need to exist in a repository yet.  In other words, it can be a new object created with repo::new_object().
• options - The following optional key/value pairs may be set:
  • allow_updates - If an OID input (typically a hidden input) contains a valid OID for an existing object of the appropriate Content Type, that object will be updated instead of creating a new one when a write option is specified.
  • debug - If TRUE, debug information will be added to the event log to help troubleshoot issues.
  • email_exclude - array of dot-notation object fields to exclude from the email.
  • email_footer - HTML message to display after the object field title/values.
  • email_from - String of comma-separated email addresses
  • email_include - array of dot-notation object fields to exclude from the email.
  • email_message - HTML message to display before the object field title/values.
  • email_oid - Append the object OID to the subject in parenthesis.
  • email_subject - Email Subject.
  • email_to - String of comma-separated email addresses to email.  Email addresses may be in the form of "email@hostname.com" and/or "Friendly Name <email@hostname.com>".
  • exclude - Array of fields to exclude from object update process.  The OID is always excluded.  If a field appears in this array, it will be excluded, even if it also appears in the include array.  If the object already has values set for the excluded fields, they will still be updated in the repository if the write option is set to save or approve, they just won't be updated from the HTML form input values.
  • folder - OID, DOID, UUID or cPath of a folder to put the object in.
  • include - Array of object fields to update from the form.  If not specified, all object fields except OID will be updated from the form.  If specified, only those field specified will be updated, unless they also appear in the exclude array.  If the write option is set, previously set object field values will still store, save or approve, even if they are not included.  In other words, this option only determines which fields are updated from the form, not which fields are updated in the repository.
  • log - A log object where any errors, warnings and notices related to the object updates should be logged.
  • method - 'post' (default), 'get' or 'request', which will use the corresponding method to retrieve form values.
  • prefix - String that will be added to the beginning of all object field Identifiers when retrieving the form values.
  • write - NULL (default), 'approve', 'save' or 'store' to determine if and how the object is automatically updated in the repostory.  If NULL, the in-memory object will be updated, but not updated in the repository, so you will need to call approve(), save() or store() afterward.

Return

Returns TRUE if the object was successfully updated without any validation or other errors.  FALSE if there was a validation or other error.

Example

// add a Form Submission object to the repository based on
// an HTML form submission with input names that match the
// Form Submission content type's field Identifiers.
$log = new \io_comand_web\log();
$object = $repo->new_object('FormSubmission');
$request = new \io_comand_web\request();
$success = $request->update($object, [
    'method' => 'post',
    'write' => 'approve',
    'log' => &$log,
]);
if(!$success && $log){
    echo('Submission Error: ' . $log->as_html());
}

• < set_request()
• session >