Save Database Records
There are 2 field types that instruct Wrival to save a form's fields
to databases, which are
The difference between the two are:
- APPEND This simply appends any new entries. It doesn't delete any existing entries and allows a database have multiple entries using the same keys.
- SAVE This first deletes any existing matching keys and then saves one new entry. This makes it so there can be only entry for a unique key.
In order for
SAVE to work the request
must pass the following rules:
SAVEvalue must be either a database object name or comma-separated database names. Only valid database names will be processed.
- Form Method must be POST. (GET can be hacked so it's not allowed.)
- The request must be from a form that resides on the same domain name.
How to Name Fields for (Default) Values for Entries
By using a header name as a form field its value will be the (default) value for any entries that does not have any more specific fields for to it. For example, a database's column for the header "Desc" would be populated with a form field's value that is named "Desc" unless a more specific field were present for the entry being written.
How to Name Fields for Specific Entries
When saving multiple entries from a single form, specific form fields can be
identified by using an index of each entry being saved. If the value of
KEYS is 3 then that means we can use 1_, 2_, and 3_ as the start
of each entry's field name followed by header names as desired. For example,
a form field named "1_Desc" would only apply to the first entry being saved.
"Desc" is an assumed header name in that example. These types of fields will
override the fields without the index.
How to Name Fields for Specific Entries in Specific Databases
If there is more than one database in
instructing fields to go to specific databases instaed of all of them simply
prepend the database name to any fields. For example, a form's field name of
"DB2_Desc" means that its value would only be saved for the DB2 entry or
entries. Furthermore, a field named "DB2_2_Desc" could be used to specify the
value to go towards DB2's second entry's Desc column. The more specific
fields always override any others.
Although it is allowed, it is recommended to avoid using underscores as part of database names, header names, and key values to prevent naming conflicts. While these naming schemes where setup in such a way to prevent any naming conflicts, while they are not likely to ever present a problem, it is still technically possible.
Saving Fields by Header Types
Some header types act as filters for saving data. When a database object is created or adjusted the header types are selected then. When a form is posted and instructed to save an entry, each field is automatically converted or filtered to reflect the header's type. For example, a form field with a value of 5.333 that is being saved to a Integer type of database field would be saved as 5.
Special Handling of Header Types
Forms with uploads must be less bytes than the configured in
The following header types also have additional special handling.
- data May be updated using any input type including
- image Uploading image files must be of a valid type as configured in the
IMAGE_TYPESserver variable. Width and height in pixels are automatically read and saved. If it fails to save an error message (if available) will be appended to the image's database value.
- file If
FILE_TYPESis not nothing, the upload must be of one of its file types.
- text May be updated using any input type including
Also the form tag must have the
enctype attribute with a value of
multipart/form-data. For example:
<form method="post" action="/" enctype="multiplart/form-data">
Override Image and Text values with _OPTION
Add an additional field with
_OPTION for overriding how their
values will be saved within the database's table. This is allowed specifically
text types it is possible to populate the
field's value within the database table itself.
Text can have a value of 1, which
will enable the text-to-html feature for its field. The
is saved as 9 values separated by a bar, |, and includes (in this order)
pixel width, pixel height, image alt, image attributes, link url, link target, link attributes,
and the last is for any error messages during their upload. Each of those values
IMG tag and a
A tag as defined.
Optionally, you may provide keys in a
KEYS field and Wrival
will save them as entries. To save only certain keys to a specific database
the database name can be appended to
KEYS_ in its own field.
- KEYS The keys to save for all databases unless there's a specific
KEYS_(+databas name). (optional)
- KEYS_(+database name) The keys to save for a specific database. (optional)
If a form doesn't provide a database's Key header name as a field then the database will generate a new unique key based on how it was setup to do so. In that case a key will be a larger number than that of all the keys already in the database.
- KEYS_SAVED Once a form has been processed this variable will return a comma-separated list of all the keys saved.
- KEYS_SAVED_(+database name) The keys saved for a specific database.
First, evaluate how many entries and where to save them:
SAVE/APPEND="DB1,DB2,DB3=5" Save 1 entry to each DB in the list (or more, like DB3, if they have their own value or if there are more keys in their KEYS field). (Processes all
SAVE's DBs before
- For each DB, determin each key using values from the first defined occurance of these different options:
KEYS_(+DB) If this has more it overrides the amount in the APPEND/SAVE value.
KEYS Also, if this has more it overrides the amount in the APPEND/SAVE value.
- Key Header An HTML field with a name that matches the database's first header (the key of the database).
- Key Generator Wrival will automatically generate a key (either an increment or the highest number existing key plus one).
- Delete (all) keys' entries. (
- Save keys' entries.
Then for each entry to save, save the first field value found using these different options:
- DB_INC_HEADER (only if DB was instructed to save multiple entries as a number)
- INC_HEADER (only if DB was instructed to save multiple entries as a number)
Wrival sets the variable
FORM_REQUIRE to "True" and the processes for
APPEND (including uploads) will only
be processed if this value is True. This provides a means for doing extra form
authentication within the page request of the form. For example, a form could be
checked for validating a user before saving anything or to check user input of
an image interpretation to ensure that the user is not a bot.
This example saves a new entry to a database.
ForSale (example database):
Key Description Price 123 Short sleave shirt 19.95 124 Long sleave shirt 24.95
Form<input type="hidden" name="SAVE" value="ForSale">
<input type="hidden" name="Key" value="125">
<input type="hidden" name="Description" value="Sweater">
<input type="hidden" name="Price" value="39.95">
Key Description Price 124 Long sleave shirt 24.95 123 Short sleave shirt 19.95 125 Sweater 39.95
In that case, if the key was instead 124 it would have deleted the 124 entry and then written a new one using the form's data. This is how updating existing data can be done. Also, if there were no Key field in the form the database would have automatically incremented a key to 125.