Package: plone.contentratings
Overview********`plone.contentratings` is an add-on package for the Plone contentmanagement system.  It extends the Zope3 package `contentratings` toprovide through the web configurable rating categories for all CMFcontent.  It AJAX-ifies the rating UI using KSS actions.Detailed Documentation**********************Using `plone.contentratings`============================After making the package `plone.contentratings` and its dependenciesavailable to your Zope instance and restarting Zope, you should have a"product" called `contentratings` available in the Plone QuickInstaller (the `Add-on Products` control panel).  Installing this"product" will add a new control panel to Plone called `Ratings`.This panel provides two configuration sections.  One for associatingparticular content types with rating categories, and another foradding and managing rating categories.Assigning Ratings-----------------On the `Rating Assignments` tab, you can choose a portal type and thenselect the rating categories to associate with the type in themulti-select below the type selector.  Once you have selected thecategories, press the save button before selecting another type.Once this is done, a rating UI will appear on the view for theselected type.  This ui will allow setting and viewing ratings in allthe selected categories.  The order in which the categories appearwill be the same as the order in the multi-select, and is determinedby the order specified in the rating category configuration (see thenext section).You can disable ratings on an individual content object on the editform for that content object.  Just uncheck the `Enable Ratings`checkbox on the `Settings` tab.Managing Categories-------------------The `Manage Categories` tab of the control panel allows you to createcustom categories, and modify or remove categories that you havecreated.  Initially, there will be no local categories, only `AcquiredCategories`.  These are categories which are not defined in the controlpanel but in python packages/products on the filesystem.  Theacquired categories cannot be edited.To add a new category, click the `Add Local Categories` button.  Thenfill in a title for the category (this is the title that will appearin the rating UI).  All other fields are optional.  You may enter adescription (primarily for documentation purposes).  You can enterTALES expressions for determining when users can and cannot viewor set ratings in the category.  If left blank all users willbe able to both view and set ratings.  To use permissions torestrict the ratings, use an expression like::python: checkPermission('View', context)The order in which the categories are displayed in the UI isdetermined by the order attribute which should be an integer.  Theview setting determines how the rating should appear in the UI.Python products can register rating views to provide different lookand feel or behavior.  Instructions for creating and registering newviews can be found in the documentation of the `contentratings`_package.  If you use a completely custom class for your view, makesure it implements the `contentratings.browser.interfaces.IRatingView`interface and is registered for the`contentratings.interfaces.IUserRating` interface, which will ensurethat it appears in the listing.You can remove custom categories by checking the box next to thecategory and clicking the remove button.  You can of course edit anyof the category attributes.  You must click the `Save` button torecord your changes (including removing categories).**Notes On Category Names**: Internally, categories are registeredand accessed using unique names.  For TTW created categories, thesenames are generated from the title using a mechanism similar to thatused by Plone to generate ids for content objects.  This has a coupleof consequences.  If you create a category, rate content using thatcategory, and then remove the category, the ratings will still bestored on the content under the original category name.  So ifyou later create a "new" category with the same title (and hencethe same name), all content previously rated under the categorywill still have rating information attached.  This makes it veryeasy to undo a mistaken removal of a category, but may cause someunexpected behavior.Additionally, this also makes it possible to override a categorydefined globally by creating one with an identical name.  However,there is no guarantee that the names of globally defined are relatedto their titles, so it's not always obvious how to do this, nor isaldoing this recommended.  You may end up with two categories with thesame title , differentiated only by their order, which is likely tolead to confusion when assigning categories.Advanced Topics===============Notes for Developers--------------------Creating global categories and custom rating views should be astraightforward process for developers who have read the`contentratings`_ documentation.  There are a few special things tonote when developing custom rating behavior for Plone.If you want a custom global categories to be available in the controlpanel, it must be registered for the`Products.CMFCore.interfaces.IDynamicType` interface.  Also, onlycategories providing the `contentratings.interfaces.IUserRating`interface will appear in the control panel (which means that they mustuse a storage factory implementing `IUserRating`).  If you register acategory for an interface specific to your type(s), then it willappear in the UI on any content implementing that interface,will not appear in the control panel configuration, and will notrespect the `Enable Ratings` checkbox on content objects.If you want to implement a custom `Rating Manager` for your contenttypes (which presumably also implement IDynamicType), you shouldinherit from the `PloneRatingCategoryAdapter`, rather than thestandard `RatingCategoryAdapter` in `contentratings`_.  Without thebehaviors defined in this class, any TTW categories assigned to typesusing the custom rating manager are likely to break or not appear.Local Configuration-------------------It's possible to install a `LocalAssignmentUtility` (from`plone.contentratings.assignment`) in any local site manager within aCMF site.  When this is done, the `@@contentratings-controlpanel` viewcan be used on that local site.  When changes are made in the localcontrol panel, they will affect content within that local site.Within a local site, the `Acquired Categories` section of the `ManageCategories` tab will contain both global categories and categoriesdefined in site managers below the current site (e.g. at the portal).These cannot be edited, but they can be overridden (see the**Notes On Category Names** section above).Installing the utility in a local site manager above the Plone root,must be done programatically for now.  The promising `plone.localconf`package may soon provide a generic mechanism and UI for suchinstallations... _contentratings: http://pypi.python.org/pypi/contentratings/To Do======* Add mechanism to make it easy to create indexes for specific aspects ofrating categories (e.g., (avg rating, number of ratings), users whohave rated an object, ....  This probably needs some infrastructuresupport in Plone (e.g. a more flexible implementation of theIIndexableObjectWrapper stuff).* Aggregate statistics across multiple rating categories and a userinterface for displaying them.  This probably requires some supportin the underlying contentratings package, and may be best left toindividual applications using this infrastructure.* Replace KSS with jQuery.* Replace our use of the long deprecated queryNextSiteManager fromzope.app.component.HISTORY=======1.2.1 (2017-03-15)----------------- Replace KSS with JQuery.(Note: there is an upgrade step to add the new javascript to the JS registry.)[davisagli]1.1 (2013-09-20)----------------- Cleanup. Compatible with Plone 4.1, 4.2 and 4.3.  [maurits]- Added italian translation [keul]- Fixes to i18n support (prefer new ids instead of full description) [keul]- Added translations for the globally defined rating categories [keul]- Accessibility fixes: display rating value when focus is put on rating icons [keul]1.0.1 (2012-06-04)------------------- Correct version dependency for contentratings. [alecm]1.0 final (2011-08-21)----------------------- Explicitly include CMFCore permissions in configure.zcml for Plone 4.1compatibility. If Plone 3 compatibility is to be maintainted includeCMFCore entirely. [raphael]1.0 rc3 (2011-05-12)--------------------- Fix z3c.autoinclude config.1.0 rc2 (2010-11-28)--------------------- Bring back Plone 3 support by removing dependence on new CMFCore interface.[alecm]1.0 rc1 (2010-08-31)--------------------- Add indexing of average rating and users that have rated content.[alecm]- Added Spanish and Czech translations.[dukebody, macagua]- Added uninstall profile.[alecm]1.0 beta2 2009-07-06---------------------- Added auto-save on type change in control panel (disabled due to KSSbug).[alecm]- Added fixes for KSS issues.[alecm]- Added missing metadata.xml and made setup.py read out it's version.[saily]- Added german translations.[saily]- Restructured and updated HISTORY.txt.[saily]1.0 beta - 2008-05-10---------------------- A completely new architecture for defining and storing ratings. Introducesthe concepts of rating categories and rating views.0.2 beta - 2008-05-10---------------------- A bugfix release with many improvements from 0.1. This package is supersededby version 1.0 which has a completely new architecture though it should bebackwards compatible.0.1 - Released--------------- Initial package structure.[alecm]