How to Add Custom Properties

This page is in response to the following question:

Q. [Maxwell - Feb 14, 2008] In the Developers Support section it mentions that I can create variables based on classes provided using JavaScript. Ideally I would like to add a property to the comment class  (e.g. comment.rating) that i could use on both the comment and layout pages, but since I don't have access to the object constructor on the server, I am at a loss.

The classes in EditMe's API are fixed - you can't change these. The reason for this is beyond the scope of this answer, but just take that as an absolute.

So how do you store extra information about a Page, Comment, User, etc? There are many ways, but the outline below shows the pieces and general steps necessary. Depending on what you're doing, you might end up with something quite different. We'll use the example of adding a Rating to Comments.

Prerequisite Note: This article assumes the reader has a thorough understanding of JavaScript, HTML, web programming in general. If you don't know JavaScript, there are thousands of books and web sites detailing this simple, yet powerful, language. Mozilla's JavaScript documentation is an excellent resource. 

1. Editing the Comment Form

First we need to customize our site's Comment form. Many of EditMe's "system" pages can be loaded into your site as an EditMe page that you can edit. You should note that these pages can contain  some complex code, and editing them requires HTML and JavaScript programming skills, as well as a thorough understanding of EditMe's JavaScript API and template language.

To get a system page loaded into your site for customization, just open a ticket at the help desk asking them to make the page you want to edit available to them. Some pages that can be edited this way are the Comment form, Edit Page form, User Management form, Registration form and more. Due to the pain and suffering a user can inflict on their site by editing these without knowing what they're doing, we don't put them there by default.

Once you've got the Comment form loaded up to your site, use your HTML skills to add a set of radio buttons to capture a Rating value when the comment form is submitted. It might look something like this (though you will probably want to make it prettier than this):

<p>Rating: 
<input type="radio" name="rating" value="1"> One 
<input type="radio" name="rating" value="2"> Two 
<input type="radio" name="rating" value="3"> Three 
</p>

Of course, this has to fall within the <form> tag on the Comment page. 

Capturing Comment Events

Here's the somewhat tricky part. You need to handle the comment form being submitted, but this is done by EditMe behind the scenes. What to do? There are two options. First, you could create your own scripted page to handle the comment form submission and change the action of the comment form to point to your scripted page. This might be useful if you want to do something radically different with the comment form than what EditMe does with it. This could be anything, so I won't go into much more detail about it here.

The other option (and what I'll cover here) is to capture Comment events raised by EditMe to do something when a comment is added, edited or deleted on your site. This method has the benefit of letting EditMe do its thing (apply security, and all that) while you just worry about your part.

EditMe Events are detailed in the online help. Read and understand that page before moving on.

Now that you know all about events, you know we need to create a scripted page called EditMeScriptEvents on your site. When a comment is added, we're going to store the rating that was submitted along with it. When a comment is edited, we're going to find that rating value and change it to the new value. And when a comment is deleted, we're going to remove the rating value we stored. But first... how do we store data?

Storing Data 101 

EditMe's "data" object provides a way to store text data of any type. It's deliberately simple, allowing developers to use it in many ways depending on what they might want to do. Think of it as a directory of files... each file has a name and contents. There can't be two files with the same name. You can search the file contents or return filtered lists of file names. You'll see in this example later on that formatting your data keys can be important when you need to retrieve them efficiently later on.

There is a very complete example of using the data object on the Data class help page, so I won't repeat that here. You should review and understand that example before moving on.

Building the Event Handlers

Now that we know how to store data, let's build our EditMeScriptEvents page. The comments here hopefully make this self-explanatory. Note that we've only included the event functions. The rest of a working EditMeScriptEvents page can be found on the Events help page.

function editme_event_comment_create() {
  // get the comment just added
  var p = site.newPage();
  var comment = p.getComment(event_data);
  // add a data entry to store the rating
  var de = data.newEntry();  
  // our key will let us look up ratings by either comment ID or page name
  de.key = 'rating.' + comment.id + '.' + comment.page + '.';
  // store the rating submitted with the comment form
  de.value = server.request('rating');
  // save our data entry
  de.save();
}
function editme_event_comment_update() {
  // get the comment just updated
  var p = site.newPage();
  var comment = p.getComment(event_data);
  // get or create the corresponding data entry
  var key = 'rating.' + comment.id + '.' + comment.page + '.';
  var de = data.get(key);
  if (de==null) {
    de = data.newEntry();
    de.key = key;    
  }
  // store the value and save
  de.value = server.request('rating');
  de.save();
}
function editme_event_comment_delete() {
  // delete the entry for the comment, if there is one
  var ratings = data.getEntries('rating.' + event_data + '.', '');
  if (ratings.length > 0) {
    ratings[0].destroy(); // there should be only one
  }
}

Save that page and you're good to go. Now your comment form shows a place to enter a rating, and your event handlers store the rating for you. All that's left to do is display the rating for each comment on your pages. This can be done in the layout.

Updating the Layout

Your site's layout is responsible for listing comments. Open up the Layouts screen for your site, edit the current default layout, and find the section that lists the comments. Wherever you want to display the rating for each comment inside the foreach loop that displays the comments, use a function that we'll create called getRating, like this:

<p editme="text getRating(comment.id)"></p> 

So, now we have to build the getRating() function. We were careful to include the page name associated with the comment in the key when we saved the rating data in our event handlers. That allows us to get all the ratings for a given page. Otherwise, we'd have to call data.get() for every single comment on the page, which would make pages with lots of comments pretty sluggish. So here's code that gets all the ratings for the page (done only once per page view). Then we define the getRating function to search through the ratings and find the one we're looking for.

var ratings = data.getEntries('rating.', '.'+page.name+'.');
function getRating(id) {
  for (var i in ratings) {
    var de = ratings[i];
    var parts = de.key.split('.');
    var thisId = parts[1];
    if (thisId == id) return de.value;
  }
  return ''; // didn't find a rating
}

Done, and done!

Comments