User Generated Content
1. Introduction
This guide will walk you through installing and configuring a script to allow user registration and modification of CMS-controlled assets. It assumes that you are comfortable with Cascade and XML. Experience with PHP is also useful, but not necessary for this guide. Using this guide, you will be able to allow users on your live site to create and manage data-definition-based pages within the CMS.
The included script, listing.php, allows a user to register an account, login, edit their page, change their password, and recover their password. Once a user registers an account, the script will create both a user account and a page in the CMS. From this point on, the page in the CMS will be associated with that account. When a user logs in, the script will allow the user to change the CMS page via fields in the data definition. The user may also change the password on the account or recover it via email.
2. Components
The script setup is divided among several components. The first is the listing.php script itself, which will be placed into a text block inside the CMS. This text block will be assigned to a page, creating a template for the script. The Form Builder data definition will be used to create a form which will be presented to the user (through a form.xml file). A data definition inside of Cascade will mirror this form. A file on the live server, users.xml will contain the database of user info.
3. The Script and Supporting Files
listing.php requires two support files. The first is the config file, listing-config.php and the second is the user database file listing-users.php. These files should be placed on the production server, though not within the document root (or you will risk exposing your client's login information to everyone). Once you have chosen a location for these files, update listing.php so that the $config_file and $users_file variables reflect the path to each file respectively.
Installing the script in the CMS is as simple as creating a text block containing the script. Now create a page, and assign the new text block to the default region of that page. This allows you to wrap the output of your script in a template. When you are ready to use the script, simply publish this page and access it. The PHP code for the script should be rendered inline in the page content.
4. The Data Definition
The listings that you want to create, must have a data-definition associated with them. The fields in this data-definition will be a superset of the fields that you will allow users to edit with the script. The identifiers that you use in your data-definition will correspond to the values that you assign to the elements of your form.
5. Building the form.xml File
Create a data definition by copying contents of the included listing-form_buider.xml into the CMS. Assign this data definition to a page titled form. Using the data definition you can build the form which the users of your script will see. Adding screens, seperates the form elements across different pages (effectively splitting up long registration processes). Don't worry about adding items for a username or a password, as the script will automatically include that on the first page of the registration process. Be sure to have this page publish to an XML file and that the $form_file variable in listing.php is the path to the published file.
6. The Configuration File
The configuration file is fairly complex, so it is recommended that you use the example provided and change it to suit your needs. Almost all of the script interface is defined within the configuration file. The file itself is divided into several sections: login, cms, mailer, strings and templates.
The login section simply contains the username, password, and hostname that the script uses to log in the Cascade instance you will be using.
Most of the templates are self-explanatory. pages contains high level layout information about page structure (as well as HTML) given certain script states. form includes templates for various form elements and situations (ex. editing versus registration). menu contains the various menus that will be displayed to the user. error is the format for displaying error messages to the user.
Templates often use various keywords will are replaced by the script. An quick overview of these parameters is included below.
| {$me} | The script path | |
| {$form_items} | Form elements derived from the form.xml file | |
| {$screen} | The id of the current screen in the form | |
| {$error} | The current error message | |
| {$field-description} | The description of the current field (in an error message) | |
| {$description} | The description of the current field (in a form element) | |
| {$value} | The recorded value of the current field (in a form element) | |
| {$name} | The name of the current field (in a form element) | |
| {$input} | Replaced with the form element matching the correct type of input | |
| {$opt_value} | The value of a particular option of a form element with multiple options | |
| {$opt_description} | The description of a particular option of a form element with multiple options | |
| {$username} | The user's (or previously entered) username | |
| {$password} | The user's (or previously entered) password | |
| {$email} | The user's (or previously entered) email address | |
| {$menu} | The menu of actions | |
| {$errors} | All errors associated with this page | |
| {$form} | A form (generated from form.xml for entering data. |
While these parameters sometimes work in various templates, they generally work only in the situations they are used in the config file. For instance, there is no meaning when {$form_items} inside of an error message (it will actually be processed as literal text). On the other hand, the {$username} parameter works in almost all situations.
Similar to the templates are the strings. These constants are the messages that the script will deliver to the user in various situations. Their uses are generally straightforward; see the example file.
The mailer settings control the script's use of email delivery. Ensure that your SMTP server allows your production server to relay messages, otherwise message delivery will fail. Note the use of a few parameters in the message body.
The CMS settings determine some important aspects of the script, including the path within the CMS to place new listings ( review_path) and the path where processed listings are stored ( listings_path). This allows a CMS user to look over new listings before they are used in the CMS (a workflow may even be initiated with some simple changes to the script). data_definition, configuration_set, metadata_set should all be paths in the CMS and refer to the settings on listing pages. One final field, name_listing_after should give the field name (in the data definition and form.xml) that will be used for the new page's name prefix.
Files
- user-generated-content-PHP.zip
This zip file contains all the necessary PHP scripts and XML. - users.xml
This is an example XML file with the user management information. - listings-php.txt
This is the main PHP scripts that displays and processes the form. - listing-form_builder.xml
This is the data definition to visually build a form. - listing-data_definition.xml
This is the data definition for the form on the live site. - listing-config.xml
This is the XML configuration file that drives the script. - form.xml
This is the XML output from the content data definition.