How to Use Forms
When forms are posted Wrival automatically processes all
of the data sent and puts every field into variables so that they
are easily accessible and reusable. In the following example
<#mytext> would have the value of any text that
was typed in the text box. This process is done regardless of
whether a GET or a POST was used as the method.
The HTML form's
action attribute should always be
the absolute path to the page that is intended to be returned.
To have the form's
method be a GET
simply do not include the
method attribute or set
its value to a GET.
<form action="/reference/forms.wrival" method="post">
Type some text: <input type="text" name="mytext" value="">
<input type="submit" value="Submit My Text">
Get vs. Post
GET and POST each have their specific uses and care should be taken to determine which one to use to achieve the desired results. Here's a brief summary of the properties they each have:
|Read fields and update cookies.||Yes||Yes|
|URL (allows for history, bookmarks, and hacks).||Yes||No|
|Page cache for results.||Yes||No|
|Accepts large amounts of data or binary characters (uploads).||No||Yes|
|Process Wrival's save and delete functions for database entries.||No||Yes|
|Converts hashes to HTML symbols (<# to <#) preventing user input from being able to write Wrival Inserts).||Yes||No|
During GET requests Wrival sweeps hashes to HTML symbols to prevent
visitors from being able to have their own input be parsed as Wrival Inserts.
HTML tags within user input will still be there. If HTML
is not desired there are a couple of functions that will strip out
or convert tags so that input can be used within HTML for example.
strip removes all HTML tags. The function
safe converts all HTML tag symbols and quotes to
their respective HTML symbols making writing Wrival Inserts impossible.
You must make user input during a POST safe!
During POST requests Wrival does NOT strip or convert any symbols
making it crucial to identify which content is made safe and which
is allowed to have Wrival Inserts written. Whenever using input data
strip functions may be used so
that the current instance of the data is safe. As a more reliable way
to secure and prevent unwanted Wrival Inserts is to not allow them during
the saving process at all in the first place. Setting a database to
"public" will instruct Wrival to convert any data's hashes to HTML
symbols (<# to <#) making it reliably safe for
any future use.
(",public" must be appended to the database's object value in Objects.txt.)
Be mindful of limits.
During a form post, for any fields that have more characters than MAX_FIELD is truncated. MAX_CHARS applies to variables being saved to a database. MAX_TEXT is the maximum size of fields that are to be saved as the text header type. MAX_POST is the byte limit for uploads.
Database Save and Delete Test
For realms not live there's a built-in test that checks that the realm is not live, there's a user logged in, and the target page's permits pass.
Functional Field Names
Wrival also offers a few special field names for managing interaction with database tables. Forms can save and delete database table entries, handle uploads, group fields for loop processes, and write cookies.
Group sets of fields by name, which
returns a comma seperated list. This
pair names and values just like
||Write a cookie using the name of the input field and the value of the field.|
||Write a cookie using the value of the input field as the name of the cookie's value and give it a value of 1.|
Save Database Entries
||Save fields to database tables. Any field names that match database table fields will be saved. A new entry is created every time even if a key is defined and there's a matching entry.|
||The keys to save. If this is not present the database will either increment or use the highest number present plus 1 depending on how the database's key header is configured.|
The keys to save for a specific database. Overrides the
||Save fields to database tables. Any field names that match database table fields will be saved. If a key is defined it will replace an existing entry or create a new one if there isn't.|
Delete Database Entries
Delete any database entries that match
any of the keys provided in
||Define a key or a comma-separated list of keys to be used for the delete function.|
||An individual database entry delete request used for the delete function. (For checkboxes, if the value is "1" the key's entry will be deleted.)|
When using AJAX calls you can use the
Form Related System Variables
||Returns a comma separated list of all the field names passed from the form.|
||Returns a comma separated list of all the available cookies for the current location of the page.|
||Returns the method used for the form (usually GET or POST).|