 |
||
ADDING EXTRA FIELDS
Definition of a Field
The topic of discussion in this section is member fields. In particular, how to go about adding new member fields to the default ones available at installation. Once again, this discussion borrows from another tutorial--namely, How To Create An Adult Review Site, where in addition to the re-iterated discussion on image fields found in the current tutorial, details were presented on how to go about adding Age, Location, and Likes/Dislikes fields. Here we consider how to add fields that can be represented as grouped selections of either independent or mutually compatible choices. For instance, the selection of an artist's favorite artistic style boils down to a choice between independent alternatives, whereas the selection of most commonly used (artistic) media might mean choosing 3 possibilities from a group of 10 (say, oil, acrylic, and charcoal).
In the same way that the Item table contains several standard fields that characterize an item, the Member table has corresponding standard fields to characterize each member: name and full_bio being the two most important ones. Each field represents a column in the table. Other standard fields include the member avatar_image (actually a foreign key into another table that stores information about the associated image), a member_image (another foreign key), and a url for a member homepage. But like most webmasters, Luke has ideas for additional fields he wants to put in. Not all of them need to appear on the member detail pages, but some might be appropriate there. This also applies to the Member Profile page associated with an artist--in order for added fields to appear, Template Toolkit tags need to be explicitly added to handle them. Review Foundry will allow Luke to add as many fields as desired, and offers a range of "field types" that facilitate the integration of 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.
Media Field (SET column)
As an example of how to add a field that allows members to assign multiple values in response to a single question about themselves, we suppose that Luke has decided to add a media column. When an artist edits their Member Profile they will have the option of specifying which media they work with. After he has set it up, Luke will have the artists activate elements from a series of checkboxes. Alternatively he could arrange for a multiple select form element to appear and have the artists select multiple media by holding down the control button while selecting from the media options. Either implementation is possible, but from the perspective of a member, checkboxes are probably easier to deal with. Compared to plain text fields, we will set that our multiple-valued field adds a little more complexity to the overall task of integrating the data into the page. Not a lot, but it does serve to demonstrate how knowledge of the Template Tookit can help in the design of your pages.
To get started, Luke first goes to the Database control panel. On the left of the page appears a pair of drop down menus. The first specifies the table that should be acted upon. Luke selects the Member table. The other menu is used to select an action. In this case, because the aim is to add a column, Luke selects the "Columns" option. 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 (show below filled out in the way it needs to be to add the proposed column--perform a scroll on the textarea form elements to see the full list of options being specified):
|
Notice that all of the possible media values are supplied as a newline-delimited list. In fact there are two such lists: the first specifies the actual values stored in the SET column that is to be created, while the second list represents the values shown in the form element used to collect the values. The second list is the human-friendly one, and while the first list could simply be numeric values, the strategy shown here is to use lowercase versions of the strings supplied in the second list. This might not be the best strategy to use, for reasons that we will see below (making the two lists identical is perhaps the simplist and most efficient way of doing things). But at the risk of adding a little extra complexity to the task, we will just make the stored values the lowercased versions of the form values and see what comes out it it. Also note that the Not Null attribute has been set to No. This is done so that an artist can choose to ignore the media field if they like. Had the Not Null attribute been set to Yes the artist would be required to specify at least one media value.
When the Media column has been added with a CHECKBOX form type it will result in a new form element that looks like the following:
|
While this new form element automatically appears on the Edit Page for the Member Profile, the collected media values will NOT apear on the displayed Member Profile until suitable Template Toolkit tags have been added. The simplest addition to the member_data.ttml template, which formats part of the Member Profile page would be something like this (slotted into the existing table found in that template--anywhere AFTER the email field the following code should work fine):
[%# this table row would appear
in the PERSONAL INFORMATION SECTION of member_data.ttml %]
[% column = member_def.cols.media %]
<tr><td align="right"
style="background: [% cell_dark %];
border-right: 1px solid [% border_color %]" nowrap>
<b><!-- setfont_base(+0) -->
[% column.form_display %]:
<!-- setfont_end --></b>
</td>
<td colspan="2" style="background: [% cell_pale %]">
<!-- setfont_base(+0) -->
[% member.media || unknown %]
<!-- setfont_end -->
</td></tr>
So what is going on here? Besides the HTML for laying out the data within table cells, and the tags for specifying the font size/family/color (this is the setfont stuff seen above), the essential thing going on here is that the column attributes of the media field are captured in the [% column %] variable, from which we pull out the public name by which the column is known, i.e. [% column.form_display %]. Then we grab the actual column value, available as [% member.media %] (the unknown variable seen above is used when no values have been selected, and is usually translated into the empty string '').
There is one caveat when dealing with SET columns, and that is the column value is represented as a set of component values separated by a single comma and NO whitespace. So if we want "acrylic, watercolor" to appear instead of "acrylic,watercolor" we are going to have to reformat the string with some Template Toolkit magic:
[%# instead of this code... %]
[% member.media || unknown %]
[%# we use this... %]
[% UNLESS member.media %]
[% unknown %]
[% ELSE %]
[% member.media.split(',').join(', ') %]
[% END %]
All that has been done is to split the original string on the comma delimiter, and then rejoin it with a comma and a space as the delimiter. In Template Toolkit the dot operator . seen between elements is used to deference data structures and to invoke methods. So the operations carried out on the [% member %] HASH are: get the string value stored in the HASH element keyed by the string media, then split that string on the comma, then join the resulting component values with a new delimiter made up from a comma and the space character.
And then there is the question of whether or not we have actually presented the data we intended to. After all, what has been extracted and presented is the string value stored in the column, whereas very possibly it is the corresponding form values that we want to show instead. That is to say, "Acrylic, Watercolor" rather than "acrylic, watercolor". If you get into the habit of making your SET column component values the same as your form values then the problem is already solved. You will immediately extract "Acrylic, Watercolor". If not, more work will be required to get the form values onto the page. However it is not too difficult. The key is understanding a little about the [% member_def %] variable which represents a HASH of all column attributes associated with the Member table. Without describing this HASH in detail we'll simply note that one element contains an ARRAY of possible SET components for the media column, while another contains the corresponding form values. These are in one to one correspondence (occupy the same position in their respective ARRAY), so the form values can be inferred like this:
[%# show the FORM VALUES instead... %]
[% UNLESS member.media %]
[% unknown %]
[% ELSE %]
[% media_form_values = [] %]
[% FOREACH media_component = member.media.split(',') %]
[%# find the position in the values array where this component occurs %]
[% index = -1 %]
[% FOREACH component = member_def.cols.media.values %]
[% index = index + 1 %]
[% NEXT UNLESS component == media_component %]
[%# now we know where the corresponding component is in
the form_values array, so store it in a separate array
%]
[% media_form_value = member_def.cols.media.form_values.$index %]
[% media_form_values.push(media_form_value) %]
[% END %]
[% END %]
[%# given the array of matching form values, join them with a comma and space %]
[% media_form_values.join(', ') %]
[% END %]
Obviously that's a lot more work, so you might want to get into the habit of making your SET values the same as your form values. But if you find, for whatever reason, that you want to store a different value than what is shown on the form, then you can always use a method similar to the above to acheive the desired result. In that case, study the Template Toolkit for the methods you can use to manipulate the data, and perhaps look into the way that the fields are represented by definition files in Review Foundry, because there is a lot of information in these files and it is generally accessible when it needs to be--in this instance, in the variable [% member_def %].
Favorite Period Field (ENUM column)
This may be a slightly contrived example of a field that represents a list of mutually exclusive alternatives from which a single value can be selected by the member artist. This kind of field is useful whenever the Review Foundry webmaster wants to offer a small list of possible choices as either a drop down SELECT menu or as a series of RADIO buttons. In this example we suppose that Luke wants to offer a SELECT menu from which each artist can (optionally) select their favorite artistic period. This time the column should be set up as an ENUM type:
|
As can be seen, setting up an ENUM column is very similar to the process for setting up a SET column. Both involve 2 lists of values: those that are stored, and those that appear in form elements (though, as pointed out earlier, you may wish to make these 2 lists identical). The primary difference is in the presentation of the form element used to collect the value for the ENUM column: it is single-valued. Because Luke has chosen to represent the form element as a drop-down SELECT menu it will appear something like this on the Edit Page for the Member Profile (because the field is optional the default selection is the NULL field, so expand the menu to see the list):
|
Once again the addition of a table row to the member_data.ttml template allows the Favorite Period field to show within a Member Profile:
[%# this table row would appear in the PERSONAL INFORMATION SECTION of member_data.ttml %] [% column = member_def.cols.favorite_period %] <tr><td align="right" style="background: [% cell_dark %]; border-right: 1px solid [% border_color %]" nowrap> <b><!-- setfont_base(+0) --> [% column.form_display %]: <!-- setfont_end --></b> </td> <td colspan="2" style="background: [% cell_pale %]"> <!-- setfont_base(+0) --> [% member.favorite_period || unknown %] <!-- setfont_end --> </td></tr>
If our stored ENUM values are the same as those that appear in the drop down SELECT element used to collect the data, we are done. If not, and we want to substitute the form value instead (say, "Baroque" rather than "baroque") we can resort to the more elaborate mapping from the values array to the form_values array:
[%# show the FORM VALUE instead... %] [% UNLESS member.favorite_period %] [% unknown %] [% ELSE %] [% favorite_period_form_value = '' %] [%# we use the column attributes twice, so let's shorten the expressions by referencing the attributes like this... %] [% attributes = member_def.cols.favorite_period %] [%# find the position in the values array where this value occurs %] [% index = -1 %] [% FOREACH value = attributes.values %] [% index = index + 1 %] [% NEXT UNLESS value == member.favorite_period %] [%# now we know where the value occurs in the form_values array, so pull it out %] [% favorite_period_form_value = attributes.form_values.$index %] [% END %] [%# given the relevant form value, display it %] [% favorite_period_form_value %] [% END %]
Image Fields
Last, but not least, are the extra image fields which Luke intends to add in order to support a small gallery of images for each artist. In this scenario Luke wants to add a personal gallery for each artist of up to 12 images which will be displayed 6 per row across the page beneath the other artist 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 member_image, Luke calls the next image column added member_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, Luke 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 member_gallery.ttml, so if Luke 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 member_image_03 to member_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, Luke 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 member_image_02 is the name of the image column, the corresponding image title column, if it is defined, should be member_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_member_thumbnails_per_row and browse_member_thumbnail_spacing. If Luke wanted finer control over the formatting of the images he would directly edit the member_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. Luke has added extra fields to handle Media and Favorite Period, as well as 12 extra Images. Shown below are the new form elements as they might appear on the edit page for the artist rlucci:
|
The final result of Luke's efforts are artist pages which look like this one.
Next Section: VIEWING A MEMBER
Copyright © 2004 Random Mouse Software. All Rights Reserved.