How to Customize Ratings and Reviews

Tags: Properties
As described in How to put Ratings or Reviews on your Things, it is very easy to use the built-in Rating and Review Properties to say how much you like something. These built-ins are just the lowest-common-denominator, though: they work nicely, but are very hard-coded. If you want to do things differently, you need to build your own custom versions; at the moment, that's rather complicated.
This Recipe assumes that you are fully comfortable with Querki -- it doesn't do as much hand-holding with the basics.

Creating a Custom Rating Property

Ratings are much simpler than Reviews, so customizing them isn't as hard, but it's less-often necessary. Create your own Rating Property if you want to change the number of stars, or change the labels on those stars.
  • Edit your Model, to create a new Property of "Rating Type". (I'll refer to it as My Rating.) Say Done to finish there.
  • Use Actions -> Show All Properties to find My Rating, and edit that.
  • In My Rating, add the Chart Labels property. Fill that in with the labels you want on the stars: the number of labels determines the number of stars that will be shown.
  • In My Rating, create a new Property of type "Rating Summarizer". (I'll refer to that as My Rating Summary.)
  • In My Rating, add the Property "Is User Value Property", and make sure the box is checked. Say Done to finish there.
That should do it -- you now have a customized My Rating property, with the right number of stars and the right label. You can use it as normal (remember to say [[My Rating._edit]] somewhere to display it so folks can give their opinions), but remember to use the names you have used for your property, and for the matching summary property.

Creating a Custom Review Property

This is where it gets really complicated. But you can do almost anything you want: in exchange for all the work, you get a lot of control and power.
  • Create a Model for your Review Property. (I'll refer to it as "My Review Model".)
  • Let's assume that you want a Rating as part of that. Create a new Property of "Rating Type". (I'll refer to it as My Rating.)
  • Make sure the Is a Model flag is checked.
  • Add whatever other properties you like. The built-in Review Model has a Large Text Property for the comments box, but in theory you can use any sort of Querki property.
  • If you want to customize what the Review looks like when you edit it, add the Instance Edit View property. This is similar to the usual Default View -- it is exactly what gets displayed when you edit a Review. It should typically contain [[My Rating._edit]] as well as _edit commands for all of the other interesting properties, and whatever layout code you like.
  • Say Done when that looks right.
  • Edit My Review Model again. Add the Instance Properties property, and list all of the properties that you want folks to be able to edit. (Generally, all the ones you added.) Say Done again.
  • Use Actions -> Show All Properties to find My Rating, and edit that.
  • In My Rating, if you want to use different labels, or a different number of stars than the default, add the Chart Labels property. Fill that in with the labels you want on the stars: the number of labels determines the number of stars that will be shown.
  • Edit the Model that you actually want to review. Create a new Property, "Based on a Model", and select My Review Model. (I'll refer to this as My Review.) As usual, say [[My Review._edit]] somewhere in the Default View, to display it for editing.
  • Use Actions -> Show All Properties to find My Review, and edit that.
  • In My Review, add the Property "Is User Value Property", and make sure the box is checked.
  • In My Review, create a new Property of type "Rating Summarizer". (I'll refer to that as My Rating Summary.) Say Done to get out of the Editor.
  • Edit My Review again. Add the "Summary Link" property, and point it to My Rating Summary.
  • Edit the My Rating Summary property. Add the "Summarizes" property to that, and point it to My Rating. (Not My Review. This step is necessary because you're building a more complicated type -- you have to tell the Summarizer how to find the actual Rating property that it is keeping track of.)
At this point, you should have a working Review Property that you can customize to your heart's content. It takes a few minutes, but isn't too awful when you get used to it. In the long run, if there is user demand, we might add a wizard to make this process easier; please speak up if this would be important to you.

Displaying a Rating's Label somewhere else

When you are editing a Rating, each star has a distinct label. (Otherwise known as its "hint".) By default, that label shows as a hover: when you pause for a second over the star, the label appears. This is easy to create, but doesn't provide quite immediate feedback. As an alternative, you can show the label immediately somewhere else, like this.
  • Edit your Model.
  • Somewhere in the display (typically the Default View), add a div with a unique ID: <div id="my-hint-target"><div>. Make sure it has a fixed size, and is big enough to hold all of the possible hints.
  • Tweak the editing of the Rating, like this: [[Rating._edit -> _data(""target"", ""my-hint-target"")]]. This tells Querki that the Rating's "target" -- the place to show the hint -- is the div named "my-hint-target".
Things get a bit more complicated if you want to do this with a Review. In this case, you will have to build a custom Review Property, as described above. Usually, you want to put the hint target somewhere in the Instance Edit View of the Review Model. Keep in mind that the id of the hint target needs to be unique on this page: if you are creating multiple Review or Rating Properties, you will need differently-named hint targets for each.
Back to Recipes