 |
||
ADDING EXTRA FIELDS
Definition of a Field
The Item table contains several standard fields that characterize an item: its name and description being the two most important ones. Each field represents a column in the table. Other standard fields store the item owner (the member who added the record), an image, and an associated URL. Using just these few fields Roger can put together a reasonable detail page for a model. However, it is easy to think up other fields that could enhance the overall presentation. Review Foundry allows the webmaster to add as many fields as desired, and offers a range of "field types" that facilitate the integration of the data into the page. A discussion of how to add extra fields (columns) to an existing Review Foundry table is treated in detail in the Review Foundry User Manual. See the section on ADDING COLUMNS TO A TABLE. In this section we see how Roger goes about adding a few fields of different types. In particular, he will add fields to handle the collection of information about the age of the model, her physical location of a model, her likes and dislikes, as well as several fields to handle the incorporation of extra images so that a small thumbnail gallery can be added to the detail page.
Age Field
We start with one of the simplest pieces of information that Roger wants to capture: the age of the model in years. Initially it might be thought that this would involve adding an integer column to the Item table. However, recording an age directly is problematic, because it changes every year. Instead, it is better to record the date of birth of the model, which never changes. The model's age can then be calculated on the fly with a simple date subtraction. Thus, here we consider what is required in order to add a Birth Date field. Because the field is a perfect match for one of the special database column types--in this case the DATE column type--Roger would elect to add a DATE column. To do this, he first selects the "Columns" option of the Review Foundry Database menu, in addition to the name of the table to which the column will be added--in this case, Item. Clicking on the submit button for this menu brings up the Column Properties page for the table, at the bottom of which is a link labeled "Add Column". When this link is clicked on, a form like the following appears (filled out in the way it needs to be to add the proposed column):
|
When the Date of Birth column has been added with a DATE_SELECTABLE form type it will result in a new form element that looks like the following, and which makes specification of a birth date both clear and easy:
|
This suggests unambiguously to the user that the year needs to be of 4-digit format, while the day and month can be selected from drop down menus.
Once new columns have been added to the Item table additional code needs to be added to the public templates in order to display the data. In order to do this correctly Roger will need to understand how the Review Foundry templating system works. In particular, because he wishes to display the age of a model, and not her date of birth, a little fiddling will be necessary within the templates. But THE TEMPLATE-TOOLKIT, the underlying mechanism by which data is translated into HTML in Review Foundry templates, is very powerful, and allows tasks like this to be performed with relative ease. In this case, Roger might add the following code to the relevant template (say item_page_top.ttml or item_page_more.ttml which are used to construct the topmost and subsequent detail pages for an item) in order to display the model's age:
[%# assuming that alias.item_info is passed into the template... %]
[% item = alias.item_info %]
[% year_of_birth = item.date_of_birth.split('-').shift %]
[% USE date %]
[% year_now = date.format(date.now,'%Y') %]
<p><b>Age:</b> [% year_now - year_of_birth %]
What has been done here is to use the date module from Template Toolkit to calculate the current year, and then subtract from it the year in which the model was born to obtain her age. The year of birth is obtained by splitting the date of birth (in the format yyyy-mm-dd) on the delimiter '-', and then taking the first element by shifting it off the resulting stack of numbers.
Note: when dealing with templates, the first step is to locate the template responsible for handling the portion of HTML you intend to affect. To do this, try looking in the HTML source code of the page that your browser is showing. Each public template identifies itself by inserting comments at the top and bottom of the template, such as <!-- begin: item_page_top.ttml --> and <!-- end: item_page_top.ttml -->. So if you are looking at the detail page for an item (a model in the current tutorial) you will discover that the item_page_top.ttml template contains the HTML that Roger would likely want to modify when inserting extra fields for display. The template will have a section of code (near the top) that assigns the passed-in fields to a local variable, such as item in the code shown above. All Roger has to do now is add a conditional statement for displaying the value of the relevant column.
There are a lot of possibilities inherent in the treatment of pulled data when using Template Toolkit to handle the data formatting. Studying the Template Toolkit in order to harness this extra flexibility is entirely optional, of course.
Location Field
Another field commonly attached to personnel pages is the location at which they can be found. So Roger adds a location column, used to record the city and state of each model. For this he uses a VARCHAR column of 255 character maximum (though perhaps 64 characters would be quite sufficent too):
|
When the Location column has been added with a TEXT form type it will result in a new form element that looks like the following:
|
Adding a suitable Template Toolkit tag to the public templates to display the value of the Location field is as simple as this:
[% item = alias.item_info %] Location: [% item.location %]
Note that the VARCHAR column type can be used to record all sorts of characteristics easily captured as short strings of free form text, such as email addresses, favorite quotes, and so on. Longer strings are better suited to the TEXT column type, as discussed in the next section.
Likes/Dislikes Fields
To record the personal likes and dislikes of a model, Roger needs to provide a textarea form input and a TEXT column to store the information, use of which allows up to 64K in character data. The two columns to be added are therefore of the same type as the description column. Here is how the personal_likes column is created:
|
In this case Roger has elected to have the Personal Likes field be optional (the Not Null attribute has not been set) so that the personal likes of a model need not be supplied each time the record for the model is edited. Additionally, Roger has specified a Search Weight of 1 for the field. This means that the field will be indexed, with a weight of 1, and terms appearing in the Personal Likes field will help power the search engine. Thus, if a model likes "eating chocolate by firelight", a search for either of the terms "chocoloate" or "firelight" should bring her up in the results. It is a good idea, however, not to go overboard and index every text column in sight, as search engine indexes take up memory in your database tables. One last note: in specifying that a TEXTAREA form element be used to collect the data, the size of the form element also needs to be specified--in this case, 40 columns and 3 rows (the two numerical terms being separated by a comma in the Form Size/Length attribute).
When the Personal Likes column has been added it results in a new form element that looks like the following:
|
To add a Template Toolkit tag to the public templates to display the value of the Personal Likes field we could do something as simple as the following (though in practice we would likely want to create a separate table for this field and contain the text in a table cell of its own to keep it separated from the Personal Likes: label):
[% item = alias.item_info %] Personal Likes: [% item.personal_likes %]
Image Fields
Last, but not least, are the extra image fields which Roger intends to add in order to support a small gallery of photos for each model. In this scenario Roger wants to add a personal gallery for each model of up to 12 images which will be displayed 6 per row across the page beneath the other model fields, and before any reviews that might also be displayed on the detail page. These images will be clickable thumbnails that pop up the full-size images. Noting that the default setup includes an image field represented by the column named item_image, Roger calls the next image column added item_image_02 and creates it with the following column specifications:
|
The interesting thing to note here is that the image is represented by an INT, or integer, column type. In fact, the actual image, and its thumbnail will not be stored within any table. But the integer value assigned to the image--which is stored in the file system--acts as an identifier for both the image and its thumbnail (if it has one). The integer is actually used as a PRIMARY KEY into the Upload table, so it should be a positive integer. That is why it has been specified as an UNSIGNED (non-negative) integer. Also, to allow any number of images to be added or removed, the field has its Not Null attribute set to No (so that extra images are optional).
For the Form Type, Roger has selected PUBLIC_IMAGE. What this means is that the field will be recognized internally by Review Foundry as one that represents an image, and various operations will be performed to store and then serve up the image. A "public image" is one that is considered to be viewable by anyone perusing the detail pages, regardless of whether or not they happen to be a member of the site.
It is also worth mentioning that the convention used for naming the image columns determines the default order in which they are placed on the page. The default rule is that images are sorted alphabetically on the column names. This is done inside a special template, named item_gallery.ttml, so if Roger wanted more control over how the images (thumbnails actually) were placed on the page, that is the template he would customize. After adding the first such image column he goes back and repeats the process for the columns item_image_03 to item_image_12.
The image columns have now been added, but there is perhaps one thing missing. A caption, or title, for each uploaded image. To add an image title which will appear beneath the thumbnailed image, Roger adds a VARCHAR(32) column of the following type (the length of the string held by the column could be any number up to 255, but 32 is generally enough for a short descriptive title):
|
The choice of the column name is NOT arbitrary. The name of a column that represents the title of an image column MUST be the same as the name of the image column, but with the suffix '_title' appended to the end of it. Thus if item_image_02 is the name of the image column, the corresponding image title column, if it is defined, should be item_image_02_title. The Not Null attribute should be set to No for titles because the images are optional, thus the titles should be as well.
When the Image 2 and Image 2 Title columns have been added they result in new form elements that look like the following (shown in the state after an image has been uploaded):
|
Gallery Presentation
Once extra images are available for presentation, these will automatically be formatted and displayed on the model detail page as tiled thumbnails, complete with an image title if one has been provided. The number of thumbnails displayed per row, and the separation distance between the table cells that contain individual images are configuration variables that can be adjusted on the Browse / Build page of the Configure area. The two variables are browse_item_thumbnails_per_row and browse_item_thumbnail_spacing. If Roger wanted finer control over the formatting of the images he would directly edit the item_gallery.ttml template, which contains the code for tiling the images horizontally. If he wanted to tile them vertically, or add a border to the table cells, or do anything related to the positioning of the thumbnails, then this would be the place to start. Another thing he might want to do is ensure that thumbnails are all scaled to, say, exactly 120 pixels in height. To do that he would consult the Thumbnails page of the Configure area, where thumbnailing options are handled, including the choice of the image manipulation library to be used to scale the images. Possibilities include Image Magick, GD, and the NetPBM executables. A fuller discussion can be found in the User Manual on the Thumbnails page.
Summary
So let's recap. Roger has added extra fields to handle model age, location, likes and dislikes, and 12 extra images. Shown below are the new form elements as they might appear on the edit page for the model Ms Lovely:
|
The final result of Roger's efforts are model pages which look like this one.
Next Section: VIEWING A MODEL
Copyright © 2004 Random Mouse Software. All Rights Reserved.