Rate My AnythingDeveloper
Over the next few weeks, we’ll be offering versions of Rate My Teachers and Restaurant Reviews which will enable you to set them up to review anything in a snap without going into the code – video games, movies, candy bars, the new fall television line-up, or even your siblings.
In the meantime, if you want to customize or configure your current clone of Rate My Teachers for any of these broader purposes, we’d like to offer two options:
- If you don’t know HTML or PHP, drop us an email at firstname.lastname@example.org and let us know what you’d like customized. We’ll create something specific for you to clone and run as your own.
- If you are a bit more adventurous or at least comfortable in HTML or PHP, we’ll walk you through here in this post what you’ll need to change.
In either case, our goal is to get you up and running as quickly as possible with your new app in the form you want it.
With that in mind, there are three broad steps to customizing Rate My Teachers after cloning it:
- Editing the config.php file
- Editing the app’s HTML templates
- Editing the apps XNHTML files
Step One: Edit config.php
The first step in customizing Rate My Teachers after cloning is to tell your cloned app about what it’s supposed to review: video games, movies, candy bars, etc. Let’s say your app is for reviewing video games. You need to decide what characteristics a user can input about a particular video game and in their review of a particular game.
In the Rate My Teachers app, the characteristics of a teacher are:
- The teacher’s name
- The teacher’s department
The characteristics of a review are:
- The numerical rating
- The courses that the reviewer took from the teacher
- The text of the review
Some specific changes in the config.php file tell the app about your new kind of content. Here are the things you need to change:
- change the
$subjectTypevariable to the content type of your new thing that’s to be reviewed, e.g. “VideoGame” or “Movie” — the “subject” of the app. This is the type of the content object that holds each game or movie, so it should just be letters – no spaces or punctuation.
- Change the
$subjectDescriptionvariable to a human-readable description of the thing to be reviewed, e.g. “Video Game” or “Movie”. This is displayed in various places in the app.
- Change the
$reviewTypevariable to the content type of the reviews people will input. A handy convention is to just make this the value of $subjectType followed by the word “Review”, such as “VideoGameReview” or “MovieReview”. Just letters here, too.
- If you want, change the
$reviewDescriptionvariable to a human-readable description of the review. If you leave this as is (set to “Review”) you’ll be just fine.
Next, you have to change the parts of config.php that actually describe the thing being reviewed and the review itself.
- First, change the “Teacher” class to have the same name as the value you set
$subjectTypeto (e.g. “VideoGame” or “Movie”)
- Then, adjust the public variables in the class so that there’s one for each piece of data you want someone to input about a thing being reviewed. For a video game, you might want to have the name of the game and the category the game belongs in (e.g. “First person shooter”, “Strategy”). In that case, leave the
$titlevariable as-is (but adjust the comment so it doesn’t talk about teachers), and change the name of the
- If you want to add additional things for users to input, add additional public variables in the class. The only restriction on the variables names (aside from PHP’s regular variable name rules) is that they shouldn’t begin with an underscore.
By default, each field will be optional for users to input and will be treated as a string. You want to change that, you can put some code in the
__construct() method in the class. There are three arrays whose values you can set in
__construct() to affect the behavior of the fields.
The first is
$this->_rules. This sets some restrictions on
allowable values for different fields. The built-in rules are
“required”, “minlength”, and “maxlength”. The required rule makes it
so that a value for the field must be entered. The minlength rule sets
a minimum length for the user-supplied value. The maxlength rule sets
a maximum length for the user-supplied value.
To set a required rule on a field called title add an element to
_rules like this:
$this->_rules['title'] = array('required');
The minlength and maxlength rules each require an additional argument:
the minimum or maximum length allowed, respectively. Add them to the
_rules array like this:
$this->_rules['title'] = array(array('minlength',10));
To make an element required *and* have a minimum length of 10, do this:
$this->_rules['title'] = array('required', array('minlength',10));
The second special array is
$this->_types. This array lets you ensure that a field will be treated as a number instead of a string. For example, to set a rating field to be a number, do:
$this->_types['rating'] = XN_Attribute::NUMBER;
The third special array is
$this->_labels. This holds labels for
fields that are used in error messages for built-in rules. If you want
the error message to identify the property by a different string then
the property name. Put that string in
_labels. For example, if you’re
storing the name of a VideoGame in its “title” system
attribute for simplicity, do this to have the error message refer to
the field as “name” instead of “title”:
$this->_labels['title'] = 'Name';
After changing the Teacher class into one that accurately describes the thing your app will review, you next need to change the TeacherReview class into one that describes the reviews that users will add.
First, change the name of the TeacherReview class to the value to which you set
$reviewType, such as VideoGameReview or MovieReview. Then, adjust the variables in the class and (possibly) the _rules, _types, and _labels array.
You have one last task in config.php. The app is set up to treat one field in the subject content object specially. For teachers, it’s “department”. For video games, it could be “category”. The map and list pages in the app display views of the content grouped by this “container” field. Change the line in the Config class that sets the
$container variable to “department” so that
$container is set to whatever field name is appropriate for your subject class.
Step Two: Edit HTML templates
The templates that the app uses to display HTML pages are all in the app’s html subdirectory. Some of these templates need to be adjusted to account for the new and changed fields in your two kinds of content objects (the “subject” and the review).
- formAdd.php is used to display the form for adding a subject. By default, it displays fields for entering a value for the “title” field in your subject and whatever field is designated as a container. If you’ve added additional fields to the subject content object, add new form elements to the form for each field. For example, if you’re subject is video games and you’ve put a $year field in your VideoGame class so users can enter what year the game was released, you can add the following PHP and HTML to the form:
<dt><?php echo Config::$subjectDescription ?>'s Year: </dt> <dd><?php echo $form->text(Config::$subjectType.':year','class="input-field"') ?></dd>
The code uses variables from the Config class so that you don’t have to embed “video game” or “teacher” or whatever in your forms. The important thing to ensure is that the part of the form field name after
Config::$subjectTypematches the field name you’ve defined in the subject class. So if the variable name in the subject class is
$year, then the form field name should be
Config::$subjectType.':year'. If the variable name in the subject class is
$flavor, then the form field name would be
$formPHP variable is an instance of the XNC_Form class, which helps out with printing form elements and default values. (The Ning Developer Documentation has more information about XNC_Form.
- formReviewPart.php is the file that prints the form elements for entering an individual review. There should be one form field here for each field in the review class. The names of the form fields should follow the same rules about corresponding to the variable names in the review class. For example, if you’ve got a variable in your VideoGameReview class called $difficulty for a user to enter how hard they found the game, you could have this corresponding code in formReviewPart.php:
<dt>How hard was this <?php echo strtolower(Config::$subjectDescription) ?>:</dt> <dd><?php echo $form->text(Config::$reviewType.':difficulty','class="input-field"') ?></dd>
- index.php: This file just needs a tiny change at the top. Change “All Teachers” to what’s appropriate for your content: such as “All Video Games”, “All Episode Synopses”, etc.
- reviewTableHeader.php: This file prints out the header for a table of reviews. Adjust the text in table column headers to match what users enter for your reviews. You don’t need to adjust the CSS style names used. (You can if you want, but then make sure to adjust the names in xn_default.css as well.)
- review.php: This file prints out the HTML for an indivdual review. It uses the
$stylevariable to print out slightly different things in different circumstances. (The page devoted to an indvidual subject, the page listing all of a particular user’s reviews, etc.) The bit to change is at the bottom — instead of a table cell for courses, the file should display table cells for the fields actually in your review class. Make sure the number of table cells match the number of table header cells you have in reviewTableHeader.php.
- subjectTable.php: This file prints out the header for a table of subjects. Similar to how you had to edit the review table header, adjust the HTML in this file so that the column names are appropriate for your subject class.
- subject.php: This file prints out HTML for an individual subject. It uses the
$stylevariable print out slightly different things in different circumstances. If you’ve added additional fields to the subject class (aside from title and the container field, add bits of code to this file to print out those fields’ values. To print the value of a field called year do:
<?php echo $subject->my->h('year'); ?>
Step 3: Adjust XNHTML files
Aside from config.php and the HTML templates, you also need to adjust three XNHTML files so they’re aware of your new kind of content. These files can’t access the info in config.php, so they need to be explicitly edited to contain new information.
The first is xn_header.view, which contains the code for your page header. Change the references to “All Teachers” and “Add a Teacher” in this file to references that are appropriate for your app.
Next, are the two files that control how your content appears on the pivot pages. Rename xn_pivot.Teacher.view to have your subject class name in the file name, e.g. xn_pivot.VideoGame.view or xn_pivot.Movie.view. Rename xn_pivot.TeacherReview.view to have your review class name in the file name, e.g. xn_pivot.VideoGameReview.view or xn_pivot.MovieReview.view.
Last, edit each of these files so that they display the correct fields for your content. In whatever you’ve renamed xn_pivot.Teacher.view to, change references to “department” to the correct container field name for your app. (Not the word “container,” but the actual field name you’re using as a container.) You can also add additional code to display additional fields. In XNHTML, to print the value fo a field called year, do:
In the pivot viewer file for your review content objects, you can also add additional code to display any fields you’ve added to the review aside from rating and review.
There is some more in-depth info about the things you can do inside your subject and review classes in the CLONEME.txt file inside the app. Also, keep in mind that the original Rate My Teachers app was made by cloning the app “Restaurant Reviews” and following exactly the process outlined in this post. So you can also take a look inside RestaurantReviews — at its config.php, HTML templates, and .view files — to get a look at another setup for subjects and reviews.
The README.html file in the app also has some more details on the file structure of the app and which file does what.
If all of this file editing and treading carefully around the bucket of punctuation that can make or break PHP has you a bit overwhelmed, you’re not alone. That’s why, as we mentioned, we’re hard at work at some additional apps and customization methods that will make the whole thing much, much easier. Soon you’ll be able to set up your own app to review whatever you want without writing a line of code.