Welcome to the documentation of the Picturae Webkitchen components, on this website you can find information how to implement our components on your own website.

You can also try the demo to see how our application should behave. In case you have any questions you can contact us at contact@picturae.com.

Mediabank
Mediabank 2.0
Genealogie
Webexpo
Memorix Archives

Picturae Webkitchen - Memorix Archives

Memorix Archives - Getting Started

To setup the archives component you need to include the follow scripts 

    <script src="http://images.memorix.nl/topviewer/1.0/src/topviewer.compressed.js"></script>
<script src="//webservices.picturae.com/archives/js/dist/web-kitchen.1.0.0.min.js" type="text/javascript"></script>
<script src="//webservices.picturae.com/archives/translations/nl_NL.js" type="text/javascript"></script>
<script src="//webservices.picturae.com/archives/packages/nl_NL/archives/full.js" type="text/javascript"></script>

The topviewer can be ommited if no scans are going to be displayed. The translations and the templates package are multilingual - currently nl_NL and en_GB versions are present.

You can also make use of some default styling which will be a good base to build your customization on

    <link rel="stylesheet" href="//webservices.picturae.com/archives/css/screen.css">

At the place in your html where you want the archives component booted you shall include the master/layout template (or write your own). For example: 

    <!-- ko template: {name: 'archives/layout/with-modal'} --><!-- /ko -->

In many use cases the default layout will not be perfectly suitable for your use case (because of the desire to use a css framework like foundation or bootstrap and benefit from their grid systems). In that case you will either need to write your own layout template overwrite or be provided with one. Both cases are not in the scope of the current tutorial.

To instantiate the javascript client you can call it as follows (this is also the minimum required configuration): 

    $(function () {
    PicturaeApi.archives({
        basePath: "<the path in your page where the component lives. E.g. '/archives'>",
        url: "<api url>",
        key: "<api key>"
    });
});

Config

General options

Here is a list of the supported application options

Name Default Type Description
basePath N/A String As the component does not use query params for its routing but works with SEF urls it needs to know what the base path where it runs is so it can parse a requested URL correctly
key N/A String The api key provided by Picturae
url N/A String The url of the data api
language en_GB String Possible values are:
  • nl_NL
  • en_GB
container body Object The DOM element on which the ko.applyBindings() will be called. If knockout is already used in the basePath where you are trying to boot the archives component this is the way to prevent calling applyBindings multiple times on the same elements which will cause knockout errors
ondemand false Boolean If you are using the default templates when this option is set to true a button for requesting scans will be displayed next to files in the details tree. When clicked the onScanOnDemand event will be triggered
scans null Object When the option is set scans will be displayed when browsing files. The configuration object supports the following properties:
  • viewer - the only supported value currently is topviewer
  • options - an object with viewer configuration
    The topviewer requires the following options:
    • tiledUrl - the url gets ".jpg" appended and at that link the topviewer will try to access the tiled version of the scans
    • notTiledUrl - in case the topviewer does not find a tiled version of a scan it will try to display a fallback image. This option sets the path where that image is going to be looked for.
views null Object View specific options. A full list of the supported options is available below
events null Object A list of event handlers. For a full reference of the supported events please go to the events chapter

View options

View Available options
search
  • view - 'context' (default) or 'list',
  • form - 'simple' (default) or 'advanced'. The advanced form has input fields for searching by finding aid id and file number
  • filtersPosition - one of ['left', 'right', 'top']. The position of the facet filters
  • formPosition - one of ['left', 'right', 'top']. The position of the search form. N.B. not all combinations of filtersPosition and formPosition are possible. When the filters are on the left or on the right the search form may be either on the same side or 'top'.
  • pagination - pagination config options
    • limit - default is 10, possible values are 10, 25 and 50
  • orderOptions - an array of config objects for the options in the sort select box. For more info contact Picturae development team.
  • defaultOrder - string value that will be used as default sort. Should be a supported option value, specified in orderOptions or the default ones. For more info contact Picturae development team.
  • facets - facets config options
    • order - default is ['unitdate_years', 'string_class_search', 'names', 'subject', 'subject_period', 'subject_place']
  • resultsWithScansOption - boolean value to control if the "Only results with scans" checkbox is shown in the searchforms. Defaults to true.
details
  • xmlLocation - if set a link to the EAD file will be displayed in the details view. The provided url will be automatically appended by <finding aid identifier>.ead.xml
  • pdfLocation - if set a link to the PDF version of the EAD will be displayed in the details view. The provided url will be automatically appended by <finding aid identifier>.ead.pdf
  • showBackButton - whether a back buttons need to be shown on top of the details page or not

When the modal option is used for scans and facetvalues views instead of just setting it to true an options object with the width and height properties is also accepted.

Facets

Hide facets The option solr.facets.field.{fieldName}.visible allows hiding a particular field's facets when set to FALSE.
Reorder facets The option for reordering facets is frontend.views.search.facets.order. It needs to be an array of fieldnames. Not listed fields will still be shown after those ones.
Reorder facet values The facets values may be ordered by index or count (as known from Solr). This is done by setting solr.facets.field.{fieldName}.sort to either index or count.

Events

A list of the supported events:

Event Callback params Description
onAfterResultsUpdate response Called after an api request was completed and the search results has been updated
onAfterDetailsUpdate response Called when the record has been loaded/reloaded in details view
onScanOnDemand file Fired when the scan on demand button is clicked for a file
onScanTopviewerLoad viewer An event raised right after the scans viewer was initialized and scans are going to be displayed

HTML 4 Mode

It is possible to force html 4 urls with a # instead of / (push state), this can be useful if you do not have the option to rewrite url's in your server.

http://example.com/archives/details/NL-RtHNI-110000135/
would become:
http://example.com/archives#details/NL-RtHNI-110000135/

This should only be done as last resort, as it's not possible to provide any server side fallback as everything behind the # is not passed to the server.

Add the following script to the head of your document, it's important that this script loads before the mediabank.js.

    <script type="text/javascript" language="javascript">
window.History = { options: { html4Mode: true} };
</script>

It's also important to have the correct base href else you could get an extra level in your hash, if your url is located on: http://example.com/archive it's important to keep an extra slash in the base href 

    <base href="http://example.com/archives/" />