$Id: anonym.html,v 1.6 2003/04/18 07:35:54 jakubadamek Exp $
|Slightly updated the info about the wizard, added a warning about two forms in one page to Tips and Tricks.|
|Added the Filler and fillform section.|
|Added tips and tricks based on the FAQ description of the previous anonymous forms|
|Added links to doc/script/show_result.php3|
|Separated from the Reader management document|
This file was created from the DocBook XML source. Please do modifications in the source, not here.
Explains the basic idea, creation and settings of Anonymous forms. The name “anonymous” is in some cases not accurate, as the form is used for reader personal info and the readers must be authorized to edit their own info.
Anonymous forms are similar in function and design to the Add / Edit item page. The main difference is they are placed outside of the AA Control Panel and thus do not provide the AA authorization and have a design of their own.
The most common usage is to allow web readers to suggest new content. After filling the Anonymous form it is sent to the Holding Bin and a Thank you page appears. But you can also allow readers to edit items with the Anonymous form.
Two scripts handle the anonymous forms. The first, filler.php3, stores the info coming from the form into the database. It also validates the data and prooves permissions to edit or update the item. The second, fillform.php3, refills the data into the form shown to the reader. It retrieves the data from database or in some special cases directly from filler.
In the previous AA versions until version 2.4, the process of creating Anonymous forms was very simple: Copy the code of the “Add item” page with only a few necessary changes. But as the form now allows to edit items and to use several options for it, a new wizard was created. This wizard creates the HTML code for a complete form with the SSI include of fillform.php3 necessary to edit items. The resulting form differs depending on whether Anonymous editing is allowed or not.
You may change these settings in the wizard or later in hidden fields:
Table 1. Wizard settings
|err_url||The URL to which the script filler.php3 jumps when some error occurs. It may be the same page on which the form is shown.|
|ok_url||Like err_url, for successful changes.|
|show_result||The URL of a PHP script which receives the results from filler.php3. This allows for a completely free design of how the errors are presented to the user. See below.|
If you are interested to know more about what the form contains, here are some remarks:
If you want to edit items with anonymous forms, first you must allow to choose which item to edit. You can create a view and add a link to the headlines, which links to the anonymous form and contains the parameter my_item_id=_#ITEM_ID_. Another approach is used in Reader management slices, see below.
You must choose the correct setting in Slice Admin - Settings - Allow anonymous editing of items, which is used by the filler.php3 script on an item update request. The options are:
Table 2. Anonymous editing options
|Not allowed||Never allow to update items|
|All items||Always allow|
|Only items posted anonymously||For items posted anonymously, filler always sets the ITEM_FLAG_ANONYMOUS_EDITABLE flag. By choosing this option you allow only items with this flag set to be edited.|
|Only items posted anonymously and not edited in AA||Similar to the previous one, but when you edit the item in the control panel, the flag is cleared and thus the item is no more allowed to be edited anonymously.|
|Authorized by a password field||filler looks for a field of type Password (with Id beginning with password....) and requests the password sent by the user to match. The password may be set on item creation. If the field is not flagged required, an empty password may be used. The new Field Input Type, Field Insert Function and Field Validate Functions “Password and Change Password” provide the usual edit boxes for changing, deleting and entering password, which is stored encrypted. The disadvantage is the password must be sent on every update.|
|Readers, authorized by HTTP auth||This is a special option, useful only for Reader management slices. The username given to the browser on HTTP authentification is looked for in the database. Each reader may edit only his or her personal info.|
It is possible to send images and other files by the form (unlike the anonymous posting in version prior 1.5)
It is possible to set values to a non-displayed field by just adding a hidden field for such a field:
<input type=hidden name="v696d675f6865696768742e2e2e2e2e2e" value="Anonymous author">
Note: This solution is easy and good working in many cases, but it is by no means secure. Any experienced user can change the values of the hidden fields so do not rely on such data. A better solution is to completely omit such fields from the input form and set the default values for the fields in "Admin" -> "Main setting - Fields" -> "Edit" -> "Default". The values are than set directly from the database. This solution is a little bit more secure.
You can disable the standard AA validation by adding a hidden field notvalidate in the form:
<input type=hidden name="notvalidate" value="1">
Each reader has her or his own item in the Reader management slice. Thus the HTTP authentication described above may be used directly to determine which item (reader personal details) to show in the form.
In this case two forms are needed, one being the publicly accessible subscribe form and the second being the HTTP protected “Change personal details” form. Because the fields on both the forms may be the same, you can use one form and include it into two different .shtml pages.
For webs not using Auth we need a way to ensure nobody not only edits but even views the data. This is achieved by assigning a special “Access Code” (see the Reader management documentation) to each reader, which must be added to the URL in order that the data are prefilled. The password authorization described above is than used on item update.
By default, the fillform.php3 script shows standard error messages. They always appear at the place where fillform.php3 is SSI-included in your shtml page.
You may create your own PHP script (see an example in doc/script/show_result.php3) and send its URL as a value of a show_result variable. Add it as a parameter to the fillform.php3 SSI include created by the Wizard, e.g.
An array $result with the results will be sent to the PHP script and you may print appropriate messages, see the example.
The $result array content is created at various places in filler.php3 array. Look there for accurate info. At this moment the messages are:
Table 3. Results from filler.php3
|fatal||Fatal error. Several messages related to the slice, not to the particular item. These errors help on creating the web page.|
|validate||Array with not validated fields, field_id => message, e.g. headline........ => This username is already used created on field validation. You may create your own messages depending on the field_id.|
|permissions||Missing permissions. Depending on the setting for Anonymous editing (see above), this item did not fullfill the requirements.|
|store||Some error in StoreItem. Usually this points to an inner AA error.|
|success||No error. The operation was successfully done. The value is “insert” or “update” (i.e. $result["success"] == "insert" or $result["success"] == "update" in the show results script).|
|email_confirmed||Added by fillform.php3 on Reader management slices: When the reader successfully confirms his or her email by using the URL sent in an email, fillform adds a message “email_confirmed => OK”. This message is added only when the email has not yet been confirmed.|
|unsubscribed||Added by fillform.php3 on Reader management slices: When the reader unsubscribes from Alerts (which is achieved by setting How often to an empty value).|
Discussion: A similar result may be achieved by adding several fields to the form, e.g. fields
err_page[validate][username......]="err_username.shtml" err_page[validate][*]="err_validate.shtml" err_page[*]="err_unrecognized.shtml"
and by creating the .shtml pages with a static message concerning the particular error. The main advantage of this approach is the web administrator may not know PHP. The disadvantage is the necessity of creating many pages but using SSI includes the pages could look only like:
<!--#include file="err_top.shtml"--> The username you entered has already been used. Please try another username. <!--#include file="err_bottom.shtml"-->