Docs: added script info to Carousels docs
[Evergreen.git] / docs / modules / admin_initial_setup / pages / carousels.adoc
1 = Adding Carousels to Your Public Catalog =
2 :toc: 
3
4 This feature fully integrates the creation and management of book carousels into Evergreen, allowing for the display of book cover images on a library’s public catalog home page. Carousels may be animated or static. They can be manually maintained by staff or automatically maintained by Evergreen. Titles can appear in carousels based on newly cataloged items, recent returns, popularity, etc. Titles must have copies that are visible to the public catalog, be circulating, and holdable to appear in a carousel. Serial titles cannot be displayed in carousels. 
5
6 image::carousel1.png[Book carousel on public catalog front screen] 
7
8 There are three administrative interfaces used to create and manage carousels and their components: 
9
10 * <<carousel_types,Carousel Types>> - used to define different types of carousels 
11 * <<carousel_definitions,Carousels>> - used to create and manage specific carousel definitions
12 * <<carousel_mapping,Carousel Library Mapping>> - used to manage which libraries will display specific carousels, as well as the default display order on a library’s public catalog home page
13
14 Each of these interfaces are detailed below.
15
16 [[carousel_types]]
17 == CAROUSEL TYPES ==
18
19 The Carousel Types administrative interface is used to create, edit, or delete carousel types. Carousel Types define the attributes of a carousel, such as whether it is automatically managed and how it is filtered. A carousel must be associated with a carousel type to function properly.  
20
21 There are five stock Carousel Types:
22
23 * *Newly Cataloged Items* - titles appear automatically based on the active date of the title’s copies
24 * *Recently Returned Items* - titles appear automatically based on the mostly recently circulated copy’s check-in scan date and time 
25 * *Top Circulated Titles* - titles appear automatically based on the most circulated copies in the Item Libraries identified in the carousel definition; titles are chosen based on the number of action.circulation rows created during an interval specified in the carousel definition and includes both circulations and renewals
26 * *Newest Items by Shelving Location* - titles appear automatically based on the active date and shelving location of the title’s copies 
27 * *Manual* - titles are added and managed manually by library staff
28
29 Additional types can be created in the Carousel Types Interface. Types can also be modified or deleted. Access the interface by going to Administration > Server Administration > Carousel Types. 
30
31 The interface displays the list of carousel types in a grid format. The grid displays the Carousel Type ID, name of the carousel type, and the characteristics of each type by default. The Actions Menu is used to edit or delete a carousel type.
32
33 image::carousel2.png[Carousel Types configuration screen]
34
35 === Attributes of Carousel Types ===
36
37 Each Carousel Type defines attributes used to add titles to the carousels associated with the type. Filters apply only to automatically managed carousels.
38
39 * *Automatically Managed* - when set to true, Evergreen uses a cron job to add titles to a carousel automatically based on a set of criteria established in the carousel definition. When set to false, library staff must enter the contents of a carousel manually.
40 * *Filter by Age* - when set to true, the type includes or excludes titles based on the age of their attached items
41 * *Filter by Item Owning Library* - when set to true, the type includes or excludes titles based the owning organizational unit of their attached items
42 * *Filter by Item Location* - when set to true, the type includes or excludes titles based on the shelving locations of their attached items
43
44 === Creating a Carousel Type ===
45
46 . Go to Administration > Server Administration > Carousel Types
47 . Select the *New Carousel Type* button
48 . Enter a name for the carousel type
49 . Use the checkboxes to apply filtering characteristics to the carousel type; filters for age, item owning library, and location are applied only to automatically managed carousels 
50   .. Automatically Managed?
51   .. Filter by Age?
52   .. Filter by Item Owning Library?
53   .. Filter by Item Location?
54
55 image::carousel3.png[Carousel Types Editor screen]
56
57 === Editing a Carousel Type ===
58
59 Users can rename a carousel type or change the characteristics of existing types.
60
61 . Go to Administration > Server Administration > Carousel Types
62 . Select the type you wish to edit with the checkbox at the beginning of the row for that type
63 . Select the Actions Button (or right-click on the type’s row) and choose Edit Type
64
65 === Deleting a Carousel Type ===
66
67 Carousel types can be deleted with the Actions Menu
68
69 . Go to Administration > Server Administration > Carousel Types
70 . Select the type you wish to delete with the checkbox at the beginning of the row for that type
71 . Select the Actions button (or right-click on the type’s row) and choose Delete Type; carousel types cannot be deleted if there are carousels attached
72
73 [[carousel_definitions]]
74 == CAROUSEL DEFINITIONS ==
75
76 The Carousels administration page is used to define the characteristics of the carousel, such as the carousel type, which libraries will be able to display the carousel, and which shelving locations should be used to populate the carousel.
77
78 The Carousels administration page is accessed through Administration > Server Administration > Carousels. (Please note that in the community release, this page will eventually move to Local Administration.) The interface displays existing carousels in a grid format. The grid can be filtered by organizational unit, based on ownership. The filter may include ancestor or descendent organization units, depending on the scope chosen. The columns displayed correspond to attributes of the carousel. The following are displayed by default: Carousel ID, Carousel Type, Owner, Name, Last Refresh Time, Active, Maximum Items. 
79
80 image::carousel4.png[Carousels configuration screen]
81
82 Additional columns may be added to the display with the column picker, including the log in of the creator and/or editor, the carousel’s creation or edit time, age limit, item libraries, shelving locations, or associated record bucket. 
83
84 === Attributes of a Carousel Definition ===
85
86 * *Carousel ID* - unique identifier assigned by Evergreen when the carousel is created
87 * *Carousel Type* - identifies the carousel type associated with the carousel
88 * *Owner* - identifies the carousel’s owning library organizational unit
89 * *Name* - the name or label of the carousel
90 * *Bucket* - once the carousel is created, this field displays a link to the carousel’s corresponding record bucket
91 * *Age Limit* - defines the age limit for the items (titles) that are displayed in the carousel
92 * *Item Libraries* - identifies which libraries should be used for locating items/titles to add to the carousel; this attribute does not check organizational unit inheritance, so include all libraries that should be used
93 * *Shelving Locations* - sets which shelving locations can/should be used to find titles for the carousel
94 * *Last Refresh Time* - identifies the last date when the carousel was refreshed, either automatically or manually. This is currently read-only value.
95 * *Is Active* - when set to true, the carousel is visible to the public catalog; automatically-maintained carousels are refreshed regularly (inactive automatic carousels are not refreshed)
96 * *Maximum Items* - defines the maximum number of titles that should appear in the carousel; this attribute is enforced only for automatically maintained carousels
97
98
99 === Creating a Carousel from the Carousels Administration Page ===
100
101 . Go to Administration > Server Administration > Carousels
102 . Select the *New Carousels* button
103 . A popup will open where you will enter information about the carousel
104 . Choose the Carousel Type from the drop-down menu
105 . Choose the Owning Library from the drop-down
106 . Enter the Name of the carousel
107 . Enter the Age limit - this field accepts values such as “6 mons or months,” “21 days,” etc.
108 . Choose the Item Libraries - this identifies the library from which items are pulled to include in the carousel
109   .. Click the field. A list of available organizational units will appear.
110   .. Select the organizational unit(s)
111    ... The owning and circulating libraries must be included on this list for titles/items to appear in the carousel. For libraries with items owned at one organizational unit (e.g., the library system), but circulating at a different organizational unit (e.g., a branch), both would need to be included in the list.
112   .. Click Add
113 . Shelving Locations - this identifies the shelving locations from which items are pulled to include in the carousel. Please note that this field is not applicable when creating a carousel of the Newly Cataloged carousel type. For creating a carousel of newly cataloged items with shelving location filters, use the Newest Items by Shelving Location type instead.
114   .. Click the field. A list of available shelving locations will appear.
115   .. Select the shelving location - the library that “owns” the shelving location does not have to be included in the list of Item Libraries
116   .. Click Add
117 . Last Refresh Time - not used while creating carousels - display the date/time when the carousel was most recently refreshed
118 . Is Active - set to true for the carousel to be visible to the public catalog
119 . Enter the Maximum Number of titles to display in the carousel
120 . Click Save 
121
122 image::carousel5.png[Carousel editor screen]
123
124 === Carousels and Record Buckets ===
125
126 When a carousel is created, a corresponding record bucket is also created. The bucket is owned by the staff user who created the carousel; however, access to the carousel is controlled by the carousel’s owning library. The bucket is removed if the carousel is deleted. 
127
128 === View a Carousel Bucket from Record Buckets ===
129
130 A record bucket linked to a carousel can be displayed in the Record Bucket interface through the Shared Bucket by ID action.
131
132 . Go to Cataloging > Record Buckets
133 . Select the Buckets button
134 . Enter the bucket number of the carousel’s bucket; this can be found on the Carousels administration page. “Bucket” is one of the column options for the grid. It displays the bucket number. 
135 . The contents of the carousel and bucket will be displayed
136
137 Users can add or remove records from the bucket. If the associated carousel is automatically maintained, any changes to the bucket’s contents are subject to being overwritten by the next automatic update. Users are warned of this when making changes to the bucket contents.
138
139 === Create a Carousel from a Record Bucket ===
140
141 A carousel can be created from a record bucket.
142  
143 . Go to Cataloging > Record Buckets
144 . The Bucket View tab opens. Select the Buckets button and choose one of the existing buckets to open. The list of titles in the bucket will display on the screen.
145 . Select the Buckets button and choose Create Carousel from Bucket
146
147 image::carousel6.png[Record Bucket Actions button - Create Carousel from Bucket]
148
149 TIP: The Create Carousel from Bucket option is visible in both Record Query and Pending Buckets; however, initiating the creation of a carousel from either of these two tabs creates an empty bucket only. It will not pull titles from either to add contents to the carousel.
150
151 === Manually Adding Contents to a Carousel from Record Details Page ===
152
153 Titles can be added to a manually maintained carousel through the record details page.
154
155 . Go to the details page for a title record
156 . Select the Other Actions button
157 . Choose Add to Carousel
158 +
159 image::carousel7.png[Actions button on Record Summary page - Add to Carousel] 
160 +
161 . A drop-down with a list of manually maintained carousels that have been shared to at least one of the user’s working locations will appear
162 . Choose the carousel from the list
163 . Click Add to Selected Carousel
164
165 TIP: The Add to Carousel menu item is disabled if no qualifying carousels are available
166
167 [[carousel_mapping]]
168 == CAROUSEL LIBRARY MAPPING ==
169
170 The Carousel Library Mapping administration page is used to manage which libraries will display specific carousels, as well as the default display order on a library’s public catalog. 
171
172 The visibility of a carousel at a given organizational unit is not automatically inherited by the descendants of that unit. The carousel’s owning organizational unit is automatically added to the list of display organizational units.
173
174 The interface is accessed by going to Administration > Server Administration > Carousel Library Mapping. (Please note that in the community release, this page will eventually move to Local Administration.) The interface produces a grid display with a list of the current mapping. The grid can be filtered by organizational unit, based on ownership. The filter may include ancestor or descendent organizational units, depending on the scope chosen. 
175
176 WARNING: If a carousel is deleted, its mappings are deleted.
177
178 === Attributes of Carousel Library Mapping ===
179
180 * *ID* - this is a unique identifier automatically generated by the database
181 * *Carousel* - this is the carousel affected by the mapping
182 * *Override Name* - this creates a name for automatically managed carousels that will be used in the public catalog display of the carousel instead of the carousel’s name
183 * *Library* - this is the organizational unit associated with the particular mapping; excludes descendent units
184 * *Sequence Number* - this is the order in which carousels will be displayed, starting with “0” (Example: Carousel 0 at consortial level will display first. Carousel 1 set at the consortial level will appear just below Carousel 0.)
185
186 === Create a New Carousel Mapping ===
187
188 . Go to Administration > Server Administration > Carousel Library Mapping
189 . Select *New Carousels Visible at Library*
190 . Choose the Carousel you wish to map from the Carousel drop-down menu
191 . If you want the title of the carousel on the public catalog home screen to be different from the carousel’s name, enter your desired name in the Override Name field
192 . Click on the Library field to choose on which library organizational unit’s public catalog home screen the carousel will appear
193 . Enter a number in sequence number to indicate in which order the carousel should appear on the library public catalog home screen. “0” is the top level. “1” is the subsequent level, etc.
194
195 image::carousel8.png[Carousel mapping editor screen]
196
197
198 == CAROUSELS - OTHER ADMINISTRATIVE FEATURES ==
199
200 === New Staff Permissions ===
201
202 Includes new staff permissions:
203
204 * ADMIN_CAROUSEL_TYPES - allows users to create, edit, or delete carousel types
205 * ADMIN_CAROUSELS - allows users to create, edit, or delete carousels
206 * REFRESH_CAROUSEL - allows users to perform a manual refresh of carousels
207
208 === New Database Tables ===
209
210 A new table was added to the database to specify the carousel and how it is to be populated, including the name, owning library, details about the most recent refresh, and a link to the Record Bucket and its contents.
211
212 Another new table defines carousel types and includes the name, whether the carousel is manually or automatically maintained, and a link to the QStore query specifying the foundation database query used to populate the carousel.
213
214 A third new table defines the set of organizational units at which the carousel is visible and the display order in which carousels should be listed at each organizational unit.
215
216 === OPAC Templates ===
217
218 Carousels display on the public catalog home page by default. Administrators can modify the public catalog templates to display carousels where desired.
219
220 A new Template Toolkit macro called “carousels” allows the Evergreen administrator to inject the contents of one or more carousels into any point in the OPAC. The macro will accept the following parameters:
221
222 * carousel_id
223 * dynamic (Boolean, default value false)
224 * image_size (small, medium, or large)
225 * width (number of titles to display on a “pane” of the carousel)
226 * animated (Boolean to specify whether the carousel should automatically cycle through its panes)
227 * animation_interval (the interval (in seconds) to wait before advancing to the next pane)
228
229 If the carousel_id parameter is supplied, the carousel with that ID will be displayed. If carousel_id is not supplied, all carousels visible to the public catalog's physical_loc organizational unit is displayed.
230
231 The dynamic parameter controls whether the entire contents of the carousel should be written in HTML (dynamic set to false) or if the contents of the carousel should be asynchronously fetched using JavaScript.
232
233 A set of CSS classes for the carousels and their contents will be exposed in style.css.tt2. Lightweight JavaScript was used for navigating the carousels, based either on jQuery or native JavaScript. The carousels are responsive.
234
235 === Accessibility Features ===
236
237 * Users can advance through the carousel using only a keyboard
238 * Users can navigate to a title from the carousel using only a keyboard
239 * Users pause animated carousels
240 * Changes in the state of the carousel are announced to screen readers.
241
242 === OpenSRF ===
243
244 Several Evergreen APIs are used to support the following operations:
245
246 * refreshing the contents of an individual carousel
247 * refreshing the contents of all automatically-maintained carousels that are overdue for refresh
248 * retrieving the names and contents of a carousel or all visible ones
249 * creating a carousel by copying and existing record bucket
250
251 The retrieval APIs allow for anonymous access to permit Evergreen admins to create alternative implementation of the carousel display or to share the carousels with other systems.
252
253 === Cron Job ===
254
255 The carousels feature includes a cronjob added to the example crontab to perform automatic carousel refreshes. It is implemented as a srfsh script named  `/openils/bin/refresh_carousels.srfsh` which will invoke `open-ils.storage.carousel.refresh_all`.
256