diff --git a/docs/modules/admin_initial_setup/pages/KidsOPAC.adoc b/docs/modules/admin_initial_setup/pages/KidsOPAC.adoc index 0c572e46be2..bb0b3a525e5 100644 --- a/docs/modules/admin_initial_setup/pages/KidsOPAC.adoc +++ b/docs/modules/admin_initial_setup/pages/KidsOPAC.adoc @@ -1,132 +1,73 @@ = Kid's OPAC Configuration = :toc: +== KPAC Redesign in Bootstrap == + +The Bootstrap version of the Kids' Catalog (KPAC) was released in Evergreen 3.16. This version is fully accessible, mobile-friendly, and translatable. + +This page overviews the steps to configure the KPAC through the administration interface in the staff client. Please see xref:opac/kids_opac.adoc[Kids’ OPAC] for how to use the Kids' Catalog. + == Configuration == -=== 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 -in */etc/apache2/eg_vhosts.conf*. - ------------------------------------------------------------------------------- - - PerlSetVar OILSWebContextLoader "OpenILS::WWW::EGKPacLoader" - PerlSetVar KPacConfigFile "/openils/conf/kpac.xml.example" - ------------------------------------------------------------------------------- - -=== 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. - * The file lives by default at /openils/conf/kpac.xml.example - * There are two top-level elements: and . - * The layout defines the owning org unit and the start page, both by ID. - * At runtime, the layout is determined by the context org unit. If no - configuration is defined for the context org unit, the layout for the - closest ancestor is used. - -[source, xml] ------------------------------------------------------------------------------- - ------------------------------------------------------------------------------- - - * The pages section is a container for elements. - * Each page defines an ID, the number of columns to display for the page, - the page name, and an icon. - -[source, xml] ------------------------------------------------------------------------------- - ------------------------------------------------------------------------------- - - * Each page is a container of cells - * Each cell defines - ** type (topic, search, link) - ** name - ** icon - ** content - * The content for type="topic" cells is the ID of the page this topic - jumps to. The name and img for the referenced page is used as the - display content. - -[source, xml] ------------------------------------------------------------------------------- -12 ------------------------------------------------------------------------------- - - * The content for type="search" cells is the search query. The name and - img are used for the display content. - -[source, xml] ------------------------------------------------------------------------------- -su:piano ------------------------------------------------------------------------------- - - * The content for type="link" cells is the URL. The name and img are used - for the display content. - -[source, xml] ------------------------------------------------------------------------------- -http://en.wikipedia.org/wiki/Clarinet ------------------------------------------------------------------------------- - - -=== Skin Configuration === - -The following example enables you to configure the alternate skin (Monster Skin, kpac2) for the Kids -Catalog. - -You should be familiar with how the xref:admin:template_toolkit.adoc#how_to_override_templates[Evergreen TPAC handles template folders] -before you make these changes. - -If you already have a custom template directory setup you can copy the *Open-ILS/examples/web/templates/kpac* -files to that directory instead, and then skip any Apache config changes. - -[source, bash] ------------------------------------------------------------------------------- -% cp -r Open-ILS/examples/web/css/skin/kpac2 /openils/var/web/css/skin/ -% cp -r Open-ILS/examples/web/images/kpac/* /openils/var/web/images/kpac/ #does not clobber -% mkdir /openils/var/templates_kpac2 -% cp -r Open-ILS/examples/web/templates/kpac /openils/var/templates_kpac2/ -% cp -r /openils/var/web/css/skin/default/kpac/fonts /openils/var/web/css/skin/kpac2/kpac ------------------------------------------------------------------------------- - -Then set up 443/80 vhosts for serving the alternate skin in eg.conf, something -along the lines of: - ------------------------------------------------------------------------------- - - ServerName xyz.dev198.esilibrary.com:80 - DocumentRoot /openils/var/web/ - DirectoryIndex index.html index.xhtml - Include eg_vhost.conf - - #Point to a different kpac.xml config file if needed - #PerlSetVar KPacConfigFile "/openils/conf/kpac.xml.example" - PerlAddVar OILSWebTemplatePath "/openils/var/templates_kpac2" - - ------------------------------------------------------------------------------- - -== 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 -were part of the TPAC. - - * Fixed width elements (divs, images, etc.), which complicates the - addition of new features and local customizations. - * Images with text, which prevents l10n/i18n. - * While the KPAC does not attempt to match the color scheme of any one - institution, it's inconsistent with the standard Evergreen color - palette. Creating an additional skin to act as the Evergreen default - my be necessary. - -== Outstanding Development (Unsponsored) == - - ** Port the XML configuration file to a DB structure, complete with UI for - managing the various components and upgrade path. +The Bootstrap KPAC will be used when the Bootstrap public catalog (OPAC) is used. This is controlled by the eg_vhost.conf file. + +=== Permissions === + +The KPAC_ADMIN permission is necessary to access the KPAC Topic Configuration interface. + +=== Library Settings === + +. _Show KPAC Link_ (opac.show_kpac_link): Shows the KPAC link in the OPAC. The default value is _False_. +. _KPAC Audience Filter_ (opac.kpac_audn_filter): Controls which items to display based on MARC Target Audience (Audn) field. Juvenile options are _a_,_b_,_c_,_d_,_j_. The default is _a_,_b_,_c_,_j_. + +=== KPAC Topic Configuration === + +The new topic administration interface is reached by going to *Administration* → *Server Administration* → *KPAC Topic Configuration*. + +==== Creating a New Topic Configuration ==== + +. Click *New KPAC Topic Configuration*. ++ +image::kpac/kpac_config_new.png[""] ++ +. Fill out the form: +.. _Name_ +.. _Description_ +.. _Active_ +.. _Image File Name_: Topic graphics should be a minimum size of 168 x 107 pixels and need to be uploaded into the /images/kpac2/uploads folder. Only the file name needs to be entered into the _Image File Name_ field (for example, kpac-dinosaur.png). +.. _Parent Category_: Should be left blank unless it is a subtopic of another category, in which case it should reference the parent topic’s name. +.. _Topic Order_: Order in which the topic displays in the categories list +.. _Content Type_: Determines what type of link a topic will be: Category, Search String, URL, or Book List. +.. _Category_: Category topics will open to a new page with subtopics. +.. _Search String_: Fill in the Search String field. This functions as a pre-made search query and accepts URL-friendly search strings. Examples: +... alphabet +... su:seasons +... ti:tractor +... nutrition after(2020) +... "telling time" +.. _URL_: Fill in the URL field. Either full URLs (https://example.com) or relative URLs (/eg/kpac/dewey) may be used. +.. _Book List_: Fill in the Book List ID field. Create a book list in the OPAC and make it shareable. Click "View in Catalog" and then copy the bookbag ID from the URL. +. Click *Save*. ++ +image::kpac/kpac_config_save[Topic Configuration form with Save button] ++ + + +==== Editing and Deleting a Topic Configuration ==== + +To edit a topic configuration, double-click the entry to open the form. Or, you can access the *Actions* dropdown menu by clicking the *Actions* button. Then click *Edited Selected*, make the updates in the form, and click *Save*. + +To delete a topic configuration, open the *Actions* dropdown menu by clicking the *Actions* button, or right-clicking the entry, and clicking *Delete Selected*. + +image::kpac/kpac_config_actions[Actions menu with Edit Selected and Delete Selected options] + + +=== Additional Customization === + +By default, the KPAC will use the round Evergreen logo. To replace it with a custom logo, replace the file at /images/kpac2/logo-header.png. + +The KPAC utilizes its own CSS files: +* /templates-bootstrap/kpac/css/style.css.tt2 +* /templates-bootstrap/kpac/css/colors.tt2 +* /templates-bootstrap/kpac/css/fonts.tt2 diff --git a/docs/modules/opac/assets/images/kpac/kpac_config_actions.png b/docs/modules/opac/assets/images/kpac/kpac_config_actions.png new file mode 100644 index 00000000000..aaab07b3eb0 Binary files /dev/null and b/docs/modules/opac/assets/images/kpac/kpac_config_actions.png differ diff --git a/docs/modules/opac/assets/images/kpac/kpac_config_new.png b/docs/modules/opac/assets/images/kpac/kpac_config_new.png new file mode 100644 index 00000000000..3c178e81204 Binary files /dev/null and b/docs/modules/opac/assets/images/kpac/kpac_config_new.png differ diff --git a/docs/modules/opac/assets/images/kpac/kpac_config_save.png b/docs/modules/opac/assets/images/kpac/kpac_config_save.png new file mode 100644 index 00000000000..bb0ee9b43de Binary files /dev/null and b/docs/modules/opac/assets/images/kpac/kpac_config_save.png differ