LP#1848524: Docs: Add missing file from TechRef directory

Signed-off-by: Remington Steed <rjs7@calvin.edu>
Signed-off-by: Galen Charlton <gmc@equinoxinitiative.org>

diff --git a/docs-antora/modules/admin_initial_setup/pages/KidsOPAC.adoc b/docs-antora/modules/admin_initial_setup/pages/KidsOPAC.adoc
new file mode 100644 (file)
index 0000000..54ec37e
--- /dev/null
+++ b/docs-antora/modules/admin_initial_setup/pages/KidsOPAC.adoc
@@ -0,0 +1,131 @@
+== Kid's OPAC Configuration ==
+
+=== 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 <<_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.
+