From: Remington Steed Date: Fri, 10 Jan 2020 13:47:25 +0000 (-0500) Subject: LP#1848524: Docs: section fixes X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=84c085bcb2c8c9e95ed2114934f03809c658e052;p=evergreen%2Ftadl.git LP#1848524: Docs: section fixes For "System Configuration and Customization": - Add chapter labels to nav file items - To match existing docs "chapter" level headings, combine adoc files as needed so that each "chapter" from the old docs structure has a single file linked from the nav - Upgrade all heading levels in each adoc file so that the top-most heading is a "Level 1" heading (example: "= Chapter Name =") - Add ":toc:" below top heading of each file For 'Using the Public Access Catalog'": - Add chapter labels to nav file items - To match existing docs "chapter" level headings, combine adoc files as needed so that each "chapter" from the old docs structure has a single file linked from the nav - In this case, the only change was in advanced_features.adoc, where two sections had the top heading level (seems like a mistake). I bumped the second one down ("Binary MARC21 Feeds") so it is a subsection of the file. Ironically, since this commit also bumps up all headings by one level, it means that heading is the only one not changed in this commit. - Upgrade all heading levels in each adoc file so that the top-most heading is a "Level 1" heading (example: "= Chapter Name =") - Add ":toc:" below top heading of each file For "Developer Resources" and "Getting Data from Evergreen": - Add chapter labels to nav file items - To match existing docs "chapter" level headings, combine adoc files as needed so that each "chapter" from the old docs structure has a single file linked from the nav - Upgrade all heading levels in each adoc file so that the top-most heading is a "Level 1" heading (example: "= Chapter Name =") - Add ":toc:" below top heading of each file Signed-off-by: Remington Steed Signed-off-by: Galen Charlton --- diff --git a/docs-antora/modules/admin/pages/sip_privacy.adoc b/docs-antora/modules/admin/pages/sip_privacy.adoc deleted file mode 100644 index 9815103a74..0000000000 --- a/docs-antora/modules/admin/pages/sip_privacy.adoc +++ /dev/null @@ -1,47 +0,0 @@ -=== Patron privacy and the SIP protocol === - -SIP traffic includes a lot of patron information, and is not -encrypted by default. It is strongly recommended that you -encrypt any SIP traffic. - -==== SIP server configuration ==== - -On the SIP server, use `iptables` or `etc/hosts` to allow SSH connections on port 22 from the SIP client machine. You will probably want to have very restrictive rules -on which IP addresses can connect to this server. - - -==== SSH tunnels on SIP clients ==== - -SSH tunnels are a good fit for use cases like self-check machines, because it is relatively easy to automatically open the connection. Using a VPN is another option, -but many VPN clients require manual steps to open the VPN connection. - -. If the SIP client will be on a Windows machine, install cygwin on the SIP client. -. On the SIP client, use `ssh-keygen` to generate an SSH key. -. Add the public key to /home/my_sip_user/.ssh/authorized_keys on your SIP server to enable logins without using the UNIX password. -. Configure an SSH tunnel to open before every connection. You can do this in several ways: -.. If the SIP client software allows you to run an arbitrary command before - each SIP connection, use something like this: -+ -[source,bash] ----- -ssh -f -L 6001:localhost:6001 my_sip_user@my_sip_server.com sleep 10 ----- -+ -.. If you feel confident that the connection won't get interrupted, you can have something like this run at startup: -+ -[source,bash] ----- -ssh -f -N -L 6001:localhost:6001 my_sip_user@my_sip_server.com ----- -+ -.. If you want to constantly poll to make sure that the connection is still running, you can do something like this as a cron job or scheduled task on the SIP client machine: -[source,bash] ----- -#!/bin/bash -instances=`/bin/ps -ef | /bin/grep ssh | /bin/grep -v grep | /bin/wc -l` -if [ $instances -eq 0 ]; then - echo "Restarting ssh tunnel" - /usr/bin/ssh -L 6001:localhost:6001 my_sip_user@my_sip_server.com -f -N -fi ----- - diff --git a/docs-antora/modules/admin/pages/sip_server.adoc b/docs-antora/modules/admin/pages/sip_server.adoc index 446a73bcee..2b990a85a3 100644 --- a/docs-antora/modules/admin/pages/sip_server.adoc +++ b/docs-antora/modules/admin/pages/sip_server.adoc @@ -680,3 +680,52 @@ All fixed-length fields in a communication will appear before the first variable parsing. Variable-length fields are by definition delimited, though there will not necessarily be an initial delimiter between the last fixed-length field and the first variable-length one. It would be unnecessary, since you should know the exact position where that field begins already. + + +=== Patron privacy and the SIP protocol === + +SIP traffic includes a lot of patron information, and is not +encrypted by default. It is strongly recommended that you +encrypt any SIP traffic. + +==== SIP server configuration ==== + +On the SIP server, use `iptables` or `etc/hosts` to allow SSH connections on port 22 from the SIP client machine. You will probably want to have very restrictive rules +on which IP addresses can connect to this server. + + +==== SSH tunnels on SIP clients ==== + +SSH tunnels are a good fit for use cases like self-check machines, because it is relatively easy to automatically open the connection. Using a VPN is another option, +but many VPN clients require manual steps to open the VPN connection. + +. If the SIP client will be on a Windows machine, install cygwin on the SIP client. +. On the SIP client, use `ssh-keygen` to generate an SSH key. +. Add the public key to /home/my_sip_user/.ssh/authorized_keys on your SIP server to enable logins without using the UNIX password. +. Configure an SSH tunnel to open before every connection. You can do this in several ways: +.. If the SIP client software allows you to run an arbitrary command before + each SIP connection, use something like this: ++ +[source,bash] +---- +ssh -f -L 6001:localhost:6001 my_sip_user@my_sip_server.com sleep 10 +---- ++ +.. If you feel confident that the connection won't get interrupted, you can have something like this run at startup: ++ +[source,bash] +---- +ssh -f -N -L 6001:localhost:6001 my_sip_user@my_sip_server.com +---- ++ +.. If you want to constantly poll to make sure that the connection is still running, you can do something like this as a cron job or scheduled task on the SIP client machine: +[source,bash] +---- +#!/bin/bash +instances=`/bin/ps -ef | /bin/grep ssh | /bin/grep -v grep | /bin/wc -l` +if [ $instances -eq 0 ]; then + echo "Restarting ssh tunnel" + /usr/bin/ssh -L 6001:localhost:6001 my_sip_user@my_sip_server.com -f -N +fi +---- + diff --git a/docs-antora/modules/admin_initial_setup/nav.adoc b/docs-antora/modules/admin_initial_setup/nav.adoc index 0920fd9728..e036815c0d 100644 --- a/docs-antora/modules/admin_initial_setup/nav.adoc +++ b/docs-antora/modules/admin_initial_setup/nav.adoc @@ -1,29 +1,32 @@ * xref:admin_initial_setup:introduction.adoc[System Configuration and Customization] -** xref:admin_initial_setup:describing_your_organization.adoc[] -** xref:admin_initial_setup:describing_your_people.adoc[] -** xref:admin_initial_setup:migrating_patron_data.adoc[] -** xref:admin_initial_setup:migrating_your_data.adoc[] -** xref:admin_initial_setup:importing_via_staff_client.adoc[] -** xref:admin_initial_setup:ordering_materials.adoc[] -** xref:admin_initial_setup:designing_your_catalog.adoc[] -** xref:admin_initial_setup:different_styles_for_searchbar.adoc[] -** xref:admin:search_interface.adoc[] -** xref:admin_initial_setup:borrowing_items.adoc[] -** xref:admin:autorenewals.adoc[] -** xref:admin_initial_setup:hard_due_dates.adoc[] -** xref:admin:template_toolkit.adoc[] +** xref:admin_initial_setup:describing_your_organization.adoc[Describing your +organization] +** xref:admin_initial_setup:describing_your_people.adoc[Describing your people] +** xref:admin_initial_setup:migrating_patron_data.adoc[Migrating Patron Data] +** xref:admin_initial_setup:migrating_your_data.adoc[Migrating from a legacy +system] +** xref:admin_initial_setup:importing_via_staff_client.adoc[Importing materials +in the staff client] +** xref:admin_initial_setup:ordering_materials.adoc[Ordering materials] +** xref:admin_initial_setup:designing_your_catalog.adoc[Designing your catalog] +** xref:admin:search_interface.adoc[Designing the patron search experience] +** xref:admin_initial_setup:borrowing_items.adoc[Borrowing items: who, what, for +how long] +** xref:admin:autorenewals.adoc[Autorenewals in Evergreen] +** xref:admin_initial_setup:hard_due_dates.adoc[Hard due dates] +** xref:admin:template_toolkit.adoc[TPac Configuration and Customization] ** xref:admin_initial_setup:carousels.adoc[Carousels] -** xref:opac:new_skin_customizations.adoc[] -** xref:admin:auto_suggest_search.adoc[] -** xref:admin:authentication_proxy.adoc[] -** xref:admin_initial_setup:KidsOPAC.adoc[] -** xref:admin:patron_address_by_zip_code.adoc[] -** xref:admin:phonelist.adoc[] -** xref:admin:sip_server.adoc[] -** xref:admin:sip_privacy.adoc[] -** xref:admin:apache_rewrite_tricks.adoc[] -** xref:admin:apache_access_handler.adoc[] -** xref:admin:ebook_api_service.adoc[] -** xref:admin:hold_targeter_service.adoc[] -** xref:admin:backups.adoc[] +** xref:opac:new_skin_customizations.adoc[Creating a New Skin: the Bare Minimum] +** xref:admin:auto_suggest_search.adoc[Auto Suggest in Catalog Search] +** xref:admin:authentication_proxy.adoc[Authentication Proxy] +** xref:admin_initial_setup:KidsOPAC.adoc[Kid's OPAC Configuration] +** xref:admin:patron_address_by_zip_code.adoc[Patron Address City/State/County +Pre-Populate by ZIP Code] +** xref:admin:phonelist.adoc[Phonelist.pm Module] +** xref:admin:sip_server.adoc[SIP Server] +** xref:admin:apache_rewrite_tricks.adoc[Apache Rewrite Tricks] +** xref:admin:apache_access_handler.adoc[Apache Access Handler Perl Module] +** xref:admin:ebook_api_service.adoc[ebook_api service] +** xref:admin:hold_targeter_service.adoc[hold-targeter service] +** xref:admin:backups.adoc[Backing up your Evergreen System] diff --git a/docs-antora/modules/admin_initial_setup/pages/KidsOPAC.adoc b/docs-antora/modules/admin_initial_setup/pages/KidsOPAC.adoc index c42cdb156c..0c572e46be 100644 --- a/docs-antora/modules/admin_initial_setup/pages/KidsOPAC.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/KidsOPAC.adoc @@ -1,8 +1,9 @@ -== Kid's OPAC Configuration == += Kid's OPAC Configuration = +:toc: -=== Configuration === +== Configuration == -==== Apache ==== +=== Apache === The KPAC is already included and ready to be used with new Evergreen installs. So you only need to change the apache config if you need to change template locations or if you want to use a different *kpac.xml* config file. The defaults for the KPAC are set @@ -15,7 +16,7 @@ in */etc/apache2/eg_vhosts.conf*. ------------------------------------------------------------------------------ -==== XML Configuration File ==== +=== XML Configuration File === * The XML configuration file defines the layout of the kid's OPAC. * It is read with each restart/reload of the Apache web server. @@ -73,7 +74,7 @@ in */etc/apache2/eg_vhosts.conf*. ------------------------------------------------------------------------------ -==== Skin Configuration ==== +=== Skin Configuration === The following example enables you to configure the alternate skin (Monster Skin, kpac2) for the Kids Catalog. @@ -110,7 +111,7 @@ along the lines of: ------------------------------------------------------------------------------ -=== Considerations for Community Adoption === +== Considerations for Community Adoption == The templates for the Kid's OPAC were developed long before the TPAC was integrated into Evergreen and it has many of the same limitations that @@ -124,7 +125,7 @@ were part of the TPAC. palette. Creating an additional skin to act as the Evergreen default my be necessary. -=== Outstanding Development (Unsponsored) === +== Outstanding Development (Unsponsored) == ** Port the XML configuration file to a DB structure, complete with UI for managing the various components and upgrade path. diff --git a/docs-antora/modules/admin_initial_setup/pages/borrowing_items.adoc b/docs-antora/modules/admin_initial_setup/pages/borrowing_items.adoc index fcd852d3c9..4ed0bc72b5 100644 --- a/docs-antora/modules/admin_initial_setup/pages/borrowing_items.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/borrowing_items.adoc @@ -1,4 +1,5 @@ -== Borrowing items: who, what, for how long == += Borrowing items: who, what, for how long = +:toc: Circulation policies pull together user, library, and item data to determine how library materials circulate, such as: which patrons, from what libraries can @@ -8,12 +9,12 @@ Individual elements of the circulation policies are configured using specific interfaces, and should be configured prior to setting up the circulation policies. -=== Data elements that affect your circulation policies === +== Data elements that affect your circulation policies == There are a few data elements which must be considered when setting up your circulation policies. -==== Copy data ==== +=== Copy data === Several fields set via the holdings editor are commonly used to affect the circulation of an item. @@ -28,7 +29,7 @@ to disallow an item from circulating. * *Reference?* flag - The reference? flag in the holdings editor can also be used as a data element in circulation policies. -==== Shelving location data ==== +=== Shelving location data === * To get to the Shelving Locations Editor, navigate to *Administration -> Local Administration -> Shelving Locations Editor*. @@ -51,7 +52,7 @@ image::media/copy_locations_editor.png[screenshot of Shelving Location Editor] * Shelving locations can also be used as a data element in circulation policies. -==== User data ==== +=== User data === Finally, several characteristics of specific patrons can affect circulation policies. You can modify these characteristics in a patron's record (*Search -> @@ -63,7 +64,7 @@ circulation policies. * Other user data that can be used for circulation policies include the *juvenile* flag in the user record. -=== Circulation Rules === +== Circulation Rules == *Loan duration* describes the length of time for a checkout. You can also identify the maximum renewals that can be placed on an item. @@ -101,7 +102,7 @@ When naming these rules, give them a name that clearly identifies what the rule does. This will make it easier to select the correct rule when creating your circ policies. -==== Circulation Limit Sets ==== +=== Circulation Limit Sets === Circulation Limit Sets allow you to limit the maximum number of items for different types of materials that a patron can check out at one time. Evergreen @@ -137,7 +138,7 @@ To create this limit set, you would add 5 to the *Items Out* field, 0 to the *Min Depth* field and select the *Global* flag. Add the DVD, BLURAY and VHS circ modifiers to the limit set. -=== Creating Circulation Policies === +== Creating Circulation Policies == Once you have identified your data elements that will drive circulation policies and have created your circulation rules, you are ready to begin creating your @@ -167,7 +168,7 @@ as the *Item Circ Lib (copy_circ_lib)*. and circulation sets created in the above sets when creating the circulation policy. -==== Best practices for creating policies ==== +=== Best practices for creating policies === * Start by replacing the default consortium-level circ policy with one that contains a majority of your libraries' duration, recurring fine, and max fine @@ -213,7 +214,7 @@ It is still true that "book" and "music" items can be checked out, while "dvd" is not circulated. However, now we have added new rules that state that "Adult" patrons of "SYS1" can circulate "dvd" items. -==== Settings Relevant to Circulation ==== +=== Settings Relevant to Circulation === The following circulation settings, available via *Administration -> Local Administration -> Library Settings Editor*, can diff --git a/docs-antora/modules/admin_initial_setup/pages/describing_your_organization.adoc b/docs-antora/modules/admin_initial_setup/pages/describing_your_organization.adoc index 6281407140..1d0e8f1775 100644 --- a/docs-antora/modules/admin_initial_setup/pages/describing_your_organization.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/describing_your_organization.adoc @@ -1,4 +1,5 @@ -== Describing your organization == += Describing your organization = +:toc: Your Evergreen system is almost ready to go. You'll need to add each of the libraries that will be using your Evergreen system. If you're doing this for a @@ -71,7 +72,7 @@ To create a new dependent organizational unit, click *New Child*. The new child will appear in the hierarchy list below the parent unit. Click on the new unit and edit the data, click *Save* -==== Organizational Unit data ==== +=== Organizational Unit data === The *Addresses* tab allows you to enter library contact information. Library Phone number, email address, and addresses are used in patron email notifications, hold slips, and transit slips. The Library address tab is broken @@ -82,7 +83,7 @@ The *Hours of Operation* tab is where you enter regular, weekly hours. Holiday and other closures are set in the *Closed Dates Editor*. Hours of operation and closed dates impact due dates and fine accrual. -==== After Changing Organization Unit Data ==== +=== After Changing Organization Unit Data === After you change Org Unit data, you must run the autogen.sh script. This script updates the Evergreen organization tree and fieldmapper IDL. diff --git a/docs-antora/modules/admin_initial_setup/pages/describing_your_people.adoc b/docs-antora/modules/admin_initial_setup/pages/describing_your_people.adoc index 46967bfeec..2d8b476bc0 100644 --- a/docs-antora/modules/admin_initial_setup/pages/describing_your_people.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/describing_your_people.adoc @@ -1,4 +1,5 @@ -== Describing your people == += Describing your people = +:toc: Many different members of your staff will use your Evergreen system to perform the wide variety of tasks required of the library. @@ -29,7 +30,7 @@ permissions are typically tied to one or more working location (sometimes referred to as a working organizational unit or work OU) which affects where a particular user can exercise the permissions they have been granted. -=== Setting the staff user's working location === +== Setting the staff user's working location == To grant a working location to a staff user in the staff client: . Search for the patron. Select *Search > Search for Patrons* from the top menu. @@ -49,7 +50,7 @@ the permissions that are given through the *Permission Group* that you assigned to this user. Depending on your own permissions, you may also have the ability to grant individual permissions directly to this user. -=== Comparing approaches for managing permissions === +== Comparing approaches for managing permissions == The Evergreen community uses two different approaches to deal with managing permissions for users: @@ -91,7 +92,7 @@ you can change them as needed. You may set and alter the permissions for each permission group in line with what your library, or possibly your consortium, defines as the appropriate needs for each function in the library. -=== Managing permissions in the staff client === +== Managing permissions in the staff client == In this section, we'll show you in the staff client: * where to find the available permissions @@ -103,7 +104,7 @@ We also provide an appendix with a listing of suggested minimum permissions for some essential groups. You can compare the existing permissions with these suggested permissions and, if any are missing, you will know how to add them. -==== Where to find existing permissions and what they mean ==== +=== Where to find existing permissions and what they mean === In the staff client, in the upper right corner of the screen, click on *Administration > Server Administration > Permissions*. @@ -117,7 +118,7 @@ appear in the Evergreen database. Description is a brief note on what the permission allows. All of the most common permissions have easily understandable descriptions. -==== Where to find existing Permission Groups ==== +=== Where to find existing Permission Groups === In the staff client, in the upper right corner of the screen, navigate to *Administration > Server Administration > Permission Groups*. @@ -131,7 +132,7 @@ expand the tree and see the groups underneath it. You should see the Permission Groups that were listed at the beginning of this chapter. If you do not and you need them, you will have to create them. -==== Adding or removing permissions from a Permission Group ==== +=== Adding or removing permissions from a Permission Group === First, we will remove a permission from the Staff group. . From the list of Permission Groups, click on *Staff*. @@ -164,13 +165,13 @@ Now, we will add the permission we just removed back to the Staff group. If you have saved your changes and you don't see them, you may have to click the Reload button in the upper left side of the staff client screen. -=== Managing role-based permission groups in the staff client === +== Managing role-based permission groups in the staff client == Main permission groups are granted in the staff client through Edit in the patron record using the Main (Profile) Permission Group field. Additional permission groups can be granted using secondary permission groups. [[secondaryperms]] -==== Secondary Group Permissions ==== +=== Secondary Group Permissions === The _Secondary Groups_ button functionality enables supplemental permission groups to be added to staff accounts. The *CREATE_USER_GROUP_LINK* and @@ -180,7 +181,7 @@ feature. In general when creating a secondary permission group do not grant the permission to login to Evergreen. -===== Granting Secondary Permissions Groups ===== +==== Granting Secondary Permissions Groups ==== . Open the account of the user you wish to grant secondary permission group to. @@ -201,7 +202,7 @@ image::media/sup-permissions-3.png[Secondary Permission Group Save] . Click _Save_ in the top right hand corner of the _Edit Screen_ to save the user's account. -===== Removing Secondary Group Permissions ===== +==== Removing Secondary Group Permissions ==== . Open the account of the user you wish to remove the secondary permission group from. . Click _Edit_. . Click _Secondary Groups_, located to the right of the _Main (Profile) Permission Group_. @@ -218,7 +219,7 @@ image::media/sup-permissions-5_web_client.png[Secondary Permissions Group Save] + . Click _Save_ in the top right hand corner of the _Edit Screen_ to save the user's account. -=== Managing role-based permission groups in the database === +== Managing role-based permission groups in the database == While the ability to assign a user to multiple permission groups has existed in Evergreen for years, a staff client interface is not currently available to facilitate the work of the Evergreen administrator. However, if you or members diff --git a/docs-antora/modules/admin_initial_setup/pages/designing_your_catalog.adoc b/docs-antora/modules/admin_initial_setup/pages/designing_your_catalog.adoc index eb5aa1b3af..43b8ffc53c 100644 --- a/docs-antora/modules/admin_initial_setup/pages/designing_your_catalog.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/designing_your_catalog.adoc @@ -1,4 +1,5 @@ -== Designing your catalog == += Designing your catalog = +:toc: When people want to find things in your Evergreen system, they will check the catalog. In Evergreen, the catalog is made available through a web interface, @@ -9,14 +10,14 @@ Template Toolkit. You will see the OPAC sometimes referred to as the _TPAC_. In this chapter, we'll show you how to customize the OPAC, change it from its default configuration, and make it your own. -=== Configuring and customizing the public interface === +== Configuring and customizing the public interface == The public interface is referred to as the TPAC or Template Toolkit (TT) within the Evergreen community. The template toolkit system allows you to customize the look and feel of your OPAC by editing the template pages (.tt2) files as well as the associated style sheets. -==== Locating the default template files ==== +=== Locating the default template files === The default URL for the TPAC on a default Evergreen system is _http://localhost/eg/opac/home_ (adjust _localhost_ to match your hostname or IP @@ -30,7 +31,7 @@ while you are developing your changes, consider using template overrides rather than touching the installed templates until you are ready to commit the changes to a branch. See below for information on template overrides. -==== Mapping templates to URLs ==== +=== Mapping templates to URLs === The mapping for templates to URLs is straightforward. Following are a few examples, where __ is a placeholder for one or more directories that @@ -66,7 +67,7 @@ Example Template Toolkit file: _opac/home.tt2_. ---- Note that file references are relative to the top of the template directory. -==== How to override template files ==== +=== How to override template files === Overrides for template files or TPAC pages go in a directory that parallels the structure of the default templates directory. The overrides then get pulled in @@ -83,7 +84,7 @@ bash$ cp /openils/var/templates/opac/advanced.tt2 \ bash$ vim /openils/var/templates_custom/opac/advanced.tt2 ---- -==== Configuring the custom templates directory in Apache's eg.conf ==== +=== Configuring the custom templates directory in Apache's eg.conf === You now need to teach Apache about the new custom template directory. Edit _/etc/apache2/sites-available/eg.conf_ and add the following __ @@ -111,7 +112,7 @@ Finally, reload the Apache configuration to pick up the changes. You should now be able to see your change at _http://localhost/eg/opac/advanced_ where _localhost_ is the hostname of your Evergreen server. -==== Adjusting colors for your public interface ==== +=== Adjusting colors for your public interface === You may adjust the colors of your public interface by editing the _colors.tt2_ file. The location of this file is in @@ -120,7 +121,7 @@ colors of your public interface, remember to create a custom file in your custom template folder and edit the custom file and not the file located in your default template. -==== Adjusting fonts in your public interface ==== +=== Adjusting fonts in your public interface === Font sizes can be changed in the _colors.tt2_ file located in _/openils/var/templates/opac/parts/css/_. Again, create and edit a custom @@ -129,12 +130,12 @@ template version and not the file in the default template. Other aspects of fonts such as the default font family can be adjusted in _/openils/var/templates/opac/css/style.css.tt2_. -==== Media file locations in the public interface ==== +=== Media file locations in the public interface === The media files (mostly PNG images) used by the default TPAC templates are stored in the repository in _Open-ILS/web/images/_ and installed in _/openils/var/web/images/_. -==== Changing some text in the public interface ==== +=== Changing some text in the public interface === Out of the box, TPAC includes a number of placeholder text and links. For example, there is a set of links cleverly named Link 1, Link 2, and so on in the @@ -195,7 +196,7 @@ these are replaced by the contents of variables passed as extra arguments to the Once the link and link text has been edited to your satisfaction, load the page in a Web browser and see the live changes immediately. -==== Adding translations to PO file ==== +=== Adding translations to PO file === After you have added custom text in translatable form to a TT2 template, you need to add the custom strings and its translations to the PO file containing the translations. Evergreen PO files are stored in _/openils/var/template/data/locale/_ @@ -235,7 +236,7 @@ After making changes, restart Apache to make the changes take effect. As root ru service apache2 restart ---- -==== Adding and removing MARC fields from the record details display page ==== +=== Adding and removing MARC fields from the record details display page === It is possible to add and remove the MARC fields and subfields displayed in the record details page. In order to add MARC fields to be displayed on the details @@ -270,7 +271,7 @@ You can add any MARC field to your record details page. Moreover, this approach can also be used to display MARC fields in other pages, such as your results page. -===== Using bibliographic source variables ===== +==== Using bibliographic source variables ==== For bibliographic records, there is a "bib source" that can be associated with every record. This source and its ID are available as record attributes called @@ -288,7 +289,7 @@ link for these records to point at the vendor website. **** -=== Setting the default physical location for your library environment === +== Setting the default physical location for your library environment == _physical_loc_ is an Apache environment variable that sets the default physical location, used for setting search scopes and determining the order in which @@ -301,7 +302,7 @@ SetEnv physical_loc 104 ---- [#setting_a_default_language_and_adding_optional_languages] -=== Setting a default language and adding optional languages === +== Setting a default language and adding optional languages == _OILSWebLocale_ adds support for a specific language. Add this variable to the Virtual Host section in _/etc/apache2/eg_vhost.conf_. @@ -335,7 +336,7 @@ Below is a table of the currently supported languages packaged with Evergreen: *American English is built into Evergreen so you do not need to set up this language and there are no PO files. -==== Updating translations in Evergreen using current translations from Launchpad ==== +=== Updating translations in Evergreen using current translations from Launchpad === Due to Evergreen release workflow/schedule, some language strings may already have been translated in Launchpad, but are not yet packaged with Evergreen. In such cases, it is possible to manually replace the PO file in @@ -358,7 +359,7 @@ Changes require web server reload to take effect. As root run the command service apache2 restart ---- -=== Change Date Format in Patron Account View === +== Change Date Format in Patron Account View == Libraries with same-day circulations may want their patrons to be able to view the due *time* as well as due date when they log in to their OPAC account. To accomplish this, go to _opac/myopac/circs.tt2_. Find the line that reads: @@ -374,7 +375,7 @@ Replace it with: ---- -=== Including External Content in Your Public Interface === +== Including External Content in Your Public Interface == The public interface allows you to include external services and content in your public interface. These can include book cover images, user reviews, table of @@ -385,7 +386,7 @@ require a subscription. The following are some of the external content services which you can configure in Evergreen. -==== OpenLibrary ==== +=== OpenLibrary === The default install of Evergreen includes OpenLibrary book covers. The settings for this are controlled by the section of @@ -422,7 +423,7 @@ image on the record details page edit the config.tt2 file and change the value of the record.summary.jacket_size. The default value is "medium" and the available options are "small", "medium" and "large." -==== ChiliFresh ==== +=== ChiliFresh === ChiliFresh is a subscription-based service which allows book covers, reviews and social interaction of patrons to appear in your catalog. To activate ChiliFresh, @@ -481,15 +482,15 @@ types to not be considered at all, you can change the "identifier_order" option in opensrf.xml. When the option is present, only the identifier(s) listed will be sent. -==== Obalkyknih.cz ==== +=== Obalkyknih.cz === -===== Setting up Obalkyknih.cz account ===== +==== Setting up Obalkyknih.cz account ==== If your library wishes to use added content provided by Obalkyknih.cz, a service based in the Czech Republic, you have to http://obalkyknih.cz/signup[create an Obalkyknih.cz account]. Please note that the interface is only available in Czech. After logging in your Obalkyknih.cz account, you have to add your IP address and Evergreen server address to your account settings. (In case each library uses an address of its own, all of these addresses have to be added.) -===== Enabling Obalkyknih.cz in Evergreen ===== +==== Enabling Obalkyknih.cz in Evergreen ==== Set obalkyknih_cz.enabled to true in '/openils/var/templates/opac/parts/config.tt2': @@ -527,7 +528,7 @@ An example of how to switch off summaries: ---- -==== Google Analytics ==== +=== Google Analytics === Google Analytics is a free service to collect statistics for your Evergreen site. Statistic tracking is disabled by default through the Evergreen @@ -540,7 +541,7 @@ will need to edit _config.tt2_ in your template. To enable the service set the value of google_analytics.enabled to true and change the value of _google_analytics.code_ to be the code in your Google Analytics account. -==== NoveList ==== +=== NoveList === Novelist is a subscription-based service providing reviews and recommendation for books in you catalog. To activate your Novelist service in Evergreen, open @@ -552,7 +553,7 @@ the Apache configuration file _/etc/apache2/eg_vhost.conf_ and edit the line: You should use the URL provided by NoveList. -==== RefWorks ==== +=== RefWorks === RefWorks is a subscription-based online bibliographic management tool. If you have a RefWorks subscription, you can activate RefWorks in Evergreen by editing @@ -560,7 +561,7 @@ the _config.tt2_ file located in your template directory. You will need to set the _ctx.refworks.enabled_ value to _true_. You may also set the RefWorks URL by changing the _ctx.refworks.url_ setting on the same file. -==== SFX OpenURL Resolver ==== +=== SFX OpenURL Resolver === An OpenURL resolver allows you to find electronic resources and pull them into your catalog based on the ISBN or ISSN of the item. In order to use the SFX @@ -570,7 +571,7 @@ Enable the resolver by changing the value of _openurl.enabled_ to _true_ and change the _openurl.baseurl_ setting to point to the URL of your OpenURL resolver. -==== Syndetic Solutions ==== +=== Syndetic Solutions === Syndetic Solutions is a subscription service providing book covers and other data for items in your catalog. In order to activate Syndetic, edit the @@ -602,7 +603,7 @@ found in bibliographic records: * ISSN -==== Clear External/Added Content Cache ==== +=== Clear External/Added Content Cache === On the catalog's record summary page, there is a link for staff that will forcibly clear the cache of the Added Content for that record. This is helpful for when the Added Content @@ -618,20 +619,20 @@ You will need to reload the record in the staff client to obtain the new images Added Content Supplier. -==== Configure a Custom Image for Missing Images ==== +=== Configure a Custom Image for Missing Images === You can configure a "no image" image other than the standard 1-pixel blank image. The example eg_vhost.conf file provides examples in the comments. Note: Evergreen does not provide default images for these. -=== Including Locally Hosted Content in Your Public Interface === +== Including Locally Hosted Content in Your Public Interface == It is also possible to show added content that has been generated locally by placing the content in a specific spot on the web server. It is possible to have local book jackets, reviews, TOC, excerpts or annotations. -==== File Location and Format ==== +=== File Location and Format === By default the files will need to be placed in directories under */openils/var/web/opac/extras/ac/* on the server(s) that run Apache. @@ -649,7 +650,7 @@ record ID at this time. - others, one of html, xml or json ... html is the default for non-image added content * *recordid* is the bibliographic record id (bre.id). -==== Example ==== +=== Example === If you have some equipment that you are circulating such as a laptop or eBook reader and you want to add an image of the equipment @@ -690,3 +691,26 @@ The system doesn't need the file extension to know what kind of file it is. Reload the bib record summary in the web catalog and your new image will display. +== Styling the searchbar on the homepage == + +The `.searchbar-home` class is added to the div that +contains the searchbar when on the homepage. This allows +sites to customize the searchbar differently on the +homepage than in search results pages, and other places the +search bar appears. For example, adding the following CSS +would create a large, Google-style search bar on the homepage only: + +[source,css] +---- +.searchbar-home .search-box { + width: 80%; + height: 3em; +} + +.searchbar-home #search_qtype_label, +.searchbar-home #search_itype_label, +.searchbar-home #search_locg_label { + display:none; +} +---- + diff --git a/docs-antora/modules/admin_initial_setup/pages/different_styles_for_searchbar.adoc b/docs-antora/modules/admin_initial_setup/pages/different_styles_for_searchbar.adoc deleted file mode 100644 index 08428dd644..0000000000 --- a/docs-antora/modules/admin_initial_setup/pages/different_styles_for_searchbar.adoc +++ /dev/null @@ -1,23 +0,0 @@ -=== Styling the searchbar on the homepage === - -The `.searchbar-home` class is added to the div that -contains the searchbar when on the homepage. This allows -sites to customize the searchbar differently on the -homepage than in search results pages, and other places the -search bar appears. For example, adding the following CSS -would create a large, Google-style search bar on the homepage only: - -[source,css] ----- -.searchbar-home .search-box { - width: 80%; - height: 3em; -} - -.searchbar-home #search_qtype_label, -.searchbar-home #search_itype_label, -.searchbar-home #search_locg_label { - display:none; -} ----- - diff --git a/docs-antora/modules/admin_initial_setup/pages/hard_due_dates.adoc b/docs-antora/modules/admin_initial_setup/pages/hard_due_dates.adoc index 80f454a18b..e2a162f2d5 100644 --- a/docs-antora/modules/admin_initial_setup/pages/hard_due_dates.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/hard_due_dates.adoc @@ -1,10 +1,11 @@ -== Hard due dates == += Hard due dates = +:toc: This feature allows you to specify a specific due date within your circulation policies. This is particularly useful for academic and school libraries, who may wish to make certain items due at the end of a semester or term. NOTE: To work with hard due dates, you will need the CREATE_CIRC_DURATION, UPDATE_CIRC_DURATION, and DELETE_CIRC_DURATION permissions at the _consortium_ level. -=== Creating a hard due date === +== Creating a hard due date == Setting up hard due dates is a two-step process. You must first create a hard due date, and then populate it with specific values. To create a hard due date: diff --git a/docs-antora/modules/admin_initial_setup/pages/importing_via_staff_client.adoc b/docs-antora/modules/admin_initial_setup/pages/importing_via_staff_client.adoc index 32fdaa8464..30a1248afa 100644 --- a/docs-antora/modules/admin_initial_setup/pages/importing_via_staff_client.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/importing_via_staff_client.adoc @@ -1,4 +1,5 @@ -== Importing materials in the staff client == += Importing materials in the staff client = +:toc: Evergreen exists to connect users to the materials represented by bibliographic records, call numbers, and copies -- so getting these materials into your @@ -12,7 +13,7 @@ of getting materials into Evergreen: for large batches of records such as the initial migration from your legacy library system. -=== Staff client batch record imports === +== Staff client batch record imports == The staff client has a utility for importing batches of bibliographic and item records available through *Cataloging > MARC Batch Import/Export*. In addition to importing new records, this interface can be used to match incoming records @@ -25,7 +26,7 @@ in the system.You will also see this name used in several places in the editor. For instance, when you click on the *Record Match Sets*, the title on the screen will be *Vandelay Match Sets*. -==== When to use the MARC Batch Importer ==== +=== When to use the MARC Batch Importer === * When importing in batches of up to 500 to 1,000 records. * When you need the system to match those incoming records to existing records @@ -36,7 +37,7 @@ WARNING: If you are importing items that do not have barcodes or call numbers, y must enable the _Vandelay Generate Default Barcodes_ and _Vandelay Default Barcode Prefix (vandelay.item.barcode.prefix)_ settings. -==== Record Match Sets ==== +=== Record Match Sets === Click the *Record Match Sets* button to identify how Evergreen should match incoming records to existing records in the system. @@ -51,7 +52,7 @@ Common match points used when creating a match set include: * MARC tag 024a (UPC) * MARC tag 028a (Publisher number) -==== Create Match Sets ==== +=== Create Match Sets === . On the *Record Match Sets* screen, click *New Match Set* to create a set of record match points. Give the set a *Name*. Assign the *Owning Library* from the dropdown list. The *Match Set Type* should remain as *biblio*. Click @@ -81,7 +82,7 @@ working points in increasing importance. image::media/create_match_sets.png[Creating a Match Point] . Click *Save Changes to Expression*. -==== Quality Metrics ==== +=== Quality Metrics === * Quality metrics provide a mechanism for Evergreen to measure the quality of records and to make importing decisions based on quality. * Metrics are configured in the match set editor. @@ -92,7 +93,7 @@ records and to make importing decisions based on quality. image::media/record_quality_metrics.png[Quality Metric Grid] -==== Import Item Attributes ==== +=== Import Item Attributes === If you are importing items with your records, you will need to map the data in your holdings tag to fields in the item record. Click the *Holdings Import Profile* button to map this information. @@ -114,7 +115,7 @@ xref:admin:librarysettings.adoc#lse-vandelay[related library settings] to set de image::media/batch_import_profile.png[Partial Screenshot of a Holdings Import Profile] -==== Overlay/Merge Profiles ==== +=== Overlay/Merge Profiles === If Evergreen finds a match for an incoming record in the database, you need to identify which fields should be replaced, which should be preserved, and which should be added to the record. Click the *Merge/Overlay Profiles* button to @@ -144,7 +145,7 @@ You can customize the overlay/merge behavior with a new profile by clicking the You can add multiple tags to these specifications, separating each tag with a comma. -==== Importing the records ==== +=== Importing the records === After making the above configurations, you are now ready to import your records. diff --git a/docs-antora/modules/admin_initial_setup/pages/introduction.adoc b/docs-antora/modules/admin_initial_setup/pages/introduction.adoc index 67166a5b20..575014eb7b 100644 --- a/docs-antora/modules/admin_initial_setup/pages/introduction.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/introduction.adoc @@ -1,4 +1,5 @@ -== Introduction == += Introduction = +:toc: The Evergreen system allows a free range of customizations to every aspect of the system. Use this part of the documentation to become familiar with the tools for configuring the system as well as customizing the catalog and staff client. diff --git a/docs-antora/modules/admin_initial_setup/pages/migrating_patron_data.adoc b/docs-antora/modules/admin_initial_setup/pages/migrating_patron_data.adoc index c6acf2a898..3f5a7f70c1 100644 --- a/docs-antora/modules/admin_initial_setup/pages/migrating_patron_data.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/migrating_patron_data.adoc @@ -1,6 +1,7 @@ -== Migrating Patron Data == += Migrating Patron Data = +:toc: -=== Introduction === +== Introduction == This section will explain the task of migrating your patron data from comma delimited files into Evergreen. It does not deal with the process of exporting @@ -137,7 +138,7 @@ for inactive or active flags. This assumes 1 address per patron. More complex scenarios may require more sophisticated SQL. -=== Creating an sql Script for Importing Patrons === +== Creating an sql Script for Importing Patrons == The procedure for importing patron can be automated with the help of an sql script. Follow these steps to create an import script: @@ -240,7 +241,7 @@ block so that if any sql statements fail, the entire process is canceled and the database is rolled back to its original state. Lines beginning with -- are comments to let you you what each sql statement is doing and are not processed. -=== Batch Updating Patron Data === +== Batch Updating Patron Data == For academic libraries, doing batch updates to add new patrons to the Evergreen database is a critical task. The above procedures and import script can be diff --git a/docs-antora/modules/admin_initial_setup/pages/migrating_your_data.adoc b/docs-antora/modules/admin_initial_setup/pages/migrating_your_data.adoc index 529b94e07c..0c89278b61 100644 --- a/docs-antora/modules/admin_initial_setup/pages/migrating_your_data.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/migrating_your_data.adoc @@ -1,6 +1,7 @@ -== Migrating from a legacy system == += Migrating from a legacy system = +:toc: -=== Introduction === +== Introduction == When you migrate to Evergreen, you generally want to migrate the bibliographic records and item information that existed in your previous library system. For @@ -12,7 +13,7 @@ are comfortable working with SQL to manipulate data within PostgreSQL. If so, then the following section will guide you towards a method of generating common data formats so that you can then load the data into the database in bulk. -=== Making electronic resources visible in the catalog === +== Making electronic resources visible in the catalog == Electronic resources generally do not have any call number or item information associated with them, and Evergreen enables you to easily make bibliographic records visible in the public catalog within sections of the organizational @@ -45,7 +46,7 @@ indicators and subfields for each 856 field in the record, you can proceed to load the records using either the command-line bulk import method or the MARC Batch Importer in the staff client. -=== Migrating your bibliographic records === +== Migrating your bibliographic records == Convert your MARC21 binary records into the MARCXML format, with one record per line. You can use the following Python script to achieve this goal; just install the _pymarc_ library first, and adjust the values of the _input_ and diff --git a/docs-antora/modules/admin_initial_setup/pages/ordering_materials.adoc b/docs-antora/modules/admin_initial_setup/pages/ordering_materials.adoc index a67fc651b1..eac19dd257 100644 --- a/docs-antora/modules/admin_initial_setup/pages/ordering_materials.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/ordering_materials.adoc @@ -1,13 +1,14 @@ -== Ordering materials == += Ordering materials = +:toc: -=== Introduction === +== Introduction == Acquisitions allows you to order materials, track the expenditure of your collections funds, track invoices and set up policies for manual claiming. In this chapter, we're going to be describing how to use the most essential functions of acquisitions in the Evergreen system. -=== When should libraries use acquisitions? === +== When should libraries use acquisitions? == * When you want to track spending of your collections budget. * When you want to use Evergreen to place orders electronically with your vendors. @@ -23,9 +24,9 @@ Below are the basic administrative settings to be configured to get started with acquisitions. At a minimum, a library must configure *Funding Sources*, *Funds*, and *Providers* to use acquisitions. -=== Managing Funds === +== Managing Funds == -==== Funding Sources (Required) ==== +=== Funding Sources (Required) === Funding sources allow you to specify the sources that contribute monies to your fund(s). You can create as few or as many funding sources as you need. These can be used to track exact amounts for accounts in your general ledger. @@ -51,7 +52,7 @@ matching source. hyperlinked name of the funding source and then click the *Apply Credit* button. Add the amount of funds you need to add. The *Note* field is optional. -==== Funds (Required) ==== +=== Funds (Required) === Funds allow you to allocate credits toward specific purchases. They typically are used to track spending and purchases for specific collections. Some libraries may choose to define very broad funds for their collections (e.g. @@ -97,7 +98,7 @@ large generic fund and use that fund for all of your purchases. *Funding Source* from which the allocation will be drawn and then enter an amount for the allocation. The *Note* field is optional. -==== Fund Tags (Optional) ==== +=== Fund Tags (Optional) === You can apply tags to funds so that you can group funds for easy reporting. For example, you have three funds for children’s materials: Children's Board Books, Children's DVDs, and Children's CDs. Assign a fund tag of children's to each @@ -117,9 +118,9 @@ fund. For convenience when propagating or rolling over a fund for a new fiscal year, fund tags will be copied from the current fund to the new year's fund. -=== Ordering === +== Ordering == -==== Providers (Required) ==== +=== Providers (Required) === Providers are the vendors from whom you order titles. . To add a provider record, select *Administration -> Acquisitions Administration -> @@ -128,7 +129,7 @@ Providers are the vendors from whom you order titles. *Provider Name*, *Code*, *Owner*, and *Currency*. You also need to select the *Active* checkbox to use the provider. -==== Distribution Formulas (Optional) ==== +=== Distribution Formulas (Optional) === If you are ordering for a multi-branch library system, distribution formulas are a useful way to specify the number of items that should be distributed to specific branches and item locations. @@ -144,7 +145,7 @@ specific branches and item locations. the right side of the field. . Keep adding entries until the distribution formula is complete. -==== Helpful acquisitions Library Settings ==== +=== Helpful acquisitions Library Settings === There are several acquisitions Library Settings available that will help with acquisitions workflow. These settings can be found at *Administration -> Local Administration -> Library Settings Editor*. @@ -159,7 +160,7 @@ Administration -> Library Settings Editor*. * Temporary call number prefix - Applies a unique prefix to the start of the call number that is automatically generated during the acquisitions process. -==== Preparing for order record loading ==== +=== Preparing for order record loading === If your library is planning to upload order records in a batch, you need to add some information to your provider records so that Evergreen knows how to map the item data contained in the order record. @@ -190,7 +191,7 @@ Is Identifier => false + where 962 is the holdings tag and p is the subfield that contains the PO Name. -==== Preparing to send electronic orders from Evergreen ==== +=== Preparing to send electronic orders from Evergreen === If your library wants to transmit electronic order information to a vendor, you will need to configure your server to use EDI. You need to install the EDI translator and EDI scripts on your server by following the instructions in the diff --git a/docs-antora/modules/admin_initial_setup/pages/troubleshooting_tpac.adoc b/docs-antora/modules/admin_initial_setup/pages/troubleshooting_tpac.adoc index 05c72e0440..fa2530e0ff 100644 --- a/docs-antora/modules/admin_initial_setup/pages/troubleshooting_tpac.adoc +++ b/docs-antora/modules/admin_initial_setup/pages/troubleshooting_tpac.adoc @@ -1,4 +1,5 @@ -== Troubleshooting TPAC errors == += Troubleshooting TPAC errors = +:toc: If there is a problem such as a TT syntax error, it generally shows up as an ugly server failure page. If you check the Apache error logs, you will probably diff --git a/docs-antora/modules/api/nav.adoc b/docs-antora/modules/api/nav.adoc index 0d713e0af1..2ce92424f3 100644 --- a/docs-antora/modules/api/nav.adoc +++ b/docs-antora/modules/api/nav.adoc @@ -1,5 +1,5 @@ * xref:api:introduction.adoc[Getting Data from Evergreen] -** xref:development:data_supercat.adoc[] -** xref:development:data_unapi.adoc[] -** xref:development:data_opensearch.adoc[] +** xref:development:data_supercat.adoc[Using Supercat] +** xref:development:data_unapi.adoc[Using UnAPI] +** xref:development:data_opensearch.adoc[Using Opensearch as a developer] diff --git a/docs-antora/modules/development/nav.adoc b/docs-antora/modules/development/nav.adoc index dd0c451b42..4c9464e4ee 100644 --- a/docs-antora/modules/development/nav.adoc +++ b/docs-antora/modules/development/nav.adoc @@ -1,6 +1,7 @@ * xref:development:introduction.adoc[Developer Resources] -** xref:development:support_scripts.adoc[] -** xref:development:pgtap.adoc[] -** xref:development:intro_opensrf.adoc[] -** xref:development:updating_translations_launchpad.adoc[] +** xref:development:support_scripts.adoc[Support Scripts] +** xref:development:pgtap.adoc[Developing with pgTAP tests] +** xref:development:intro_opensrf.adoc[Easing gently into OpenSRF] +** xref:development:updating_translations_launchpad.adoc[Updating translations +using Launchpad] diff --git a/docs-antora/modules/development/pages/data_opensearch.adoc b/docs-antora/modules/development/pages/data_opensearch.adoc index 218410a380..9e2a1514d7 100644 --- a/docs-antora/modules/development/pages/data_opensearch.adoc +++ b/docs-antora/modules/development/pages/data_opensearch.adoc @@ -1,6 +1,7 @@ -== Using Opensearch as a developer == += Using Opensearch as a developer = +:toc: -=== Introduction === +== Introduction == Evergreen responds to OpenSearch requests. This can be a good way to get search results delivered in a format that you prefer. diff --git a/docs-antora/modules/development/pages/data_supercat.adoc b/docs-antora/modules/development/pages/data_supercat.adoc index 0cea5f52bd..ff4489c9b4 100644 --- a/docs-antora/modules/development/pages/data_supercat.adoc +++ b/docs-antora/modules/development/pages/data_supercat.adoc @@ -1,6 +1,7 @@ -== Using Supercat == += Using Supercat = +:toc: -=== Introduction === +== Introduction == You can use SuperCat to get data about ISBNs, metarecords, bibliographic records, and authority records. @@ -8,7 +9,7 @@ records, and authority records. Throughout this section, replace `` with the domain or subdomain of your Evergreen installation to try these examples on your own system. -=== ISBNs === +== ISBNs == Given one ISBN, Evergreen can return a list of related records and ISBNs, including alternate editions and translations. To use the Supercat @@ -56,9 +57,9 @@ the following list of catalog record IDs and ISBNs: ---------------------------------------------------------------------------- -=== Records === +== Records == -==== Record formats ==== +=== Record formats === First, determine which format you'd like to receive data in. To see the available formats for bibliographic records, visit @@ -110,7 +111,7 @@ data for a given bibliographic record. ============================================================================ -==== Retrieve records ==== +=== Retrieve records === You can retrieve records using URLs in the following format: ---- @@ -197,7 +198,7 @@ returns the following record. ---------------------------------------------------------------------------- -==== Recent records ==== +=== Recent records === SuperCat can return feeds of recently edited or created authority and bibliographic records: @@ -213,7 +214,7 @@ Note the following features: Example: http://gapines.org/opac/extras/feed/freshmeat/atom/biblio/import/10/2008-01-01 -===== Filtering by Org Unit ===== +==== Filtering by Org Unit ==== You can generate a similar list, with the added ability to limit by Org Unit, using the item-age browse axis. @@ -235,7 +236,7 @@ Modifying the 'atom' portion of the URL to 'html-full' will produce an HTML page Example: http://gapines.org/opac/extras/browse/html-full/item-age/ARL-BOG/1/10 -===== Additional Filters ===== +==== Additional Filters ==== If you'd like to limit to a particular status, you can append `?status=0` where `0` is the ID number of the status you'd like to limit to. If a diff --git a/docs-antora/modules/development/pages/data_unapi.adoc b/docs-antora/modules/development/pages/data_unapi.adoc index cd9a27146a..5d6fcb18b4 100644 --- a/docs-antora/modules/development/pages/data_unapi.adoc +++ b/docs-antora/modules/development/pages/data_unapi.adoc @@ -1,6 +1,7 @@ -== Using UnAPI == += Using UnAPI = +:toc: -=== URL format === +== URL format == Evergreen's unAPI support includes access to many record types. For example, the following URL would fetch diff --git a/docs-antora/modules/development/pages/intro_opensrf.adoc b/docs-antora/modules/development/pages/intro_opensrf.adoc index e1be38f374..d512978569 100644 --- a/docs-antora/modules/development/pages/intro_opensrf.adoc +++ b/docs-antora/modules/development/pages/intro_opensrf.adoc @@ -1,6 +1,7 @@ -== Easing gently into OpenSRF == += Easing gently into OpenSRF = +:toc: -=== Abstract === +== Abstract == The Evergreen open-source library system serves library consortia composed of hundreds of branches with millions of patrons - for example, http://www.georgialibraries.org/statelibrarian/bythenumbers.pdf[the Georgia @@ -11,7 +12,7 @@ article introduces OpenSRF, demonstrates how to build OpenSRF services through simple code examples, and explains the technical foundations on which OpenSRF is built. -=== Introducing OpenSRF === +== Introducing OpenSRF == OpenSRF is a message routing network that offers scalability and failover support for individual services and entire servers with minimal development and deployment overhead. You can use OpenSRF to build loosely-coupled applications @@ -48,7 +49,7 @@ of your servers; or if the problem is that your service is resource-hungry, you could add an inexpensive server to your cluster and dedicate it to running that resource-hungry service. -==== Programming language support ==== +=== Programming language support === If you need to develop an entirely new OpenSRF service, you can choose from a number of different languages in which to implement that service. OpenSRF @@ -79,7 +80,7 @@ The recommended option for would-be developers of another language binding is to use the Python implementation as the cleanest basis for a port to another language. -==== OpenSRF communication flows over XMPP ==== +=== OpenSRF communication flows over XMPP === The XMPP messaging service underpins OpenSRF, requiring an XMPP server such as http://www.ejabberd.im/[ejabberd]. When you start OpenSRF, the first XMPP @@ -98,7 +99,7 @@ ID `6285` that has connected to the `private.localhost` domain using the `opensrf@private.localhost/opensrf.simple-text_drone_at_localhost_6285`. [#OpenSRFOverHTTP] -==== OpenSRF communication flows over HTTP ==== +=== OpenSRF communication flows over HTTP === Any OpenSRF service registered with the public router is accessible via the OpenSRF HTTP Translator. The OpenSRF HTTP Translator implements the http://www.open-ils.org/dokuwiki/doku.php?id=opensrf_over_http[OpenSRF-over-HTTP @@ -218,7 +219,7 @@ Evergreen `open-ils.pcrud` public service offers the same functionality as additional authentication and authorization layer in `open-ils.pcrud` prevents unchecked access to Evergreen's data. -==== Stateless and stateful connections ==== +=== Stateless and stateful connections === OpenSRF supports both _stateless_ and _stateful_ connections. When an OpenSRF client issues a `REQUEST` message in a _stateless_ connection, the router @@ -242,7 +243,7 @@ set of database INSERT, UPDATE, and DELETE statements within a transaction. .CONNECT, REQUEST, and DISCONNECT flow in a stateful connection image:media/CONNECT.png[CONNECT, REQUEST, and DISCONNECT flow in a stateful connection] -=== Enough jibber-jabber: writing an OpenSRF service === +== Enough jibber-jabber: writing an OpenSRF service == Imagine an application architecture in which 10 lines of Perl or Python, using the data types native to each language, are enough to implement a method that can then be deployed and invoked seamlessly across hundreds of servers. You @@ -303,7 +304,7 @@ inheritance is available in this package (named by the special Perl symbol procedure is how we introduce a method to the rest of the OpenSRF world. [#serviceRegistration] -==== Registering a service with the OpenSRF configuration files ==== +=== Registering a service with the OpenSRF configuration files === Two files control most of the configuration for OpenSRF: @@ -419,12 +420,12 @@ offers their services via the public router as well as the private router. Once you have defined the new service, you must restart the OpenSRF Router to retrieve the new configuration and start or restart the service itself. -==== Calling an OpenSRF method ==== +=== Calling an OpenSRF method === OpenSRF clients in any supported language can invoke OpenSRF services in any supported language. So let's see a few examples of how we can call our fancy new `opensrf.simple-text.reverse()` method: -===== Calling OpenSRF methods from the srfsh client ===== +==== Calling OpenSRF methods from the srfsh client ==== `srfsh` is a command-line tool installed with OpenSRF that you can use to call OpenSRF methods. To call an OpenSRF method, issue the `request` command and pass the OpenSRF service and method name as the first two arguments; then pass a list @@ -448,7 +449,7 @@ Request Time in seconds: 0.016718 -------------------------------------------------------------------------------- [#opensrfIntrospection] -===== Getting documentation for OpenSRF methods from the srfsh client ===== +==== Getting documentation for OpenSRF methods from the srfsh client ==== The `srfsh` client also gives you command-line access to retrieving metadata about OpenSRF services and methods. For a given OpenSRF method, for example, @@ -527,7 +528,7 @@ implementation. <9> `argc` is an integer describing the minimum number of arguments that must be passed to this method. -===== Calling OpenSRF methods from Perl applications ===== +==== Calling OpenSRF methods from Perl applications ==== To call an OpenSRF method from Perl, you must connect to the OpenSRF service, issue the request to the method, and then retrieve the results. @@ -618,7 +619,7 @@ contains the `length` and `word_count` keys we defined in the method. <10> The `OpenSRF::AppSession->disconnect()` method closes the XMPP client connection and cleans up resources associated with the session. -==== Accepting and returning more interesting data types ==== +=== Accepting and returning more interesting data types === Of course, the example of accepting a single string and returning a single string is not very interesting. In real life, our applications tend to pass @@ -653,7 +654,7 @@ returned to the caller. As a caller of a given method, you must rely on the documentation used to register to determine the data structures - if the developer has added the appropriate documentation. -==== Accepting and returning Evergreen objects ==== +=== Accepting and returning Evergreen objects === OpenSRF is agnostic about objects; its role is to pass JSON back and forth between OpenSRF clients and services, and it allows the specific clients and @@ -810,7 +811,7 @@ the given instance has been deleted, updated, or created respectively. Evergreen can then act in batch mode over the collection to perform the requested actions on any of the instances that have been flagged for action. -==== Returning streaming results ==== +=== Returning streaming results === In the previous implementation of the `opensrf.simple-text.split` method, we returned a reference to the complete array of results. For small values being @@ -867,7 +868,7 @@ connection object on each element of the array. <2> Registering the method as a streaming method instructs OpenSRF to also register an atomic variant (`opensrf.simple-text.split.atomic`). -==== Error! Warning! Info! Debug! ==== +=== Error! Warning! Info! Debug! === As hard as it may be to believe, it is true: applications sometimes do not behave in the expected manner, particularly when they are still under development. The server language bindings for OpenSRF include integrated @@ -934,7 +935,7 @@ To see everything that is happening in OpenSRF, try leaving your logging level set to INTERNAL for a few minutes - just ensure that you have a lot of free disk space available if you have a moderately busy system! -==== Caching results: one secret of scalability ==== +=== Caching results: one secret of scalability === If you have ever used an application that depends on a remote Web service outside of your control-say, if you need to retrieve results from a microblogging service-you know the pain of latency and dependability (or the @@ -986,7 +987,7 @@ entry, with the cache key, value to be stored ("here"), and the timeout value in seconds to ensure that we do not return stale data on subsequent calls -==== Initializing the service and its children: child labour ==== +=== Initializing the service and its children: child labour === When an OpenSRF service is started, it looks for a procedure called `initialize()` to set up any global variables shared by all of the children of the service. The `initialize()` procedure is typically used to retrieve @@ -1003,7 +1004,7 @@ procedure (if any) to clean up any resources associated with the child process. Similarly, when the OpenSRF service is stopped, it calls the `DESTROY()` procedure to clean up any remaining resources. -==== Retrieving configuration settings ==== +=== Retrieving configuration settings === The settings for OpenSRF services are maintained in the `opensrf.xml` XML configuration file. The structure of the XML document consists of a root element `` containing two child elements: @@ -1045,12 +1046,12 @@ libraries locally cache the configuration file to avoid network roundtrips for every request and enable the developer to request specific values without having to manually construct XPath expressions. -=== Getting under the covers with OpenSRF === +== Getting under the covers with OpenSRF == Now that you have seen that it truly is easy to create an OpenSRF service, we can take a look at what is going on under the covers to make all of this work for you. -==== Get on the messaging bus - safely ==== +=== Get on the messaging bus - safely === One of the core innovations of OpenSRF was to use the Extensible Messaging and Presence Protocol (XMPP, more colloquially known as Jabber) as the messaging bus that ties OpenSRF services together across servers. XMPP is an "XML @@ -1078,7 +1079,7 @@ The opensrf and router user names, passwords, and domain names, along with the list of services that should be public, are contained in the `opensrf_core.xml` configuration file. -==== Message body format ==== +=== Message body format === OpenSRF was an early adopter of JavaScript Object Notation (JSON). While XMPP is an XML protocol, the Evergreen developers recognized that the compactness of the JSON format offered a significant reduction in bandwidth for the volume of @@ -1145,7 +1146,7 @@ The content of the `` element of the OpenSRF request and result should look familiar; they match the structure of the <> that we previously dissected. -==== Registering OpenSRF methods in depth ==== +=== Registering OpenSRF methods in depth === Let's explore the call to `__PACKAGE__->register_method()`; most of the elements of the hash are optional, and for the sake of brevity we omitted them in the previous example. As we have seen in the results of the <>, a @@ -1168,7 +1169,7 @@ that you should pass to `__PACKAGE__->register_method()`: *** `desc`: a description of the return value *** `type`: the data type of the return value: for example, string, integer, boolean, number, array, or hash -=== Evergreen-specific OpenSRF services === +== Evergreen-specific OpenSRF services == Evergreen is currently the primary showcase for the use of OpenSRF as an application architecture. Evergreen 2.6.0 includes the following @@ -1232,7 +1233,7 @@ flexibility as OpenSRF services, but have the disadvantage of not being integrated into the same configuration and control infrastructure as the OpenSRF services. -=== Evergreen after one year: reflections on OpenSRF === +== Evergreen after one year: reflections on OpenSRF == http://projectconifer.ca[Project Conifer] has been live on Evergreen for just over a year now, and as one of the primary technologists I have had to work @@ -1240,7 +1241,7 @@ closely with the OpenSRF infrastructure during that time. As such, I am in a position to identify some of the strengths and weaknesses of OpenSRF based on our experiences. -==== Strengths of OpenSRF ==== +=== Strengths of OpenSRF === As a service infrastructure, OpenSRF has been remarkably reliable. We initially deployed Evergreen on an unreleased version of both OpenSRF and Evergreen due @@ -1284,7 +1285,7 @@ to a single server where we can inspect the complete set of messages for the entire cluster in context, rather than trying to piece them together across servers. -==== Weaknesses ==== +=== Weaknesses === The primary weakness of OpenSRF is the lack of either formal or informal documentation for OpenSRF. There are many frequently asked questions on the @@ -1329,7 +1330,7 @@ framework is in place, more developers might be willing to develop and contribute patches as they could sanity check their own code without an intense effort before exposing it to their peers. -=== Summary === +== Summary == In this article, I attempted to provide both a high-level and detailed overview of how OpenSRF works, how to build and deploy new OpenSRF services, how to make requests to OpenSRF method from OpenSRF clients or over HTTP, and why you @@ -1341,7 +1342,7 @@ Conifer after a year in production, with some thoughts about areas where the right application of skills could make a significant difference to the Evergreen and OpenSRF projects. -=== Appendix: Python client === +== Appendix: Python client == Following is a Python client that makes the same OpenSRF calls as the Perl client: diff --git a/docs-antora/modules/development/pages/introduction.adoc b/docs-antora/modules/development/pages/introduction.adoc index 81ea47416f..8fd3a0a5de 100644 --- a/docs-antora/modules/development/pages/introduction.adoc +++ b/docs-antora/modules/development/pages/introduction.adoc @@ -1,4 +1,5 @@ -== Introduction == += Introduction = +:toc: Developers can use this part to learn more about the programming languages, communication protocols and standards used in Evergreen. diff --git a/docs-antora/modules/development/pages/pgtap.adoc b/docs-antora/modules/development/pages/pgtap.adoc index b86fd2f2ad..0b8a15677c 100644 --- a/docs-antora/modules/development/pages/pgtap.adoc +++ b/docs-antora/modules/development/pages/pgtap.adoc @@ -1,6 +1,7 @@ -== Developing with pgTAP tests == += Developing with pgTAP tests = +:toc: -=== Setting up pgTAP on your development server === +== Setting up pgTAP on your development server == Currently, Evergreen pgTAP tests expect a version of pgTAP (0.93) that is not yet available in the packages for most Linux distributions. @@ -19,7 +20,7 @@ Therefore, you will have to install pgTAP from source as follows: CREATE EXTENSION pgtap; ------------------------------------------------------------------------------ -=== Running pgTAP tests === +== Running pgTAP tests == The pgTAP tests can be found in subdirectories of `Open-ILS/src/sql/Pg/` as follows: diff --git a/docs-antora/modules/development/pages/support_scripts.adoc b/docs-antora/modules/development/pages/support_scripts.adoc index 9167894140..04e993cb36 100644 --- a/docs-antora/modules/development/pages/support_scripts.adoc +++ b/docs-antora/modules/development/pages/support_scripts.adoc @@ -1,4 +1,5 @@ -== Support Scripts == += Support Scripts = +:toc: Various scripts are included with Evergreen in the `/openils/bin/` directory (and in the source code in `Open-ILS/src/support-scripts` and @@ -59,7 +60,7 @@ to more thorough documentation, if available. [#authority_control_fields] -=== authority_control_fields: Connecting Bibliographic and Authority records === +== authority_control_fields: Connecting Bibliographic and Authority records == indexterm:[authority control] @@ -97,7 +98,7 @@ Here is how the matching works: [#marc_export] -=== marc_export: Exporting Bibliographic Records into MARC files === +== marc_export: Exporting Bibliographic Records into MARC files == indexterm:[marc_export] indexterm:[MARC records,exporting,using the command line] @@ -144,12 +145,12 @@ cat /home/opensrf/records.txt | ./marc_export --store -i -c /openils/conf/opensr `marc_export` does not output progress as it executes. ==================== -==== Options ==== +=== Options === The *marc_export* support script includes several options. You can find a complete list by running `./marc_export -h`. A few key options are also listed below: -===== --descendants and --library ===== +==== --descendants and --library ==== The `marc_export` script has two related options, `--descendants` and `--library`. Both options take one argument of an organizational unit @@ -170,7 +171,7 @@ All of the specified org. units and their descendants will be included in the output. You can also combine `--library` and `--descendants` options when necessary. -===== --items ===== +==== --items ==== The `--items` option will add an 852 field for every relevant item to the MARC record. This 852 field includes the following information: @@ -193,18 +194,18 @@ record. This 852 field includes the following information: |=================================== -===== --since ===== +==== --since ==== You can use the `--since` option to export records modified after a certain date and time. -===== --store ===== +==== --store ==== By default, marc_export will use the reporter storage service, which should work in most cases. But if you have a separate reporter database and you know you want to talk directly to your main production database, then you can set the `--store` option to `cstore` or `storage`. -===== --uris ===== +==== --uris ==== The `--uris` option (short form: `-u`) allows you to export records with located URIs (i.e. electronic resources). When used by itself, it will export only records that have located URIs. When used in conjunction with `--items`, @@ -217,7 +218,7 @@ holdings both physical and electronic. [#pingest_pl] -=== Parallel Ingest with pingest.pl === +== Parallel Ingest with pingest.pl == indexterm:[pgingest.pl] indexterm:[MARC records,importing,using the command line] @@ -234,7 +235,7 @@ NOTE: The browse ingest is presently done in a single process over all of the input records as it cannot run in parallel with itself. It does, however, run in parallel with the other ingests. -==== Command Line Options ==== +=== Command Line Options === pingest.pl accepts the following command line options: @@ -308,7 +309,7 @@ SELECT reporter.refresh_materialized_simple_record(); [#importing_authority_records_from_command_line] -=== Importing Authority Records from Command Line === +== Importing Authority Records from Command Line == indexterm:[marc2are.pl] indexterm:[pg_loader.pl] @@ -358,7 +359,7 @@ that command looks like: psql -U evergreen -h localhost -d evergreen -f pg_loader-output.sql ---- -=== Juvenile-to-adult batch script === +== Juvenile-to-adult batch script == The batch `juv_to_adult.srfsh` script is responsible for toggling a patron from juvenile to adult. It should be set up as a cron job. @@ -368,7 +369,7 @@ library setting named "Juvenile Age Threshold" (`global.juvenile_age_threshold`) When no library setting value is present at a given patron's home library, the value passed in to the script will be used as a default. -=== MARC Stream Importer === +== MARC Stream Importer == indexterm:[MARC records,importing,using the command line] diff --git a/docs-antora/modules/development/pages/updating_translations_launchpad.adoc b/docs-antora/modules/development/pages/updating_translations_launchpad.adoc index c3dca9badd..9b177395f9 100644 --- a/docs-antora/modules/development/pages/updating_translations_launchpad.adoc +++ b/docs-antora/modules/development/pages/updating_translations_launchpad.adoc @@ -1,10 +1,11 @@ -== Updating translations using Launchpad == += Updating translations using Launchpad = +:toc: This document describes how to update the translations in an Evergreen branch by pulling them from Launchpad, as well as update the files to be translated in Launchpad by updating the POT files in the Evergreen master branch. -=== Prerequisites === +== Prerequisites == You must install all of the Python prerequisites required for building translations, per http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-admin:customizations:i18n @@ -16,7 +17,7 @@ http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-admin:customizations:i18 * http://pypi.python.org/pypi/simplejson/[simplejson] * http://lxml.de/[lxml] -=== Updating the translations === +== Updating the translations == . Check out the latest translations from Launchpad by branching the Bazaar repository: diff --git a/docs-antora/modules/opac/nav.adoc b/docs-antora/modules/opac/nav.adoc index 4790f38a2a..aa2e6a3214 100644 --- a/docs-antora/modules/opac/nav.adoc +++ b/docs-antora/modules/opac/nav.adoc @@ -1,12 +1,14 @@ * xref:opac:introduction.adoc[Using the Public Access Catalog] -** xref:opac:using_the_public_access_catalog.adoc[] -** xref:opac:my_lists.adoc[] -** xref:opac:batch_actions_from_search.adoc[] -** xref:opac:kids_opac.adoc[] -** xref:opac:catalog_browse.adoc[] -** xref:opac:advanced_features.adoc[] -** xref:opac:tpac_meta_record_holds.adoc[] -** xref:opac:linked_libraries.adoc[] -** xref:opac:opensearch.adoc[] -** xref:opac:search_form.adoc[] +** xref:opac:using_the_public_access_catalog.adoc[Using the Public Access +Catalog] +** xref:opac:my_lists.adoc[My Lists] +** xref:opac:batch_actions_from_search.adoc[Batch Actions from Search] +** xref:opac:kids_opac.adoc[Kids OPAC] +** xref:opac:catalog_browse.adoc[Catalog Browse] +** xref:opac:advanced_features.adoc[Bibliographic Search Enhancements] +** xref:opac:tpac_meta_record_holds.adoc[TPAC Metarecord Search and Metarecord +Level Holds] +** xref:opac:linked_libraries.adoc[Library Information Pages] +** xref:opac:opensearch.adoc[Adding Evergreen Search to Web Browsers] +** xref:opac:search_form.adoc[Adding an Evergreen search form to a web page] diff --git a/docs-antora/modules/opac/pages/advanced_features.adoc b/docs-antora/modules/opac/pages/advanced_features.adoc index 259c4408b9..af27cf697c 100644 --- a/docs-antora/modules/opac/pages/advanced_features.adoc +++ b/docs-antora/modules/opac/pages/advanced_features.adoc @@ -1,14 +1,15 @@ -== Bibliographic Search Enhancements == += Bibliographic Search Enhancements = +:toc: Enhancements to the bibliographic search function enable you to search for records that were created, edited, or deleted within a date range. You can use the catalog interface or the record feed to search for records with specific date ranges. Note that all dates should be formatted as YYYY-MM-DD and should be included in parentheses. -=== Use the Catalog to Retrieve Records with Specified Date Ranges: === +== Use the Catalog to Retrieve Records with Specified Date Ranges: == -==== Search by Create Date or Range ==== +=== Search by Create Date or Range === To find records that were created on or after a specific date, enter the term, create_date, and the date in the catalog search field. For example, to find records that were created on or after April 1, 2013, enter the following into the catalog search field: @@ -24,7 +25,7 @@ create_date(2013-04-01,2013-04-08) -==== Search by Edit Date or Range ==== +=== Search by Edit Date or Range === To find records that were edited on or before a specific date, enter the term, edit-date, and the date in the catalog search field. The date should be preceded by a comma. For example, to find records that were edited on or before April 1, 2013, enter the following into the catalog search field: @@ -47,7 +48,7 @@ edit_date(2013-04-01,2013-04-08) -==== Search by Deleted Status ==== +=== Search by Deleted Status === To search for deleted records, enter in your catalog search field the term, edit_date, the date that you want to search, and the term, #deleted. For example, to find records that were deleted on or after April 1, 2013, enter the following into the catalog search field: @@ -63,7 +64,7 @@ edit_date(2013-04-01,2013-04-08)#deleted -=== Use a Feed to Retrieve Records with Specified Date Ranges: === +== Use a Feed to Retrieve Records with Specified Date Ranges: == You can use a feed to retrieve records that were created, edited, or deleted within specific date ranges by adding the dates to the catalog's URL. You can do this manually, or you can write a script that would automatically retrieve this information. diff --git a/docs-antora/modules/opac/pages/batch_actions_from_search.adoc b/docs-antora/modules/opac/pages/batch_actions_from_search.adoc index bfa08a69e4..c7da7bb19e 100644 --- a/docs-antora/modules/opac/pages/batch_actions_from_search.adoc +++ b/docs-antora/modules/opac/pages/batch_actions_from_search.adoc @@ -1,12 +1,13 @@ [#batch_actions_from_search] -== Batch Actions from Search == += Batch Actions from Search = +:toc: -=== Introduction === +== Introduction == The public catalog and staff interface display checkboxes on the search results pages, both for bibliographic records and metarecord constituents. Selecting one or more titles with these checkboxes adds the titles to a basket, which is viewable on the search bar as an icon. Users can then take a variety of actions on titles within the basket: place holds, print or email title details, add the items to a permanent list (from the public catalog) or add the titles to a bucket (from the staff interface). -=== Using Batch Actions from Search in the Public Catalog === +== Using Batch Actions from Search in the Public Catalog == . Perform a search in the public catalog and retrieve a list of results. + @@ -30,7 +31,7 @@ image::media/BatchActionsSearch-02.png[Basket Actions Drop-down] image::media/BatchActionsSearch-03.png[Details of Basket Actions Drop-down] -==== Actions Initiated with the Basket Actions Drop-down ==== +=== Actions Initiated with the Basket Actions Drop-down === * *View Basket* - This opens the basket in a new screen. Checkboxes allow for the selection of one or more titles within the basket. A drop-down menu appears above the list of titles that can be used to place holds, print title details, email title details, or remove titles from the basket. This menu reads _Actions for these items_. (See the next section for more information about this menu.) * *Place Hold* - This allows for placement of holds in batch for all of the items in the basket. If not already authenticated, users will be asked to login. Once authenticated, the holds process begins for all titles within the basket. Users can set _Advanced Hold Options_ for each title, as well as set the pickup location, hold notification and suspend options. @@ -43,12 +44,12 @@ image::media/BatchActionsSearch-03.png[Details of Basket Actions Drop-down] * *Clear Basket* - This removes removes all titles from the basket -==== View Basket -> _Actions for These Items_ Drop-down Menu ==== +=== View Basket -> _Actions for These Items_ Drop-down Menu === Most actions described above can be taken on titles from within the basket with the _Actions for these items_ drop-down menu. This menu offers additional flexibility, as users can select some or all of the individual titles in the basket on which to place holds, print or email details, or remove from the basket. Users cannot add titles to permanent lists with this menu. image::media/BatchActionsSearch-04.png[Actions for These Items Drop-down Menu] -=== Using Batch Actions from Search in the Staff Interface === +== Using Batch Actions from Search in the Staff Interface == . Perform a search in the staff interface and retrieve a list of results. + @@ -70,7 +71,7 @@ image::media/BatchActionsSearch-02.png[Basket Actions Drop-down] image::media/BatchActionsSearch-03.png[Details of Basket Actions Drop-down] -==== Actions Initiated with the Basket Actions Drop-down ==== +=== Actions Initiated with the Basket Actions Drop-down === * *View Basket* - This opens the basket in a new screen. Checkboxes allow for the selection of one or more titles within the basket. A drop-down menu appears above the list of titles that can be used to place holds, print title details, email title details, or remove titles from the basket. This menu reads _Actions for these items_. (See the next section for more information about this menu.) @@ -90,11 +91,11 @@ image::media/BatchActionsSearch-06.png[Add Basket Titles to Bucket] * *Clear Basket* - removes all items from the basket -==== View Basket -> Actions for These Items Drop-down Menu ==== +=== View Basket -> Actions for These Items Drop-down Menu === Most of the basket actions can be taken on titles from within the basket with the _Actions for these items_ drop-down menu. This menu offers additional flexibility, as staff can select some or all of the individual titles within the basket on which to place holds, print or email details, or remove from the basket. Staff cannot place titles in Records Buckets from this menu. -=== Additional Information === +== Additional Information == The basket used to be called a *Temporary List* in previous versions of Evergreen. diff --git a/docs-antora/modules/opac/pages/catalog_browse.adoc b/docs-antora/modules/opac/pages/catalog_browse.adoc index 288fd43888..85b8c8178b 100644 --- a/docs-antora/modules/opac/pages/catalog_browse.adoc +++ b/docs-antora/modules/opac/pages/catalog_browse.adoc @@ -1,4 +1,5 @@ -== Catalog Browse == += Catalog Browse = +:toc: *Abstract* diff --git a/docs-antora/modules/opac/pages/introduction.adoc b/docs-antora/modules/opac/pages/introduction.adoc index 159087776c..4c2e5e7f9e 100644 --- a/docs-antora/modules/opac/pages/introduction.adoc +++ b/docs-antora/modules/opac/pages/introduction.adoc @@ -1,4 +1,5 @@ -== Introduction == += Introduction = +:toc: Evergreen has a public OPAC that meets WCAG guidelines (http://www.w3.org/WAI/intro/wcag), which helps make the OPAC accessible to diff --git a/docs-antora/modules/opac/pages/kids_opac.adoc b/docs-antora/modules/opac/pages/kids_opac.adoc index 9f4e6dbdd0..8cd50373f2 100644 --- a/docs-antora/modules/opac/pages/kids_opac.adoc +++ b/docs-antora/modules/opac/pages/kids_opac.adoc @@ -1,6 +1,7 @@ -== Kids OPAC == += Kids OPAC = +:toc: -=== Introduction === +== Introduction == The Kids OPAC (KPAC) is a public catalog search that was designed for children and teens. Colorful menu items,large buttons, and simple navigation make this @@ -11,7 +12,7 @@ as the Template Toolkit OPAC (TPAC), the adult catalog search, so you can easily extend the KPAC using the code that already exists in the TPAC. Finally, third party content, such as reader reviews, can be integrated into the KPAC. -=== Choose a Skin === +== Choose a Skin == Two skins, or design interfaces, have been created for the KPAC. The KPAC was designed to run multiple skins on a single web server. A consortium, then, could @@ -37,7 +38,7 @@ After you login, the Login button disappears. image::media/Kids_OPAC2.jpg[Kids_OPAC2] -=== Search the Catalog === +== Search the Catalog == You can search the catalog using only the search bar, the search grid, or the search bar and the collection drop down menu. @@ -112,7 +113,7 @@ image::media/Kids_OPAC7.jpg[Kids_OPAC7] -=== Place a Hold === +== Place a Hold == From the search results, click the *Get it!* link to place a hold. @@ -138,7 +139,7 @@ image::media/Kids_OPAC13.jpg[Kids_OPAC13] -=== Save Items to a List === +== Save Items to a List == You can save items to a temporary list, or, if you are logged in, you can save to a list of your own creation. To save items to a list, click the *Get it* button @@ -163,7 +164,7 @@ image::media/Kids_OPAC15.jpg[Kids_OPAC15] -=== Third Party Content === +== Third Party Content == Third party content, such as reader reviews, can be viewed in the Kids OPAC. The reviews link appears adjacent to the brief information. @@ -184,7 +185,7 @@ copy information. image::media/Kids_OPAC10.jpg[Kids_OPAC10] -=== Configuration Files === +== Configuration Files == Configuration files allow you to define labels for canned searches in the icon grid, determine how icons lead users to new pages, and define whether those icons diff --git a/docs-antora/modules/opac/pages/linked_libraries.adoc b/docs-antora/modules/opac/pages/linked_libraries.adoc index dd771638d3..0e19f15533 100644 --- a/docs-antora/modules/opac/pages/linked_libraries.adoc +++ b/docs-antora/modules/opac/pages/linked_libraries.adoc @@ -1,4 +1,5 @@ -== Library Information Pages == += Library Information Pages = +:toc: The branch name displayed in the copy details section of the search results page, the record summary page, and the kids catalog record summary page will diff --git a/docs-antora/modules/opac/pages/my_account.adoc b/docs-antora/modules/opac/pages/my_account.adoc index fdad57a63a..2cb559c712 100644 --- a/docs-antora/modules/opac/pages/my_account.adoc +++ b/docs-antora/modules/opac/pages/my_account.adoc @@ -2,7 +2,7 @@ [#my_account] -=== My Account === +== My Account == // ``First Login Password Update'' the following documentation comes from JSPAC // as of 2013-03-12 this feature did not exist in EG 2.4 TPAC, @@ -68,7 +68,7 @@ If using a public computer be sure to log out! [#password_reset] -==== Password Reset ==== +=== Password Reset === indexterm:[my account, password reset] @@ -104,7 +104,7 @@ password_ field and re-enter it in the _Re-enter new password_ field. . Login to your account with your new password. -==== Account Summary ==== +=== Account Summary === indexterm:[my account, account summary] @@ -233,7 +233,7 @@ there is no way for a patron to recover those data. After changing any of these settings, you must click _Save_ to store your preferences. -===== Authorize other people to use your account ===== +==== Authorize other people to use your account ==== indexterm:[Allow others to use my account] indexterm:[checking out,materials on another patron's account] @@ -253,7 +253,7 @@ information will also be visible to circulation staff at your library. indexterm:[holds, preferred pickup location] -==== Patron Messages ==== +=== Patron Messages === The Patron Message Center provides a way for libraries to communicate with patrons through messages that can be accessed through the patron's OPAC account. @@ -284,7 +284,7 @@ image::media/message_center12.PNG[Message Center 12] NOTE: Patron deleted messages will still appear in the patron's account in the staff client under Other -> Message Center. -==== Reservations ==== +=== Reservations === When patrons place a reservation for a particular item at a particular time, they can check on its status using the *Reservations* tab. diff --git a/docs-antora/modules/opac/pages/my_lists.adoc b/docs-antora/modules/opac/pages/my_lists.adoc index 8ee6550c37..5be9c21e41 100644 --- a/docs-antora/modules/opac/pages/my_lists.adoc +++ b/docs-antora/modules/opac/pages/my_lists.adoc @@ -1,4 +1,5 @@ -== My Lists == += My Lists = +:toc: The *My Lists* feature replaces the bookbag feature that was available in versions prior to 2.2. The *My Lists* feature is a part of the Template Toolkit OPAC that is available in version 2.2. This feature enables you to create temporary and permanent lists; create and edit notes for items in lists; place holds on items in lists; and share lists via RSS feeds and CSV files. @@ -8,7 +9,7 @@ As of version 3.2, xref:opac:batch_actions_from_search.adoc#batch_actions_from_s image::media/My_Lists.png[My Lists] -=== Create New Lists === +== Create New Lists == 1) Log in to your account in the OPAC. @@ -45,7 +46,7 @@ image::media/My_Lists7.jpg[Share, Delete, Download List] 16) When you no longer need a list, click *Delete List*. -=== Local Call Number in My Lists === +== Local Call Number in My Lists == When a title is added to a list in the TPAC, a local call number will be displayed in the list to assist patrons in locating the physical item. Evergreen will look at the following locations to identify the most relevant call number to display in the list: @@ -61,7 +62,7 @@ The local call number and associated library location will appear in the list: image::media/my_list_call_numbers.png[Local Call Number in List] -=== My Lists Preferences === +== My Lists Preferences == Patrons can adjust the number of lists or list items displayed in a page. This setting can be found under the *Account Preferences* tab, in the *My Lists Preferences* section. diff --git a/docs-antora/modules/opac/pages/new_skin_customizations.adoc b/docs-antora/modules/opac/pages/new_skin_customizations.adoc index 8bbfb58471..2e7872966e 100644 --- a/docs-antora/modules/opac/pages/new_skin_customizations.adoc +++ b/docs-antora/modules/opac/pages/new_skin_customizations.adoc @@ -1,12 +1,13 @@ -== Creating a New Skin: the Bare Minimum == += Creating a New Skin: the Bare Minimum = +:toc: -=== Introduction === +== Introduction == When you adopt the TPAC as your catalog, you must create a new skin. This involves a combination of overriding template files and setting Apache directives to control the look and feel of your customized TPAC. -=== Apache directives === +== Apache directives == There are a few Apache directives and environment variables of note for customizing TPAC behavior. These directives should generally live within a `` section of your Apache configuration. @@ -31,7 +32,7 @@ PerlAddVar OILSWebDefaultLocale "fr-CA" SetEnv physical_loc 104 ------------------------------------------------------------------------------ -=== Customizing templates === +== Customizing templates == When you install Evergreen, the TPAC templates include many placeholder images, text, and links. You should override most of these to provide your users with a custom experience that matches your library. Following is a list of templates diff --git a/docs-antora/modules/opac/pages/opensearch.adoc b/docs-antora/modules/opac/pages/opensearch.adoc index 0702324c22..18883cd1e1 100644 --- a/docs-antora/modules/opac/pages/opensearch.adoc +++ b/docs-antora/modules/opac/pages/opensearch.adoc @@ -1,6 +1,7 @@ -== Adding Evergreen Search to Web Browsers == += Adding Evergreen Search to Web Browsers = +:toc: -=== Adding OpenSearch to Firefox browser === +== Adding OpenSearch to Firefox browser == OpenSearch is a collection of simple formats for the sharing of search results. More information about OpenSearch can be found on their diff --git a/docs-antora/modules/opac/pages/search_form.adoc b/docs-antora/modules/opac/pages/search_form.adoc index b56c6d6954..6cc3997241 100644 --- a/docs-antora/modules/opac/pages/search_form.adoc +++ b/docs-antora/modules/opac/pages/search_form.adoc @@ -1,13 +1,14 @@ -== Adding an Evergreen search form to a web page == += Adding an Evergreen search form to a web page = +:toc: -=== Introduction === +== Introduction == To enable users to quickly search your Evergreen catalog, you can add a simple search form to any HTML page. The following code demonstrates how to create a quick search box suitable for the header of your web site: -=== Simple search form === +== Simple search form == [source,html] ------------------------------------------------------------------------------ @@ -29,7 +30,7 @@ site: wish to anchor your search. This is the value of the ''locg'' parameter in your normal search. -=== Advanced search form === +== Advanced search form == [source,html] -------------------------------------------------------------------------------- @@ -74,17 +75,17 @@ site: -------------------------------------------------------------------------------- -=== Encoding === +== Encoding == For non English characters it is vital to set the attribute `accept-charset="UTF-8"` in the form tag (as in the examples above). If the parameter is not set, records with non English characters will not be retrieved. -=== Setting the document type === +== Setting the document type == You can set the document types to be searched using the attribute `option value=` in the form. For the value use MARC 21 code defining the type of record (i.e. https://www.loc.gov/marc/bibliographic/bdleader.html[Leader, position 06]). For example, for musical recordings you could use `` -=== Setting the library === +== Setting the library == Instead of searching the entire consortium, you can set the Library to be searched in using the attribute `option value=` in the form. For the value use Evergreen database.organization unit ID. diff --git a/docs-antora/modules/opac/pages/search_url.adoc b/docs-antora/modules/opac/pages/search_url.adoc index 36cb3664c3..d6ea158d3c 100644 --- a/docs-antora/modules/opac/pages/search_url.adoc +++ b/docs-antora/modules/opac/pages/search_url.adoc @@ -1,4 +1,4 @@ -=== Search URL === +== Search URL == indexterm:[search, URL] @@ -12,11 +12,11 @@ Here is a basic search URL structure: +++[hostname]+++/eg/opac/results?query=[search term]&**qtype**=keyword&fi%3Aitem_type=&**locg**=[location id] -==== locg Parameter ==== +=== locg Parameter === This is the id of the search location. It is an integer and matches the id of the location the user selected in the location drop down menu. -==== qtype Parameter ==== +=== qtype Parameter === The _qtype_ parameter in the URL represents the search type values and represent one of the following search or request types: @@ -31,7 +31,7 @@ one of the following search or request types: These match the options in the search type drop-down box. -==== Sorting ==== +=== Sorting === The _sort_ parameter sorts the results on one of these criteria. diff --git a/docs-antora/modules/opac/pages/sitemap.adoc b/docs-antora/modules/opac/pages/sitemap.adoc index fdfa23cca5..d66d246b22 100644 --- a/docs-antora/modules/opac/pages/sitemap.adoc +++ b/docs-antora/modules/opac/pages/sitemap.adoc @@ -1,4 +1,5 @@ -== Sitemap generator == += Sitemap generator = +:toc: A http://www.sitemaps.org[sitemap] directs search engines to the pages of interest in a web site so that the search engines can intelligently crawl diff --git a/docs-antora/modules/opac/pages/tpac_meta_record_holds.adoc b/docs-antora/modules/opac/pages/tpac_meta_record_holds.adoc index 5d7f7c2e50..59a548009a 100644 --- a/docs-antora/modules/opac/pages/tpac_meta_record_holds.adoc +++ b/docs-antora/modules/opac/pages/tpac_meta_record_holds.adoc @@ -1,4 +1,5 @@ -== TPAC Metarecord Search and Metarecord Level Holds == += TPAC Metarecord Search and Metarecord Level Holds = +:toc: Metarecords are compilations of individual bibliographic records that represent the same work. This compilation allows for several records to be represented on diff --git a/docs-antora/modules/opac/pages/using_the_public_access_catalog.adoc b/docs-antora/modules/opac/pages/using_the_public_access_catalog.adoc index 78f97a204c..c16386c5a4 100644 --- a/docs-antora/modules/opac/pages/using_the_public_access_catalog.adoc +++ b/docs-antora/modules/opac/pages/using_the_public_access_catalog.adoc @@ -1,6 +1,7 @@ -== Using the Public Access Catalog == += Using the Public Access Catalog = +:toc: -=== Basic Search === +== Basic Search == indexterm:[OPAC] @@ -50,7 +51,7 @@ To search an item copy call number, use <> ============= -==== Formats ==== +=== Formats === You can limit your search by formats based on MARC fixed field type: @@ -86,7 +87,7 @@ indexterm:[formats, music] * *VHS* -===== Libraries ===== +==== Libraries ==== If you are using a catalogue in a library or accessing a library’s online catalogue from its homepage, the search will return items for your local @@ -94,7 +95,7 @@ library. If your library has multiple branches, the result will display items available at your branch and all branches of your library system separately. -=== Advanced Search === +== Advanced Search == Advanced searches allow users to perform more complex searches by providing more options. Many kinds of searches can be performed from the _Advanced Search_ @@ -107,7 +108,7 @@ search options, use _Add Search Row_ button to add more search input rows. Clicking the _X_ button will close the search input row. -==== Sort Results ==== +=== Sort Results === indexterm:[advanced search, sort results] @@ -116,7 +117,7 @@ By default, the search results are in order of greatest to least relevance, see to order the search results by relevance, title, author, or publication date. -==== Search Library ==== +=== Search Library === indexterm:[advanced search, search library] @@ -126,7 +127,7 @@ only. If your library system has multiple branches, use the _Search Library_ box to select different branches or the whole library system. -==== Limit to Available ==== +=== Limit to Available === indexterm:[advanced search, limit to available] @@ -135,7 +136,7 @@ This checkbox is at the bottom line of _Search Library_. Select _Limit to Available_ to limit results to those titles that have items with a circulation status of "available" (by default, either _Available_ or _Reshelving_). -==== Exclude Electronic Resources ==== +=== Exclude Electronic Resources === indexterm:[advanced search, exclude electronic resources] @@ -154,7 +155,7 @@ the 'ctx.exclude_electronic_checkbox' setting in config.tt2 to 1. =============== -==== Search Filter ==== +=== Search Filter === indexterm:[advanced search, search filters] @@ -168,7 +169,7 @@ For each filter type, you may select multiple criteria by holding down the _CTRL_ key as you click on the options. If nothing is selected for a filter, the search will return results as though all options are selected. -===== Search Filter Enhancements ===== +==== Search Filter Enhancements ==== Enhancements to the Search Filters now makes it easier to view, remove, and modify search filters while viewing search results in the Evergreen OPAC. Filters that are selected while conducting an advanced search in the Evergreen OPAC now appear below the search box in the search results interface. @@ -186,7 +187,7 @@ Each filter can be removed by clicking the X next to the filter name to modify t [#numeric_search] indexterm:[advanced search, numeric search] -==== Numeric Search ==== +=== Numeric Search === If you have details on the exact item you wish to search for, use the _Numeric Search_ tab on the advanced search page. Use the drop-down menu to select your @@ -194,7 +195,7 @@ search by _ISBN_, _ISSN_, _Bib Call Number_, _Call Number (Shelf Browse)_, _LCCN_, _TCN_, or _Item Barcode_. Enter the information and then click the _Search_ button. -==== Expert Search ==== +=== Expert Search === indexterm:[advanced search, expert search] @@ -213,7 +214,7 @@ an expert search for "245 a Gone with the wind", simply do a regular title search for "Gone with the wind". ============= -=== Boolean operators === +== Boolean operators == indexterm:[search, AND operator] indexterm:[search, OR operator] @@ -249,7 +250,7 @@ might require it, using symbolic operators as follows: | NOT | `-`_term_ | `a -b` |================================= -=== Search Tips === +== Search Tips == indexterm:[search, stop words] indexterm:[search, truncation] @@ -317,7 +318,7 @@ truncate any number of characters. (example: _environment* agency_) -=== Search Methodology === +== Search Methodology == [#stemming] @@ -351,7 +352,7 @@ _golden_. [#order_of_results] -==== Order of Results ==== +=== Order of Results === indexterm:[search, order of results] @@ -368,7 +369,7 @@ can also re-order your search results using the _Sort Results_ dropdown list on the search result screen. -=== Search Results === +== Search Results == indexterm:[search results] @@ -407,7 +408,7 @@ the _Show More Details_ link. Clicking an entry on the list will re-sort your search results accordingly. -==== Facets: Subjects, Authors, and Series ==== +=== Facets: Subjects, Authors, and Series === indexterm:[search results, facets: subjects, authors, and series] @@ -420,7 +421,7 @@ your original results before the facet was activated. image::media/catalogue-5.png[catalogue-5] -==== Availability ==== +=== Availability === indexterm:[search results, availability] @@ -441,7 +442,7 @@ next to the _Limit to available items_ check box, to view each search result's copies' individual call number, status, and shelving location. -==== Viewing a record ==== +=== Viewing a record === indexterm:[search results, viewing a record] @@ -452,7 +453,7 @@ options for placing holds, add to my list, and print/email. image::media/catalogue-8.png[catalogue-8] image::media/catalogue-8a.png[catalogue-8a] -=== Details === +== Details == indexterm:[search results, details] @@ -538,7 +539,7 @@ The record summary page offers a link to a shorter permalink that image::media/using-opac-view-permalink.png[Permalink] -==== SMS Call Number ==== +=== SMS Call Number === If configured by the library system administrator, you may send yourself the call number via SMS message by clicking on the *Text* link, which appears beside diff --git a/docs-antora/modules/opac/pages/visibility_on_the_web.adoc b/docs-antora/modules/opac/pages/visibility_on_the_web.adoc index b5f04c68b1..d1fcb6183f 100644 --- a/docs-antora/modules/opac/pages/visibility_on_the_web.adoc +++ b/docs-antora/modules/opac/pages/visibility_on_the_web.adoc @@ -1,6 +1,7 @@ -== Library visibility on the Web == += Library visibility on the Web = +:toc: -=== Introduction === +== Introduction == Evergreen follows a number of best practices to make Library data integrate with the rest of the @@ -11,7 +12,7 @@ collections. Evergreen is also preparing for an eventual shift toward linked open bibliographic data. -=== Catalog data in search engines === +== Catalog data in search engines == Each record in the catalog is displayed to search engines using http://schema.org[schema.org] microdata. @@ -23,7 +24,7 @@ These files restrict search engines, up to the point of not allowing search engines to index your site at all. -==== Details of the schema.org mapping ==== +=== Details of the schema.org mapping === * Each item is listed as a http://schema.org/Offer[schema:Offer], which is @@ -60,7 +61,7 @@ site at all. http://schema.org/exampleOfWork[schema:exampleOfWork]. -==== Viewing microdata ==== +=== Viewing microdata === You can learn more about how Evergreen publicizes these data by viewing them directly. The http://linter.structured-data.org[structured data linter] @@ -75,7 +76,7 @@ is a helpful tool for viewing microdata. into the text box. . Click _Submit_ -==== Other helpful features for search engines ==== +=== Other helpful features for search engines === * Titles of catalog pages follow a "Page title - Library name" pattern to provide specific titles in search engine results pages, @@ -101,7 +102,7 @@ is a helpful tool for viewing microdata. that provides machine-readable hours and contact information. -=== SKOS support === +== SKOS support == Some vocabularies used (or which could be used) for stock record attributes and coded value maps in Evergreen