= Generic Database Messages: Using modelglue.!GenericCommit =

When this message is broadcast, the !DataController will attempt to save a record to a given table.

It performs this action by doing the following:

  1. Loading an existing record to perform updates, or creating a new record to insert of none matches the criteria specified.
  1. Updating the record's field values. By default, any field with a corresponding value in the viewstate (the combination of FORM and URL scopes) will be set to the value in the viewstate.[[BR]][[BR]] This means that for a given contact, the value of a form input named "firstname" will automatically populate the Firstname property of a contact record.[[BR]][[BR]] By default, the !DataController will attempt to populate all fields from any like-named values in the viewstate. To control which properties to populate, use the "properties" argument as documented below.
  1. Validating the record by calling its Validate() method.
  1. If the record is valid, the !DataController will save its data to the database
  1. Last, the !DataController adds one of two results: "commit" or "validationError". '''Adding result mappings for these result names works in the same manner as any other result mapping.'''

This message is configured by using the following <argument> tags:

  1. Object (Required) - The name of the table to which to commit a record.
  1. Criteria (Required) - A list of viewstate values to use as filters. Any value listed whose name matches a column in the target table will be used as a filter in the query's WHERE clause. This will most often be set to a list of the table's primary keys. If left empty, a new record will be created. If a given record matches the criteria specified, the record will be updated. Otherwise, a new record will be inserted.
  1. !RecordName (Optional) - The name of the viewstate value to set the resultant record into. Defaults to Object & "Record".
  1. !ValidationName (Optional) - The name of the viewstate value to set a collection of validation errors into. Defaults to Object & "Validation".
  1. Properties (Optional) - The names of the Record's fields to attempt to populate from like-named values in the viewstate. Defaults to all of the record's fields.

== Examples ==

=== A Basic Generic Commit ===

To perform a basic commit on the Contact table, the following <message> tag could be added to an <event-handler>:

{{{
<message name="modelglue.GenericCommit">
    <argument name="object" value="Contact" />
    <argument name="contactId" value="Contact" />
</message>
}}}

A View could then <cfdump> the record by performing the following code:

{{{
<cfdump var="#viewstate.getValue("ContactRecord")#" />
}}}

A View could then <cfdump> any validation messages by performing the following code:

{{{
<cfdump var="#viewstate.getValue("ContactValidation")#" />
}}}

Assuming an event-handler name of "contact.commit", visiting the event handler with the following URL would result in updating !ContactId 42's first name to "Fred".

index.cfm?event=contact.commit&contactId=42&firstname=Fred

=== Customizing the Viewstate value name ===

To perform a basic commit on the Contact table and specify viewstate value names for both the record and its validation, the following <message> tag could be added to an <event-handler>:

{{{
<message name="modelglue.GenericCommit">
    <argument name="object" value="Contact" />
    <argument name="contactId" value="Contact" />
    <argument name="recordName" value="myCommittedContact" />
    <argument name="validationName" value="validationForContact" />
</message>
}}}

A View could then <cfdump> the record by performing the following code:

{{{
<cfdump var="#viewstate.getValue("myCommittedContact")#" />
}}}

A View could then <cfdump> any validation messages by performing the following code:

{{{
<cfdump var="#viewstate.getValue("validationForContact")#" />
}}}

Assuming an event-handler name of "contact.commit", visiting the event handler with the following URL would result in updating !ContactId 42's first name to "Fred".

index.cfm?event=contact.commit&contactId=42&firstname=Fred

=== Committing Specific Properties ===

To perform a basic commit on the Contact table where only the Firstname would be updated, the following <message> tag could be added to an <event-handler>:

{{{
<message name="modelglue.GenericCommit">
    <argument name="object" value="Contact" />
    <argument name="contactId" value="Contact" />
    <argument name="properties" value="Firstname" />
</message>
}}}

A View could then <cfdump> the record by performing the following code:

{{{
<cfdump var="#viewstate.getValue("ContactRecord")#" />
}}}

A View could then <cfdump> any validation messages by performing the following code:

{{{
<cfdump var="#viewstate.getValue("ContactValidation")#" />
}}}

Assuming an event-handler name of "contact.commit", visiting the event handler with the following URL would result in updating !ContactId 42's first name to "Fred" but '''not''' updating the lastname to "Finklebuster"

index.cfm?event=contact.commit&contactId=42&firstname=Fred&lastname=Finklebuster