Save Records

"It's still web development, it's just way easier!"

Save Database Records

APPEND, SAVE

There are 2 field types that instruct Wrival to save a form's fields to databases, which are APPEND and SAVE. 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 APPEND or SAVE to work the request must pass the following rules:

  1. The APPEND or SAVE value must be either a database object name or comma-separated database names. Only valid database names will be processed.
  2. Form Method must be POST. (GET can be hacked so it's not allowed.)
  3. 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 SAVE or APPEND 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 MAX_POST. The following header types also have additional special handling.

  • data – May be updated using any input type including file.
  • image – Uploading image files must be of a valid type as configured in the IMAGE_TYPES server 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_TYPES is not nothing, the upload must be of one of its file types.
  • text – May be updated using any input type including file.

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 for the image and 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 image value 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 populate an IMG tag and a A tag as defined.

Key Values

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.

Saving Process

First, evaluate how many entries and where to save them:

  1. 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 APPEND's.)
  2. For each DB, determin each key using values from the first defined occurance of these different options:
    1. KEYS_(+DB) – If this has more it overrides the amount in the APPEND/SAVE value.
    2. KEYS – Also, if this has more it overrides the amount in the APPEND/SAVE value.
    3. Key Header – An HTML field with a name that matches the database's first header (the key of the database).
    4. Key Generator – Wrival will automatically generate a key (either an increment or the highest number existing key plus one).
  3. Delete (all) keys' entries. (SAVE only)
  4. Save keys' entries.

Then for each entry to save, save the first field value found using these different options:

  1. DB_INC_HEADER (only if DB was instructed to save multiple entries as a number)
  2. INC_HEADER (only if DB was instructed to save multiple entries as a number)
  3. DB_KEY_HEADER
  4. KEY_HEADER
  5. HEADER

Form Authentication

Wrival sets the variable FORM_REQUIRE to "True" and the processes for both SAVE and 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.

Example

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">

Submit, then...

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.