docs/opac/new_skin_customizations.adoc

   1 Creating a New Skin: the Bare Minimum
   2 =====================================
   3
   4 Introduction
   5 ------------
   6
   7 When you adopt the TPAC as your catalog, you must create a new skin. This
   8 involves a combination of overriding template files and setting Apache
   9 directives to control the look and feel of your customized TPAC.
  10
  11 Apache directives
  12 -----------------
  13 There are a few Apache directives and environment variables of note for
  14 customizing TPAC behavior. These directives should generally live within a
  15 `<vhost>` section of your Apache configuration.
  16
  17 * `OILSWebDefaultLocale` specifies which locale to display when a user lands
  18    on a page in the TPAC and has not chosen a different locale from the TPAC
  19    locale picker. The following example shows the `fr_ca` locale being added
  20    to the locale picker and being set as the default locale:
  21 +
  22 ------------------------------------------------------------------------------
  23 PerlAddVar OILSWebLocale "fr_ca"
  24 PerlAddVar OILSWebLocale "/openils/var/data/locale/opac/fr-CA.po"
  25 PerlAddVar OILSWebDefaultLocale "fr-CA"
  26 ------------------------------------------------------------------------------
  27 +
  28 * `physical_loc` is an Apache environment variable that sets the default
  29   physical location, used for setting search scopes and determining the order
  30   in which copies should be sorted. The following example demonstrates the
  31   default physical location being set to library ID 104:
  32 +
  33 ------------------------------------------------------------------------------
  34 SetEnv physical_loc 104
  35 ------------------------------------------------------------------------------
  36
  37 Customizing templates
  38 ---------------------
  39 When you install Evergreen, the TPAC templates include many placeholder images,
  40 text, and links. You should override most of these to provide your users with a
  41 custom experience that matches your library.  Following is a list of templates
  42 that include placeholder images, text, or links that you should override.
  43
  44 NOTE: All paths are relative to `/openils/var/templates/opac`
  45
  46 [[configtt2]]
  47
  48 * `parts/config.tt2`: contains many configuration settings that affect the
  49   behavior of the TPAC, including:
  50   ** hiding the *Place Hold* button for available items
  51   ** enabling RefWorks support for citation management
  52   ** adding OpenURL resolution for electronic resources
  53   ** enabling Google Analytics tracking for your TPAC
  54   ** displaying the "Forgot your password?" prompt
  55   ** controlling the size of cover art on the record details page
  56   ** defining which facets to display, and in which order
  57   ** controlling basic and advanced search options
  58   ** controlling if the "Show More Details" button is visible or activated by
  59 default in OPAC search results
  60   ** hiding phone notification options (useful for libraries that do not do
  61 phone notifications)
  62   ** disallowing password or e-mail changes (useful for libraries that use
  63 centralized authentication or single sign-on systems)
  64   ** displaying a maintenance message in the public catalog and KPAC (this is
  65 controlled by the _ctx.maintenance_message_ variable)
  66   ** displaying previews of books when available from Google Books.  This is
  67 controlled by the _ctx.google_books_preview_ variable, which is set to 0 by
  68 default to protect the privacy of users who might not want to share their
  69 browsing behavior with Google.
  70   ** disabling the "Group Formats and Editions" search. This is controlled by
  71 setting the metarecords.disabled variable to 1.
  72   ** setting the default search to a 'Group Formats and Editions' search. This
  73 is done by setting the search.metarecord_default variable to 1.
  74 * `parts/footer.tt2` and `parts/topnav_links.tt2`: contains customizable
  75   links. Defaults like 'Link 1' will not mean much to your users!
  76 * `parts/homesearch.tt2`: holds the large Evergreen logo on the home page
  77   of the TPAC. Substitute your library's logo, or if you are adventurous,
  78   create a "most recently added items" carousel... and then share your
  79   customization with the Evergreen community.
  80 * `parts/topnav_logo.tt2`: holds the small Evergreen logo that appears on the
  81   top left of every page in the TPAC. You will also want to remove or change
  82   the target of the link that wraps the logo and leads to the
  83   http://evergreen-ils.org[Evergreen site].
  84 * `parts/login/form.tt2`: contains some assumptions about terminology and
  85   examples that you might prefer to change to be more consistent with your own
  86   site's existing practices. For example, you may not use 'PIN' at your library
  87   because you want to encourage users to use a password that is more secure than
  88   a four-digit number.
  89 * `parts/login/help.tt2`: contains links that point to http://example.com,
  90   images with text on them (which is not an acceptable practice for
  91   accessibility reasons), and promises of answers to frequently asked questions
  92   that might not exist at your site.
  93 * \`parts/login/password_hint.tt2\`: contains a hint about your users' password
  94   on first login that is misleading if your library does not set the initial
  95   password for an account to the last four digits of the phone number associated
  96   with the account.
  97 * `parts/myopac/main_refund_policy.tt2`: describes the policy for refunds for
  98   your library.
  99 * `parts/myopac/prefs_hints.tt2`: suggests that users should have a valid email
 100   on file so they can receive courtesy and overdue notices. If your library
 101   does not send out email notices, you should edit this to avoid misleading your
 102   users.
 103 * `myopac/update_password_msg.tt2`: defines the password format that needs
 104   to be used when setting a user password. If your Evergreen site has set
 105   _Password format_ regex in the Library Settings Editor, you
 106   should update the language to describe the format that should be used.
 107 * `password_reset.tt2`: in the msg_map section, you might want to change the
 108   NOT_STRONG text that appears when the user tries to set a password that
 109   does not match the required format. Ideally, this message will tell the user
 110   how they should format the password.
 111 * \`parts/css/fonts.tt2\`: defines the font sizes for the TPAC in terms of one
 112   base font size, and all other sizes derived from that in percentages. The
 113   default is 12 pixels, but http://goo.gl/WfNkE[some design sites] strongly
 114   suggest a base font size of 16 pixels. Perhaps you want to try '1em' as a
 115   base to respect your users' preferences. You only need to change one number
 116   in this file if you want to experiment with different options for your users.
 117 * `parts/css/colors.tt2`: chances are your library's official colors do not
 118   match Evergreen's wall of dark green. This file defines the colors in use in
 119   the standard Evergreen template. In theory you should be able to change just
 120   a few colors and everything will work, but in practice you will need to
 121   experiment to avoid light-gray-on-white low-contrast combinations.
 122
 123 The following are templates that are less frequently overridden, but some
 124 libraries benefit from the added customization options.
 125
 126 * `parts/advanced/numeric.tt2`: defines the search options of the Advanced
 127 Search > Numeric search. If you wanted to add a bib call number search option,
 128 which is different from the item copy call number; you would add the following
 129 code to `numeric.tt2`.
 130 +
 131 ------------------------------------------------------------------------------
 132 <option value="identifier|bibcn">[% l('Bib Call Number') %]</option>
 133 ------------------------------------------------------------------------------
 134