Differences

This shows you the differences between two versions of the page.

--- en:user:favourites [2023/07/24 01:47] – updated version info kjdon
+++ en:user:favourites [2024/02/12 23:42] (current) – [Customizing Favourites] kjdon
@@ Line 1: / Line 1: @@
+====== Greenstone 3 Favourites ======
-====== Favourites/Berry Baskets (Greenstone 3) ======
+//[ This page documents favourites for Greenstone 3 version 3.11. For 3.10 and earlier versions, please see our [[en:user:berry_baskets| Berry Baskets]] page. ]//
-//[ This version is for 3.11. For 3.10 and earlier versions, please see our [[en:user:berry_baskets| Berry Baskets]] page. ]//
+The favourites functionality allows the user to collect up a set of interesting or useful documents as she is browsing through the library. Once they are finished, they can view the basket of links, and email it to themselves.
-A favourites/berry basket functionality has been implemented in Greenstone 3. This allows the user to collect up a set of interesting or useful documents as she is browsing through the library. Once they are finished, they can view the basket of links, and email it to themselves.
+When favourites are enabled, a star is displayed for each document in browsing and searching lists. Clicking the star will add/remove that document to/from the favourites list.
-Favourites - a star is displayed for each document in browsing and searching lists. Clicking the star will add/remove that document from the favourites list.
+A link to the favourites list is also displayed on searching, browsing and document view pages. Clicking the link will take you to a full view of the contents of the list, where you can remove items, and email the list, or copy the list for pasting elsewhere.
-Berry Baskets - little berries are displayed by each document. Drag a berry on to the basket to add that document.
+===== Activating Favourites =====
-The basket itself is displayed on the side of the page. Clicking the link in the basket will take you to a full view of the contents of the basket.
+A library can enable the favourites functionality using a servlet option. Favourites are enabled by default. To disable, please edit resources/web/servlets.xml.in, and set the **favouritebasket** parameter to **false** in the servlet description for the library you want to change.
-===== Activating Favourites/Berry Baskets =====
+A user can enable/disable favourites for themselves (assuming the library provides the funtionality) on the preferences page. Favourites are enabled for the user by default. To set them to be disabled by default,  set a paramDefault in web/sites/localsite/siteConfig.xml (or in the siteConfig.xml of the site you are using for the library). This format element goes at the top level of the siteConfig element.
-By default, Favourites is active, not Berry Baskets.
-The library administrator can change to use Berry Baskets, or disable the functionality altogether by editing options in the web/interfaces/default/interfaceConfig.xml file.
-<code>
-<optionList>
-  <option name="favouriteBasket" value="true"/>
-  <option name="berryBasket" value="false"/>
-</optionList>
-</code>
-Set both to false to disable this completely.
-While the functionality is active, it is not turned on for the user by default. (It will be for 3.10 and later). The user can go to Preferences, and turn it on/off.
-To make it turned on/off by default, set a paramDefault in web/sites/localsite/siteConfig.xml.
 <code>
 <format>
-  <paramDefault name="favouritebasket" value="on"/>  (or 'off', or 'berrybasket')
+  <paramDefault name="favouritebasket" value="off"/>
 </format>
 </code>
-===== Customizing Berry Baskets =====
+===== Customizing Favourites =====
-==== Metadata ====
+The links in the list of favourites can now be customised using format statements (like we use to customise document lists for browsing and searching).
-If you want to add an extra metadata field to the display, then you need to specify that metadata in web/sites/localsite/siteConfig.xml. Look for the BerryBasket serviceRack and add a metadataList containing the desired elements. For example:
+The content of the favourites page is defined in web/interfaces/default/transform/pages/favourites.
-<code>
+The default templace for the documentNode is below. This will be used if there is no alternative specified in the FavouriteBasket ServiceRack, or in a collectionConfig file.
-<serviceRack name="BerryBaskets">
-  <metadataList>
-    <metadata name="dc.Creator"/>
-    <metadata name="dc.Subject"/>
-  </metadataList>
-</serviceRack>
-</code>
-Then restart Tomcat.
-By default, these specified metadata elements will just get added to the item's display, e.g. at the bottom of the metadata lists in the 'text' and 'email' views. Or after the title in the 'full' view.
-If you want to customise the display, take a look at the javascript code. web/interfaces/default/js/berrybasket/berrybasket.js, function showBasket() displays the small version on other pages, while web/interfaces/default/js/berrybasket/berrycheckout.js functions showFullView(), showTextView() and showEmail() display the different basket views. In particular, populateUrlsAndMetadata() displays the links plus metadata entries for Text and Email views, and generateDocDisplay() displays the entries for the text view.
-=== Example: Using dc.Title instead of Title in Berry Basket display ===
-By default, the berry basket entries display Title metadata. If the linked item is a section, it will also display the book Title (root_Title).
-If we have a collection that doesn't have Title metadata (eg from a CSV spreadsheet), we can modify the code to display dc.Title instead.
-. Edit web/sites/localsite/siteConfig.xml and add dc.Title into the BerryBasket service metadataList:
 <code>
-<serviceRack name="BerryBaskets">
+<xsl:template match="documentNode">
-  <metadataList>
+   <xsl:call-template name="displayFavourite"/>
-    <metadata name="dc.Title"/>
+</xsl:template>
-  </metadataList>
+<xsl:template match="documentNode" mode="plain-text">
-</serviceRack>
+   <xsl:call-template name="displayPlainText"/>
-</code>
+</xsl:template>
-. Edit web/interfaces/default/js/berrybasket/berrycheckout.js
-Look for generateDocDisplay and edit it:
-<code>
-Replace:
-a.href=generateURL(doc);
-a.appendChild(document.createTextNode(doc['Title']));
-with either:
-. Use this if all documents have dc.Title instead of Title
-a.href=generateURL(doc);
-a.appendChild(document.createTextNode(doc['dc.Title']));
-or:
-. use this if some documents have Title and some have dc.Title
-a.href=generateURL(doc);
-if (doc['Title']) {
-   a.appendChild(document.createTextNode(doc['Title']));
-} else if (doc['dc.Title']) {
-   a.appendChild(document.createTextNode(doc['dc.Title']));
-}
 </code>
-This will now display dc.Title instead of Title for the title link to the document in the full view.
+The displayFavourite template displays a link to the source doc (eg pdf/image etc) plus the document title which is linked to the greenstone version of the document. The displayPlainText template makes a plain text version, with no HTML markup, suitable for use in an email or in the copy buffer.
-However, as dc.Title is not defined as one of the standard metadatas, it also gets added to the end of the display. To prevent this, either add it to the default_metas list at the top of the file, or modify generateDocDisplay further.
-<code>
-Replace:
-for (var metaItem in doc) {
-  if ( !default_metas.includes(metaItem)){
-     metadata += " "+metaItem+": "+ doc[metaItem]+" ";
-  }
-}
-with:
+web/sites/localsite/siteConfig.xml is where the FavouriteBasket ServiceRack is added to the library. In here we can customise the display for a particular site - by default, the documentNode templates above are just repeated here. Note, in order to be able to add collection specific formatting, this site-wide format element needs to be present.
-for (var metaItem in doc) {
-  if ( !default_metas.includes(metaItem) && metaItem != 'dc.Title'){
-     metadata += " "+metaItem+": "+ doc[metaItem]+" ";
-  }
-}
-</code>
-In the text and email view, all metadata is displayed in a list: First the hard-wired ones, then any that are not in the default list. So the dc.Title metadata just gets added to the list. If you added dc.Title to default_metas list as mentioned above, then you need to manually add it to the display to get it to appear.
-For example, in populateUrlsAndMetadata(), add in the following:
 <code>
-if (doc['dc.Title']) {
+   <serviceRack name="FavouriteBasket">
-  metadata += "dc.Title: "+doc['dc.Title']+"\n";
+      <format>
-}
+        <!-- set the following to true is you have an email service on the server, or if you have setup mail server properties in resources/web/global.properties.in-->
+        <gsf:option name="serverEmail" value="false"/>
+        <!-- default template used for email/copy-->
+        <xsl:template match="documentNode" mode="plain-text">
+          <xsl:call-template name="displayPlainText"/>
+        </xsl:template>
+        <!-- default template used for favourites display -->
+        <xsl:template match="documentNode">
+          <xsl:call-template name="displayFavourite"/>
+        </xsl:template>
+      </format>
+    </serviceRack>
 </code>
+A collection can specify its own customisation for documents from that collection in the favourites list. In this case, we have to put it in a special place: inside a top level ccServices element (cross collection services), specifying which service the format element is for.
+For example:
-==== Document Link ====
-By default the link in the basket will be to the Greenstone HTML version of the document. You can change this to link to the source document, eg the PDF version.
-Edit web/interfaces/default/js/berrybasket/berrycheckout.js.
-There are three variables at the top of this file:
 <code>
-var default_link_type = "document"; // or "source"
+<ccServices>
-var source_link_collections = new Array();
+  <format service="GetFavouritesList">
-var document_link_collections = new Array();
+    <xsl:template match="documentNode">
+      <xsl:call-template name="displayFavourite"/><gsf:metadata name="dc.Creator/>
+    </xsl:template>
+    <xsl:template mode="plain-text" match="documentNode">
+      <gsf:metadata name="dc.Title"/>
+       <xsl:text> (</xsl:text>
+       <xsl:value-of select="@collection"/>
+       <xsl:text>)</xsl:text>
+    </xsl:template>
+  </format>
+</ccServices>
 </code>
-The default_link_type specifies whether links are to the Greenstone versions ("document") or to the source eg PDF versions ("source"); If you then want to have a few collections done the opposite way, use source_link_collections/document_link_collections to list the exceptions.
+The first template uses the default display template, but adds on dc.Creator metadata. The second template does away with the default altogether, and displays the dc.Title metadata, followed by the collection name in brackets. A pretty useless display, as it contains no link to the document, but just for illustrative purposes.
-For example, if most collections use document, but pdfcoll and exampapers use source, then set the variables like this:
+===== Setting up the Email Results Functionality =====
-<code>
+The favourites list can be emailed out using a mail server, or by using the user's existing mail client.
-var default_link_type = "document";
-var source_link_collections = ["pdfcoll", "exampapers"];
-</code>
-Similarly, use document_link_collections to set the exceptions if you have made the default "source".
+Mail server:
+  * the results will be emailed from a pre-specified  address
+  * requires the mail server to be set up
+  * works for all users
-===== Setting up the Email Results Functionality =====
+User's mail client:
+  * doesn't require any mail server setup
+  * the email will be sent from the user's own address
+  * Won't work if the user has no default mail client
-This applies to nightly releases and the upcoming 3.09 release. Emailing the results didn't work properly in 3.08.
+If you have a mail server set up on the machine running tomcat, or you want to use another existing mail server,
-Please edit resources/web/global.properties.in (31 July 2018 and later binaries) or resources/web/global.properties (30 July 2018 or earlier binaries). Set your mail server, username and password etc by uncommenting the lines and setting the proper values.
+Please edit resources/web/global.properties.in. Set your mail server, username and password etc by uncommenting the lines and setting the proper values.
 <code>