From 8d76b76e2ae622c9238b3e4e464a424ce486b4a8 Mon Sep 17 00:00:00 2001 From: Remington Steed Date: Fri, 10 Jan 2020 08:47:25 -0500 Subject: [PATCH] Docs: Fix section for Antora: "System Configuration and Customization" This commit does the known tasks to prepare each main docs section for Antora: - 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 --- docs-antora/modules/admin/pages/sip_privacy.adoc | 47 ----------- docs-antora/modules/admin/pages/sip_server.adoc | 49 ++++++++++++ docs-antora/modules/admin_initial_setup/nav.adoc | 55 ++++++------- .../admin_initial_setup/pages/KidsOPAC.adoc | 15 ++-- .../admin_initial_setup/pages/borrowing_items.adoc | 21 ++--- .../pages/describing_your_organization.adoc | 7 +- .../pages/describing_your_people.adoc | 25 +++--- .../pages/designing_your_catalog.adoc | 90 ++++++++++++++-------- .../pages/different_styles_for_searchbar.adoc | 23 ------ .../admin_initial_setup/pages/hard_due_dates.adoc | 5 +- .../pages/importing_via_staff_client.adoc | 19 ++--- .../admin_initial_setup/pages/introduction.adoc | 3 +- .../pages/migrating_patron_data.adoc | 9 ++- .../pages/migrating_your_data.adoc | 9 ++- .../pages/ordering_materials.adoc | 27 +++---- .../pages/troubleshooting_tpac.adoc | 3 +- 16 files changed, 212 insertions(+), 195 deletions(-) delete mode 100644 docs-antora/modules/admin/pages/sip_privacy.adoc delete mode 100644 docs-antora/modules/admin_initial_setup/pages/different_styles_for_searchbar.adoc 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 -- 2.11.0