Previous Entry Share Next Entry
Release 0.8 -- Ratings, Reviews and User Values
jducoeur wrote in querki_project
This long-awaited release (three weeks -- an eternity for Querki) is actually a hair premature: I haven't quite finished every nuance of the new features. But we found some critical permissions bugs over the past day, so I decided to put out the release now to deal with them. (No information was accidentally revealed; the problem was that some folks couldn't see things they should have been able to.)

This is a big one; hence the bump to the major version number. As always for major releases, this one features the addition of an important new feature: User Values.

To understand User Values, it's easiest to start with what they enable. There are two new standard System Properties that you can add to your Models: Rating and Review. Rating allows you to give a simple 1-5 star score to a Thing; Review is a Model Type that combines a Rating with a comment field.

What makes both of these cool is that, unlike ordinary Properties, *each user* is allowed to give their individual Ratings and Reviews. That's what a User Value Property is -- a Property with the magic Is User Value Property flag, declaring that each user gets to give their own value for this Property.

On top of that, there is now a standard concept of User Value Summaries. This gets kind of complex, but the gist is that you can link a User Value Property to a Summary Property that keeps track of the totals associated with it. For now, there is one standard Summary Property: the Rating and Review Properties point to the Rating Summary, which totals up all of the Ratings and Reviews on a Thing. If you say [[Rating Summary]] on a Thing that has a Rating or Review, it shows a detailed histogram of all of those values; if you say [[Rating Summary -> _average]], it shows the average value as stars, with the exact number next to that.

If you are a logged-in Querki user (and a member of the Alpha Sandbox Space, which most of you are -- feel free to ask for access if you're not), you can see this in action by going to the Rateable or Reviewable Things that I just created: you can add your own rating, refresh the page and see the average and histogram updated with your value.

There is also a new Permission associated with User Values, which is of course called Who Can Have User Values. This lets you specify exactly who is allowed to supply Ratings, Reviews, and so on. Note that you can't specify this on a per-Property basis, but as usual you can apply it on individual Things, on Models (to set it for all of their Instances), and on the Space (to apply it to everything). By default, all Members are allowed to set User Values, which I believe is most often going to be the right answer. I *may* be willing to change this default to Public if there is an outcry for that, but am going to be cautious about that, since it is a small potential spam vector.

There is one more important sub-feature yet to come: a mechanism allowing you to display, examine and process *all* of the User Values in detail. That'll be showing up in the next few days.

I recommend that, if possible, you just use the built-in Rating and Review Properties: they are ready to roll out of the box, and good enough for most purposes. However, if you want to get into the nuts and bolts and build your own User Value Property, here are a few more technical details. (Feel free to ignore this section.)

As mentioned above, you make a Property into a User Value Property simply by adding the Is User Value Property flag. You should be able to do this on any Property in theory; it definitely works on Model Types, so it can get pretty complex.

The Summary concept is highly generalized, but also pretty hard-coded at the moment. The only type of Summary currently available is the Rating Summarizer, which specifically knows how to work with Ratings and Reviews. But conceptually, we could add many more kinds of Summarizers. The key thing is that, if you want to look at the *statistics* of the User Values of a Thing, you should use a Summarizer. This mostly for system efficiency, frankly: loading all of the User Values is slow and inefficient, so the Summarizer provides a window into the statistics that lives on the Thing itself. If you find that you really want more kinds of Summarizers, talk to me -- I'm open to the idea, and wouldn't mind making it more fully-baked.

For now, though, I'm focused on Ratings and Reviews, which are the one form of User Values that I think are going to be really commonly useful. The built-ins will work most of the time, but here's how to roll your own if, for instance, you need *multiple* Ratings on a Thing. For now, this is *extremely* clunky; we'll provide some UI gloss eventually, sooner if folks need it more often. (I've allowed it to stay clunky for now because I *think* it's going to be a bit unusual.)

First, create your Model, and create a new Property of Rating Type. (Or Review Type, as you prefer -- they work very similarly.) Also create a new Property of Rating Summarizer Type. Then say Done in your Model, go to Actions -> Show all Properties, select your newly-created Property, and edit it. Add the Is User Value Property meta-property to that, and make sure it is checked. Also add the Summary Link meta-Property, and point that to the new Summarizer Property that you created before.

While you're at it: you can also set the Chart Labels meta-Property on your Rating or Review Type Property. This is a list of Plain Text fields, and is the *label* of each star. By default, they are Poor, Fair, Good, Great and Excellent, but you can set them to whatever you like. The number of labels determines the number of stars that will be shown.

Final tweak: if you are creating a Review Type Property, edit your new Summarizer Type Property, add the Summarizes Property meta-Property to it, and set that to the built-in *Rating* Property. Why? Review Type is a composite of the Rating Property plus a comment box. So you have to tell the Summarizer *what* to summarize -- which sub-Property it applies to.

Yes, that's kind of horrible -- I actually spent a while trying to build things a different way, to make that process more straightforward, but that turned out to demand *horrifying* hacks to Querki's overall architecture. So we're instead going to let the underpinnings be complicated, and later we will add a specialized UI for building User Value Properties to make the process easier.

Ratings, Reviews and User Values took most of the past several weeks, but there were also several other items:

Whitelisted more HTML: I'm basically adding HTML tags and attributes as I need them. Feel free to request anything you specifically need. This time around, I whitelisted the <strike>, <dl>, <dt> and <dd> tags, as well as a rather restricted subset of data-stuff attributes. (Also feel free to request specific loosenings of this.)

Raty and Histogram: added the jQuery Raty plug-in, for those stars. This is a beautifully complete gadget, with lots of features: I am open to doing more with it, if folks really want it. Also, the simple histograms we use to summarize the ratings are a plug-in that I whipped up -- it is available for user use, if you like. (I haven't bothered to document it yet, but can do so if anyone cares.) Note that, in the longer run, I suspect we will integrate the D3 visualization library into Querki: I encourage y'all to think about what you would like to be able to do with that.

Fixed anonymous access: I had somehow managed to break un-logged-in access to Spaces. That now works again.

Internals: the biggest new internal change is that we now have a true concept of Sessions -- when you are working in a Space, you get your own little session that connects you to it. This *shouldn't* have any particularly noticeable effect (save that it enormously speeds up User Values, which was the real motivation). This Session does time out after a while (it'll be somewhere between 5-30 minutes); again, that shouldn't be visible to you except that there will be a small delay when you come back after a timeout. If you find anything behaving strangely after you've been away for a while, please tell me ASAP -- I've played with User Session timeouts heavily (the timeout is set to thirty seconds on my development machine), but changes like this are likely to cause edge-case bugs.

Next time: finish those last couple of bits for User Values. Then back to Conversations, and lots of bug fixes...

  • 1
First, create your Model, and create a new Property of Rating Type. (Or Review Type, as you prefer -- they work very similarly.)

When I go to Create New Property, I see Rating Type and Rating Summarizer as type options, but not Review Type...

Oh, good point. Since it is a Model Type, it expects you to link to the Model -- and since the Model isn't local, it isn't offering that as an option. Okay, I need to figure out how to deal with that...

... and weirdly, adding the Review Property is now failing for me. Bother. I'll track this down tomorrow...

Curious to see aggregate results if you set this loose on the Poker Querki. Create a new page sorting the variants by rating.

Good point -- the Poker Space would be a fine place to use Review. I've just added it to Variant; members are encouraged to chime in. Once we have some data, we can play with displaying it...

  • 1

Log in

No account? Create an account