docs/TechRef/KidsOPAC.txt

   1 Kid's OPAC Configuration
   2 ========================
   3
   4 Configuration
   5 -------------
   6
   7 Apache
   8 ~~~~~~
   9
  10 The KPAC is already included and ready to be used with new Evergreen installs.  So you only need to change the apache config
  11 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
  12 in */etc/apache2/eg_vhosts.conf*.
  13
  14 ------------------------------------------------------------------------------
  15 <Location /eg/kpac>
  16     PerlSetVar OILSWebContextLoader "OpenILS::WWW::EGKPacLoader"
  17     PerlSetVar KPacConfigFile "/openils/conf/kpac.xml.example"
  18 </Location>
  19 ------------------------------------------------------------------------------
  20
  21 XML Configuration File
  22 ~~~~~~~~~~~~~~~~~~~~~~
  23
  24     * The XML configuration file defines the layout of the kid's OPAC.
  25     * It is read with each restart/reload of the Apache web server.
  26     * The file lives by default at /openils/conf/kpac.xml.example
  27     * There are two top-level elements: <pages> and <layout>.
  28     * The layout defines the owning org unit and the start page, both by ID.
  29     * At runtime, the layout is determined by the context org unit.  If no
  30       configuration is defined for the context org unit, the layout for the
  31       closest ancestor is used.
  32
  33 [source, xml]
  34 ------------------------------------------------------------------------------
  35 <layout owner="1" page="1"/>
  36 ------------------------------------------------------------------------------
  37
  38     * The pages section is a container for <page> elements.
  39     * Each page defines an ID, the number of columns to display for the page,
  40       the page name, and an icon.
  41
  42 [source, xml]
  43 ------------------------------------------------------------------------------
  44 <page id="1" columns="5" name="Home" img="/images/home.jpg">
  45 ------------------------------------------------------------------------------
  46
  47     * Each page is a container of cells
  48     * Each cell defines
  49         ** type (topic, search, link)
  50         ** name
  51         ** icon
  52         ** content
  53     * The content for type="topic" cells is the ID of the page this topic
  54       jumps to.  The name and img for the referenced page is used as the
  55       display content.
  56
  57 [source, xml]
  58 ------------------------------------------------------------------------------
  59 <cell type="topic">12</cell>
  60 ------------------------------------------------------------------------------
  61
  62     * The content for type="search" cells is the search query.  The name and
  63       img are used for the display content.
  64
  65 [source, xml]
  66 ------------------------------------------------------------------------------
  67 <cell name="Piano" img="category.png" type="search">su:piano</cell>
  68 ------------------------------------------------------------------------------
  69
  70     * The content for type="link" cells is the URL.  The name and img are used
  71     for the display content.
  72
  73 [source, xml]
  74 ------------------------------------------------------------------------------
  75 <cell name="Clarinet" img="category.png"
  76     type="link">http://en.wikipedia.org/wiki/Clarinet</cell>
  77 ------------------------------------------------------------------------------
  78
  79
  80 Skin Configuration
  81 ~~~~~~~~~~~~~~~~~~
  82
  83 The following example enables you to configure the alternate skin (Monster Skin, kpac2) for the Kids
  84 Catalog.
  85
  86 You should be familiar with how the <<_how_to_override_templates,Evergreen TPAC handles template folders>>
  87 before you make these changes.
  88
  89 If you already have a custom template directory setup you can copy the *Open-ILS/examples/web/templates/kpac*
  90 files to that directory instead, and then skip any Apache config changes.
  91
  92 [source, bash]
  93 ------------------------------------------------------------------------------
  94 % cp -r Open-ILS/examples/web/css/skin/kpac2 /openils/var/web/css/skin/
  95 % cp -r Open-ILS/examples/web/images/kpac/* /openils/var/web/images/kpac/ #does not clobber
  96 % mkdir /openils/var/templates_kpac2
  97 % cp -r Open-ILS/examples/web/templates/kpac /openils/var/templates_kpac2/
  98 % cp -r /openils/var/web/css/skin/default/kpac/fonts /openils/var/web/css/skin/kpac2/kpac
  99 -------------------------------------------------------------------------------
 100
 101 Then set up 443/80 vhosts for serving the alternate skin in eg.conf, something
 102 along the lines of:
 103
 104 ------------------------------------------------------------------------------
 105 <VirtualHost *:80>
 106     ServerName xyz.dev198.esilibrary.com:80
 107     DocumentRoot /openils/var/web/
 108     DirectoryIndex index.html index.xhtml
 109     Include eg_vhost.conf
 110     <Location /eg/kpac>
 111         #Point to a different kpac.xml config file if needed
 112         #PerlSetVar KPacConfigFile "/openils/conf/kpac.xml.example"
 113         PerlAddVar OILSWebTemplatePath "/openils/var/templates_kpac2"
 114     </Location>
 115 </VirtualHost>
 116 -------------------------------------------------------------------------------
 117
 118 Considerations for Community Adoption
 119 -------------------------------------
 120
 121 The templates for the Kid's OPAC were developed long before the TPAC was
 122 integrated into Evergreen and it has many of the same limitations that
 123 were part of the TPAC.
 124
 125     * Fixed width elements (divs, images, etc.), which complicates the
 126       addition of new features and local customizations.
 127     * Images with text, which prevents l10n/i18n.
 128     * While the KPAC does not attempt to match the color scheme of any one
 129       institution, it's inconsistent with the standard Evergreen color
 130       palette.  Creating an additional skin to act as the Evergreen default
 131       my be necessary.
 132
 133 Outstanding Development (Unsponsored)
 134 -------------------------------------
 135
 136     ** Port the XML configuration file to a DB structure, complete with UI for
 137        managing the various components and upgrade path.
 138