1.6/development/supercat.xml

   1 <?xml version="1.0" encoding="utf-8"?>\r
   2 <chapter xml:id="supercat" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
   3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
   4         <info>\r
   5                 <title>SuperCat</title>\r
   6         </info>\r
   7         <section xml:id="usingsupercat">>\r
   8                 <title>Using SuperCat</title> \r
   9                 <para>SuperCat allows Evergreen record and information retrieval from a web browser using a based on a number of open web standards and formats. The following record types are \r
  10                 supported:</para>\r
  11                 <itemizedlist>\r
  12                         <listitem>isbn</listitem>\r
  13                         <listitem>metarecord</listitem>\r
  14                         <listitem>record</listitem>\r
  15                 </itemizedlist>\r
  16                 <simplesect>\r
  17                         <title>Return a list of ISBNs for related records</title>\r
  18                         <para>Similar to the OCLC xISBN service, Evergreen can return a list of related records based on its oISBN algorithm:</para>\r
  19                         <para><uri>http://&lt;hostname&gt;/opac/extras/osibn/&lt;ISBN&gt;</uri></para>\r
  20                         <para>For example, <uri>http://dev.gapines.org/opac/extras/oisbn/0439136350</uri> returns:</para>\r
  21 <screen>\r
  22 &lt;idlist metarecord="302670"&gt;\r
  23 &lt;isbn record="250060"&gt;0790783525&lt;/isbn&gt;\r
  24 &lt;isbn record="20717"&gt;0736691316&lt;/isbn&gt;\r
  25 &lt;isbn record="250045"&gt;0790783517&lt;/isbn&gt;\r
  26 &lt;isbn record="199060"&gt;9500421151&lt;/isbn&gt;\r
  27 &lt;isbn record="250061"&gt;0790783495&lt;/isbn&gt;\r
  28 &lt;isbn record="154477"&gt;0807286028&lt;/isbn&gt;\r
  29 &lt;isbn record="227297"&gt;1594130027&lt;/isbn&gt;\r
  30 &lt;isbn record="26682"&gt;0786222743&lt;/isbn&gt;\r
  31 &lt;isbn record="17179"&gt;0807282316&lt;/isbn&gt;\r
  32 &lt;isbn record="34885"&gt;0807282316&lt;/isbn&gt;\r
  33 &lt;isbn record="118019"&gt;8478885196&lt;/isbn&gt;\r
  34 &lt;isbn record="1231"&gt;0738301477&lt;/isbn&gt;\r
  35 &lt;/idlist&gt;\r
  36 </screen>\r
  37                  </simplesect>\r
  38                  <simplesect>\r
  39                         <title>Return records</title>\r
  40                         <para>SuperCat can return records and metarecords in many different formats (see <xref linkend='supportedsupercatformats' /></para>\r
  41                         <para><uri>http://&lt;hostname&gt;/opac/extras/supercat/retrieve/&lt;format&gt;/&lt;record-type&gt;/&lt;bib-ID&gt;</uri></para>\r
  42                         <para>For example, <uri>http://dev.gapines.org/opac/extras/supercat/retrieve/mods/record/555</uri> returns:</para>\r
  43 <screen>\r
  44 &lt;mods:modsCollection version="3.0"&gt;\r
  45         &lt;mods:mods xsi:schemaLocation="http://www.loc.gov/mods/ http://www.loc.gov/standards/mods/mods.xsd"&gt;\r
  46                 &lt;titleInfo&gt;\r
  47                         &lt;title&gt;More Brer Rabbit stories /&lt;/title&gt;\r
  48                 &lt;/titleInfo&gt;\r
  49                 &lt;typeOfResource&gt;text&lt;/typeOfResource&gt;\r
  50                 &lt;originInfo&gt;\r
  51                         &lt;place&gt;\r
  52                                 &lt;code authority="marc"&gt;xx&lt;/c0de&gt;\r
  53                         &lt;/place&gt;\r
  54                         &lt;publisher&gt;Award Publications&lt;/publisher&gt;\r
  55                         &lt;dateIssued&gt;c1982, 1983&lt;/dateIssued&gt;\r
  56                         &lt;dateIssued encoding="marc" point="start"&gt;1983&lt;/dateIssued&gt;\r
  57                         &lt;dateIssued encoding="marc" point="end"&gt;1982&lt;/dateIssued&gt;\r
  58                         &lt;issuance&gt;monographic&lt;/issuance&gt;\r
  59                         &lt;/originInfo&gt;\r
  60                 &lt;language authority="iso639-2b"&gt;eng&lt;/language&gt;\r
  61                 &lt;physicalDescription&gt;\r
  62                         &lt;form authority="marcform"&gt;print&lt;/form&gt;\r
  63                         &lt;extent&gt;unp. : col. ill.&lt;/extent&gt;\r
  64                 &lt;/physicalDescription&gt;\r
  65                 &lt;note type="statement of responsibility"&gt;ill. by Rene Cloke.&lt;/note&gt;\r
  66                 &lt;subject authority="lcsh"&gt;\r
  67                         &lt;topic&gt;Animals&lt;/topic&gt;\r
  68                         &lt;topic&gt;Fiction&lt;/topic&gt;\r
  69                 &lt;/subject&gt;\r
  70                 &lt;subject authority="lcsh"&gt;\r
  71                         &lt;topic&gt;Fables&lt;/topic&gt;\r
  72                 &lt;/subject&gt;\r
  73                 &lt;recordInfo&gt;\r
  74                         &lt;recordContentSource&gt;(BRO)&lt;/recordContentSource&gt;\r
  75                         &lt;recordCreationDate encoding="marc"&gt;930903&lt;/recordCreationDate&gt;\r
  76                         &lt;recordChangeDate encoding="iso8601"&gt;19990703024637.0&lt;/recordChangeDate&gt;\r
  77                         &lt;recordIdentifier&gt;PIN60000007 &lt;/recordIdentifier&gt;\r
  78                 &lt;/recordInfo&gt;\r
  79         &lt;/mods:mods&gt;\r
  80 &lt;/mods:modsCollection&gt;\r
  81 </screen>\r
  82                  </simplesect>\r
  83                  <simplesect>\r
  84                         <title>Return a feed of recently edited or created records</title>\r
  85                         <para>SuperCat can return feeds of recently edited or created authority and bibliographic records:</para>\r
  86                         <para><uri>http://&lt;hostname&gt;/opac/extras/feed/freshmeat/&lt;feed-type&gt;/[authority|biblio]/[import|edit]/&lt;limit&gt;/&lt;date&gt;</uri></para>\r
  87                         <para>The limit records imported or edited following the supplied date will be returned. If you do not supply a date, then the most recent limit records will be returned.</para>\r
  88                         <para>If you do not supply a limit, then up to 10 records will be returned.</para>      \r
  89                         <para>Feed-type can be one of atom, html, htmlholdings, marcxml, mods, mods3, or rss2.</para>           \r
  90                         <para><uri>For example, http://dev.gapines.org/opac/extras/feed/freshmeat/atom/biblio/import/10/2008-01-01</uri></para>\r
  91                 </simplesect>\r
  92                  <simplesect>\r
  93                         <title>Browse records</title>\r
  94                         <para>SuperCat can browse records in HTML and XML formats:</para>\r
  95                         <para><uri>http://&lt;hostname&gt;/opac/extras/supercat/browse/&lt;format&gt;/call_number/&lt;org_unit&gt;/&lt;call_number&gt;</uri></para>\r
  96                         <para>For example, <uri>http://dev.gapines.org/opac/extras/browse/xml/call_number/-/GV</uri> returns:</para>\r
  97 <screen>\r
  98 &lt;hold:volumes xmlns:hold='http://open-ils.org/spec/holdings/v1'&gt;\r
  99         &lt;hold:volume id="tag:open-ils.org,2008:asset-call_number/130607" lib="FRRLS-FA" label="GUTCHEON BETH"&gt;\r
 100                 &lt;act:owning_lib id="tag:open-ils.org,2008:actor-org_unit/111" name="Fayette County Public Library"/&gt;\r
 101                 &lt;record xsi:schemaLocation="http://www.loc.gov/MARC21/slim http://www.loc.gov/ \r
 102                         standards/marcxml/schema/MARC21slim.xsd"\r
 103                         id="tag:open-ils.org,2008:biblio-record_entry/21669/FRRLS-FA"&gt;\r
 104                         &lt;leader&gt;09319pam a2200961 a 4500&lt;/leader&gt;\r
 105                         &lt;controlfield tag="001"/&gt;\r
 106                         &lt;controlfield tag="005"&gt;20000302124754.0&lt;/controlfield&gt;\r
 107                         &lt;controlfield tag="008"&gt;990817s2000    nyu           000 1 eng  &lt;/controlfield&gt;\r
 108                         &lt;datafield tag="010" ind1=" " ind2=" "&gt;\r
 109                                 &lt;subfield code="a"&gt;   99045936&lt;/subfield&gt;\r
 110                         &lt;/datafield&gt;\r
 111                         ..\r
 112                 &lt;/record&gt;\r
 113                 &lt;record&gt;\r
 114                         ..\r
 115                 &lt;/record&gt;\r
 116         &lt;/hold:volume&gt;\r
 117 &lt;/hold:volumes&gt;   \r
 118 </screen>\r
 119                 </simplesect>\r
 120                  <simplesect xml:id="supportedsupercatformats">\r
 121                         <title>Supported formats</title>\r
 122                         <para>SuperCat maintains a list of supported formats for records and metarecords:</para>\r
 123                         <para><uri>http://&lt;hostname&gt;/opac/extras/supercat/formats/&lt;record-type&gt;</uri></para>\r
 124                         <para>For example, <uri>http://dev.gapines.org/opac/extras/supercat/formats/record</uri> returns:</para>\r
 125 <screen>\r
 126 &lt;formats&gt;\r
 127 \r
 128   &lt;format&gt;\r
 129     &lt;name&gt;opac&lt;/name&gt;\r
 130     &lt;type&gt;text/html&lt;/type&gt;\r
 131   &lt;/format&gt;\r
 132 \r
 133   &lt;format&gt;\r
 134     &lt;name&gt;htmlholdings&lt;/name&gt;\r
 135     &lt;type&gt;text/html&lt;/type&gt;\r
 136   &lt;/format&gt;\r
 137  \r
 138   &lt;format&gt;\r
 139     &lt;name&gt;html&lt;/name&gt;\r
 140     &lt;type&gt;text/html&lt;/type&gt;\r
 141   &lt;/format&gt;\r
 142  \r
 143   &lt;format&gt;\r
 144     &lt;name&gt;htmlholdings-full&lt;/name&gt;\r
 145     &lt;type&gt;text/html&lt;/type&gt;\r
 146   &lt;/format&gt;\r
 147  \r
 148   &lt;format&gt;\r
 149     &lt;name&gt;html-full&lt;/name&gt;\r
 150     &lt;type&gt;text/html&lt;/type&gt;\r
 151   &lt;/format&gt;\r
 152  \r
 153   &lt;format&gt;\r
 154     &lt;name&gt;marcxml&lt;/name&gt;\r
 155     &lt;type&gt;application/xml&lt;/type&gt;\r
 156     &lt;namespace_uri&gt;http://www.loc.gov/MARC21/slim&lt;/namespace_uri&gt;\r
 157     &lt;docs&gt;http://www.loc.gov/marcxml/&lt;/docs&gt;\r
 158  \r
 159     &lt;schema_location&gt;\r
 160     http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd\r
 161     &lt;/schema_location&gt;\r
 162   &lt;/format&gt;\r
 163  \r
 164   &lt;format&gt;\r
 165     &lt;name&gt;marcxml-full&lt;/name&gt;\r
 166     &lt;type&gt;application/xml&lt;/type&gt;\r
 167     &lt;namespace_uri&gt;http://www.loc.gov/MARC21/slim&lt;/namespace_uri&gt;\r
 168     &lt;docs&gt;http://www.loc.gov/marcxml/&lt;/docs&gt;\r
 169  \r
 170     &lt;schema_location&gt;\r
 171     http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd\r
 172     &lt;/schema_location&gt;\r
 173   &lt;/format&gt;\r
 174  \r
 175   &lt;format&gt;\r
 176     &lt;name&gt;rss2&lt;/name&gt;\r
 177     &lt;type&gt;application/xml&lt;/type&gt;\r
 178   &lt;/format&gt;\r
 179  \r
 180   &lt;format&gt;\r
 181     &lt;name&gt;rss2-full&lt;/name&gt;\r
 182     &lt;type&gt;application/xml&lt;/type&gt;\r
 183   &lt;/format&gt;\r
 184  \r
 185   &lt;format&gt;\r
 186     &lt;name&gt;rdf_dc&lt;/name&gt;\r
 187     &lt;type&gt;application/xml&lt;/type&gt;\r
 188     &lt;namespace_uri&gt;http://purl.org/dc/elements/1.1/&lt;/namespace_uri&gt;\r
 189     &lt;schema_location&gt;http://purl.org/dc/elements/1.1/&lt;/schema_location&gt;\r
 190   &lt;/format&gt;\r
 191  \r
 192   &lt;format&gt;\r
 193     &lt;name&gt;oai_dc&lt;/name&gt;\r
 194     &lt;type&gt;application/xml&lt;/type&gt;\r
 195     &lt;namespace_uri&gt;http://www.openarchives.org/OAI/2.0/oai_dc/&lt;/namespace_uri&gt;\r
 196     &lt;schema_location&gt;http://www.openarchives.org/OAI/2.0/oai_dc.xsd&lt;/schema_location&gt;\r
 197   &lt;/format&gt;\r
 198  \r
 199   &lt;format&gt;\r
 200     &lt;name&gt;srw_dc&lt;/name&gt;\r
 201     &lt;type&gt;application/xml&lt;/type&gt;\r
 202     &lt;namespace_uri&gt;info:srw/schema/1/dc-schema&lt;/namespace_uri&gt;\r
 203  \r
 204     &lt;schema_location&gt;\r
 205     http://www.loc.gov/z3950/agency/zing/srw/dc-schema.xsd\r
 206     &lt;/schema_location&gt;\r
 207   &lt;/format&gt;\r
 208  \r
 209   &lt;format&gt;\r
 210     &lt;name&gt;mods32&lt;/name&gt;\r
 211     &lt;type&gt;application/xml&lt;/type&gt;\r
 212     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
 213     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 214     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-2.xsd&lt;/schema_location&gt;\r
 215   &lt;/format&gt;\r
 216  \r
 217   &lt;format&gt;\r
 218     &lt;name&gt;mods3&lt;/name&gt;\r
 219     &lt;type&gt;application/xml&lt;/type&gt;\r
 220     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
 221     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 222     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-1.xsd&lt;/schema_location&gt;\r
 223   &lt;/format&gt;\r
 224  \r
 225   &lt;format&gt;\r
 226     &lt;name&gt;mods3-full&lt;/name&gt;\r
 227     &lt;type&gt;application/xml&lt;/type&gt;\r
 228     &lt;namespace_uri&gt;http://www.loc.gov/mods/v3&lt;/namespace_uri&gt;\r
 229     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 230     &lt;schema_location&gt;http://www.loc.gov/standards/mods/v3/mods-3-1.xsd&lt;/schema_location&gt;\r
 231   &lt;/format&gt;\r
 232  \r
 233   &lt;format&gt;\r
 234     &lt;name&gt;mods&lt;/name&gt;\r
 235     &lt;type&gt;application/xml&lt;/type&gt;\r
 236     &lt;namespace_uri&gt;http://www.loc.gov/mods/&lt;/namespace_uri&gt;\r
 237     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 238     &lt;schema_location&gt;http://www.loc.gov/standards/mods/mods.xsd&lt;/schema_location&gt;\r
 239   &lt;/format&gt;\r
 240  \r
 241   &lt;format&gt;\r
 242     &lt;name&gt;mods-full&lt;/name&gt;\r
 243     &lt;type&gt;application/xml&lt;/type&gt;\r
 244     &lt;namespace_uri&gt;http://www.loc.gov/mods/&lt;/namespace_uri&gt;\r
 245     &lt;docs&gt;http://www.loc.gov/mods/&lt;/docs&gt;\r
 246     &lt;schema_location&gt;http://www.loc.gov/standards/mods/mods.xsd&lt;/schema_location&gt;\r
 247   &lt;/format&gt;\r
 248  \r
 249   &lt;format&gt;\r
 250     &lt;name&gt;atom&lt;/name&gt;\r
 251     &lt;type&gt;application/xml&lt;/type&gt;\r
 252     &lt;namespace_uri&gt;http://www.w3.org/2005/Atom&lt;/namespace_uri&gt;\r
 253     &lt;docs&gt;http://www.ietf.org/rfc/rfc4287.txt&lt;/docs&gt;\r
 254   &lt;/format&gt;\r
 255  \r
 256   &lt;format&gt;\r
 257     &lt;name&gt;atom-full&lt;/name&gt;\r
 258     &lt;type&gt;application/xml&lt;/type&gt;\r
 259     &lt;namespace_uri&gt;http://www.w3.org/2005/Atom&lt;/namespace_uri&gt;\r
 260     &lt;docs&gt;http://www.ietf.org/rfc/rfc4287.txt&lt;/docs&gt;\r
 261   &lt;/format&gt;\r
 262 &lt;/formats&gt;\r
 263 </screen>\r
 264                 </simplesect>\r
 265         </section>\r
 266         <section xml:id="addingsupercatformats">\r
 267                 <title>Adding new SuperCat Formats</title>\r
 268                 <para>Adding SuperCat formats requires experience editing XSL files and familiarity with XML and Perl.</para>   \r
 269                 <para>SuperCat web services are based on the OpenSRF service, <systemitem class="service">>open-ils.supercat</systemitem>.</para> \r
 270                 <para>Developers are able to add new formats by adding the <emphasis>xsl</emphasis> stylesheet for the format. By default, the location of the stylesheets is <filename class="directory">/openils/var/xsl/</filename>. You must also add the feed  to the perl \r
 271                 modules <filename>openils/lib/perl5/OpenILS/WWW/SuperCat/feed.pm</filename> and <filename>openils/lib/perl5/OpenILS/WWW/SuperCat.pm</filename>. An Evergreen restart is \r
 272                 required for the feed to be activated.</para>\r
 273                 <tip><para>Use an existing xsl stylesheet and Perl module entry as a template for your new format.</para></tip>\r
 274         </section>\r
 275         <section xml:id="editingsupercatformats">\r
 276                 <title>Customizing SuperCat Formats</title>     \r
 277                 <para>Editing SuperCat formats requires experience editing XSL files and familiarity with XML..</para>  \r
 278                 <para>It is possible to customize existing supercat formats using XSL stylesheets. You arwe able to change the content to be displayed and the design of the pages.</para> \r
 279                 <para>In order to change the display of a specific format, edit the corresponding XSL file(s) for the particular format. The default location for the XSL stylesheets is \r
 280                 <filename class="directory">/openils/var/xsl/</filename>. </para>\r
 281         </section>\r
 282 </chapter>\r
 283 \r