|
JCollection manual
The following sections give an overview of the elements that are used in JCollection.
I. Categories
Categories are organized as a tree, each category has a parent (which may be the root category) and an arbitrary number of child categories. The root category is special, it has the ID 0 and can not be accessed (meaning: no items are allowed in the root category). To change the description of the root category, please change the entry in the language file.
ROOT -- Category 1 -- Category 1.1
|
- Category 1.2
Each category has a name, a description and an image. Items must belong to a proper category (NOT the root category).
II. Items
An item is the most important element of JCollection. It represents a certain book, CD, DVD, recipe,... or even an arbitrary combination of several books, CDs, DVDs, recipes,...
Each item has a name, url, image and description and a number of associated info sets, each of which representing one particular item type (book, CD, DVD, recipe,...).
III. Info sets
An info set is for an individual book, CD, DVD, recipe,...
It has a name, image, description and url. Moreover, it has a type and depending on the type up to 10 additional information fields (such as author, publisher, pages,...). Each field may be overwritten using one of the available webservices.
IV. Reviews
Each review belongs to an info set and contains a name, description (the review itself) and a rating. The rating is only displayed in frontend if the rating plugin is installed.
V. List categories
Just like normal categories, list categories have a name, image and description, but do not have a tree structure. Each list belongs to a list category.
VI. Lists
Each list belongs to a list category (list categories are like item categories, but without the tree structure, i.e. no parents and childs) and it holds an arbitrary
number of items. Although the order of the items is stored, it may not be relevant for the list (for example if lists are used as tags).
VII. Types and rating
Each info set has a type that defines the kind of information. The type itself defines labels for 10 different information fields, HTML code for these fields ({INFO1} -- {INFO10} are replaced by the actual content) and 5 labels for 5 different ratings. Each info set can be rated in up to 5 disciplines by the visitors of your site (needs rating plugin). See also: the global parameter "allow_rating".
VIII. Webservice types
Webservices typically deliver an XML file that contains information about an item. The webservice type allows to provide XPaths where item title, description, image, url and the 10 info set entries can be found.
Note that the webservice type is not neccessarily connected with an info set type, meaning that, for example, an Amazon book webservice type is used if the Amazon product group is "Books", hence the info fields are according to the webservice type. The user has to make sure that the info set type matches.
Diagram
Category contains items and categories
List category contains lists
List contains items
Item contains info sets
Info set contains reviews
Import and export
JCollection can import data from a Collection Manager installation. Please be aware that some manual work (such as publishing and approving the entries) may be neccessary. This feature is also not extensively tested, so YMMV.
It is possible to import a file which contains ISBN/Amazon ASIN numbers (one ISBN/ASIN per line).
The JCollection database can be exported and imported as XML (export is pretty much done, import not finished yet!).
Access levels
Each JCollection element (category, list, item, review, info set) has an individual access level. The possible access levels are "public" (everybody can view the element), "registered" and "special", according to the standard Joomla access control mechanism.
Access control
Each user has a set of rights according to his user group. He can either edit items that are created by him or he can edit all items. That also applies to lists and reviews. Moreover, each usergroup is or is not allowed to publish and/or approve items, reviews and lists.
Parameters
Parameters can only be changed in the backend interface - exceptions are the webservice parameters of info sets which can also be changed in frontend!
For the global parameters, select "JCollection - items" and click on "configure" in the top toolbar.
The available global parameters and their meanings are:
show_author: Show/hide the author of items
show_create_date: Show/hide date
show_modify_date: Show/hide modification date
show_item_navigation: Show/hide next/prev buttons
show_toplists, show_bottomlists: Show the selected lists using the listcat plugin
show_vote, allow_rating: show rating/allow rating for a certain usergroup
show_useful, allow_useful: show review usefulness (using rating plugin)
show_hits: Show item hits
show_reviews: Show info set reviews
show_external_reviews: Show external (webservice) reviews (Amazon)
show_additional_fields: Show additional data provided by the webservice (currently only eBay)
show_similar_items: Show similar items (currently only Amazon)
show_offers: Show offers (Amazon, eBay, Zanox)
webserviceoverwrite: default order in which the info set fields are overwritten (comma-separated list). Defaults to all webservices if empty. Possible values amazon,wikipedia,yahoo,yahoomusic,yahoomap,googlebook,googlemap,ebay,zanox,lastfm,isbndb,imdb,none (to disable webservices).
item_cache_time: item overrides are cached for this number of minutes (defaults to the global Joomla cache time).
amazonaccesskey: developer access key for the Amazon webservice (until August 15th 2009, this can be empty and then the JCollection access key is used).
amazonsecretaccesskey: From August 15th 2009, this value is neccessary to digitally sign the Amazon webservice request.
amazoncountry: default Amazon country
amazonpartnerid_percentage: Percentage how often the JCollection partnerid isused instead of the partnerid provided below. This helps to support the development of JCollection! Please consider setting this to a reasonable value (10-15%).
amazonpartnerid_xx: the Amazon partner-id (assocciate key)
isbndbaccesskey: access key for the ISBNdb webservice. Defaults to JCollection's access key, please consider getting an own access key if you use this service extensively.
wikipediacountry: Default Wikipedia country
yahooaccesskey: Yahoo webservice access key (needed if you want to use Yahoo webservices).
yahoomusiccountry: Default country for Yahoo music
lastfmaccesskey: last.fm webservice access key, defaults to JCollection's access key.
googleaccesskey: Google access key (needed for google map and associated with a website).
ebayaccesskey: eBay webservice access key. Defaults to JCollection's access key.
ebaycountry: default eBay country.
zanoxaccesskey: Zanox webservice access key id, defaults to JCollection's access key.
zanoxaccesskey_percentage: Percentage how often JCollection's access key id is used. This can help supporting JCollection's development, please consider setting this to a reasonable value (10-15%).
The category menu entry for JCollection also has some parameters:
catid: the category id.
show_all: show all items in the category, including all items in all subcategories.
The list menu entry for JCollection also has some parameters:
listid: the list id
The item menu entry for JCollection also has some parameters:
id: the item id
Each Category has the following parameters:
show_reviews: see above
Each Item has the following paramters:
Each Info set has the following parameters:
amazonitem: an identifier of the form xx_ASIN (ASIN=Amazon identification number, for books identical with the ISBN-10), xx corresponds to the Amazon country (us, uk, ca, fr, de, jp)
googlebookitem: a google books identifier
googlemapitem: a coordinate pair (long, lat)
yahooitem: an identifier X_ID (X=C or O denotes if it is a category or an offer, ID is the identification number)
yahoomapitem: a coordinatte pair (long, lat)
yahoomusicitem: a Yahoo music identifier
lastfmitem: an identifier ARTIST{,}ALBUMTITLE (the '{,}' is neccessary to separate the two parts. Unfortunately, there is no other unique identifier)
zanoxitem: a zanox product identifier
isbndbitem: an ISBN
imdbitem: an imdb identifier
The parameter overwrite rule for parameters that appear in several places is:
global parameters -> menu entry parameters -> category parameters (recursively, starting from the root category) -> item parameters (-> info set parameters/-> review parameters)
('->' means 'is overwritten by', info set/review parameters are usually not properly overwritten, but used in a manner reflecting this scheme)
Webservices
To fetch information from webservices, JCollection needs to be able to connect to the webservice servers. Most PHP installations in shared hosting environments do allow this (either directly or using the "curl" extension), but some don't. In this case, there is no way JCollection (or any other PHP script, for that matter) can use webservices. JCollection checks your webserver's ability upon installation and produces a warning if it is not possible to use webservices.
JCollection supports a variety of webservices, most of them are freely available (and hence JCollection has built-in access keys), but some of them require the JCollection user to obtain an access key.
The current status is:
Webservices that do not need any access key:
Google books, Wikipedia
imdb: No access key required, but needs the library imdbphp. For more information see "imdbphp instructions" below.
Webservices that need an access key which can be provided by JCollection:
Amazon: This will change as of August 15, 2009! Then, two keys are needed, the access key and a secret key which is used for signed requests.
ISBNdb: No access key required if your website has a moderate load. Otherwise please obtain an own access key at http://www.isbndb.com.
eBay, Zanox, last.fm
Webservices that need an access key which cannot be provided by JCollection (hence the user has to obtain a key):
Google maps: Go to ... to obtain an access key. Please note that this access key is only valid for one URL of your Joomla installation!
Yahoo webservices: Access key required. (?) Go to ...
The overwrite mechanism allows to overwrite individual fields of info sets with information that is fetched from a webservice.
Note on partner programs: if you are member of a partner program (i.e. Amazon associates, eBay partner network or Zanox), you can enter and use your partner ids in JCollection. However, to support the development of JCollection, you can enter a percentage indicating how often the JCollection partner id is used instead (percentage of webservice calls, the results may vary due to caching). JCollection uses its own partner id if no other id is given.
Note that some webservices provide additional information, such as customer reviews, offers or similar items. Some of this information can be used and displayed. See also parameters "show_offers", "show_similar_items", "show_additional_fields", "show_external_reviews".
imdbphp instructions
JCollection itself does not provide imdb access (imdb does not provide a webservice), but it can utilize imdbphp. To use imdbphp, download and unzip imdbphp. Then create a folder /administrator/components/com_jcollection/imdbphp and copy all *.class.php files into this folder. Read the documentation(!) and change the configuration to your needs.
Modules
List: Display a given list or category.
Tagcloud: Display a list cateogry as a tag cloud (this module is NOT freely available)
Plugins
JCollection comes with several plugins that provide some additional features.
Rating:
The rating plugin allows the site visitors to rate info sets and reviews (in the sense that reviews are useful or not). JCollection supports 5 rating categories per info set type.
Listcat:
Display lists that the item belongs to (and that are in a specific list category themselves) before (or after) the item. This feature also allows a simple "tagging", where tags are simply lists that belong to the list category "tags".
Catpagenav: Simple filters for category/list view (order/text)
Content plugin: link to a JCollection item from a Joomla article.
Search plugin: Use the standard Joomla search facility to search in JCollection
|
