Docs: 3.16 updates for KidsOPAC.adoc

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*.
-
-------------------------------------------------------------------------------
-<Location /eg/kpac>
-    PerlSetVar OILSWebContextLoader "OpenILS::WWW::EGKPacLoader"
-    PerlSetVar KPacConfigFile "/openils/conf/kpac.xml.example"
-</Location>
-------------------------------------------------------------------------------
-
-=== 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: <pages> and <layout>.
-    * 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]
-------------------------------------------------------------------------------
-<layout owner="1" page="1"/>
-------------------------------------------------------------------------------
-
-    * The pages section is a container for <page> elements.
-    * Each page defines an ID, the number of columns to display for the page, 
-      the page name, and an icon.
-
-[source, xml]
-------------------------------------------------------------------------------
-<page id="1" columns="5" name="Home" img="/images/home.jpg">
-------------------------------------------------------------------------------
-
-    * 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]
-------------------------------------------------------------------------------
-<cell type="topic">12</cell>
-------------------------------------------------------------------------------
-
-    * The content for type="search" cells is the search query.  The name and 
-      img are used for the display content.
-
-[source, xml]
-------------------------------------------------------------------------------
-<cell name="Piano" img="category.png" type="search">su:piano</cell>
-------------------------------------------------------------------------------
-
-    * The content for type="link" cells is the URL.  The name and img are used 
-    for the display content.
-
-[source, xml]
-------------------------------------------------------------------------------
-<cell name="Clarinet" img="category.png" 
-    type="link">http://en.wikipedia.org/wiki/Clarinet</cell>
-------------------------------------------------------------------------------
-
-
-=== 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:
-
-------------------------------------------------------------------------------
-<VirtualHost *:80>
-    ServerName xyz.dev198.esilibrary.com:80
-    DocumentRoot /openils/var/web/
-    DirectoryIndex index.html index.xhtml
-    Include eg_vhost.conf
-    <Location /eg/kpac>
-	#Point to a different kpac.xml config file if needed
-        #PerlSetVar KPacConfigFile "/openils/conf/kpac.xml.example"
-        PerlAddVar OILSWebTemplatePath "/openils/var/templates_kpac2"
-    </Location>
-</VirtualHost>
-------------------------------------------------------------------------------
-
-== 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