Modes Wordpress Plugin documentation First edition April 2015 Richard Light

Transcription

1 Modes Wordpress Plugin documentation data detail domain folder image item modes name page pages script search stylesheet First edition April 2015 Richard Light

2 Modes Wordpress Plugin Free version documentation Richard Light First edition Copyright ( ) Modes Users Association (MUA), Published electronically as part of the Modes Complete, not for distribution separately from the Modes Wordpress Plugin. Authored as a TEI document in Modes Complete (file name 'Wordpress plugin documentation') April 2015 Richard Light First edition completed.

3 Modes Wordpress Plugin Free version documentation 1 Installation Modes Wordpress plugin: basic version... 2 Shortcodes... 2 modesdatagrid... 2 modessimplesearch... 2 modeshitlist... 3 modesdetail... 3 modespagelink... 4 modeshome... 4 modessearchsummary... 4 modesnavigator... 5 modeshitcount Configuration... 6 Search pages... 6 Connections... 7 Media and display options... 8 Data sources Data grid options Page Creation plugin General Pages Modes search pages Specifying individual Modes search pages Search Home Page Search Pages Search Results Pages Item Detail Pages Technical details i

4 Modes Wordpress Plugin Free version documentation ii

5 Modes Wordpress Plugin Free version documentation Installation 1 Installation The Modes Wordpress plugin is provided as a zip file, which can be selected and installed using the standard Wordpress 'Add plugin' feature (Select 'Plugins - Add new' from the Wordpress Dashboard). If you are downloading the plugin from the MUA site, save it to your Downloads folder, and then select the option to upload a plugin in.zip format. (This is a link to a separate page, which provides a Browse button.) Click on this button, navigate to your Downloads page, and select the ModesBrowserFree.zip file. The installation of the plugin should then proceed automatically. If you are downloading the free version of the plugin from the public Wordpress plugins directory, search for "Modes Browser" and look through the search results for the plugin. Select it, and the plugin should be installed automatically. [We need to decide whether to upload the free plugin to the public Wordpress plugin folder, or provide it as a download from the MUA site. Searching for 'Modes browser' on this site yields loads of hits, so we would need to make it easy to find. The premium plugin should probably be a download from the MUA site in any case, so that we can exercise some sort of control over who can download it.]

6 Modes Wordpress plugin: basic version Modes Wordpress Plugin Free version documentation 2 Modes Wordpress plugin: basic version 2.1 Shortcodes The Free version of the Modes Wordpress Plugin supports the following shortcodes modesdatagrid A Modes data grid is a set of pre-defined searches of the Modes data, offered to the user as a grid of clickable images with titles. In the basic version of the plugin, only a single data grid is supported. As such, it will normally be placed on the search 'home page', to act as an easy way into the data for users who don't have a specific idea of what they want to search for. The data grid is inserted into the Wordpress page using the shortcode [modesdatagrid]. The settings for the data grid are specified in the Modes Browser Options (Settings - Modes Browser from the Wordpress Dashboard). Specify a number of rows and a number of columns for the data grid, and save the Modes Browser settings. When the Options are redisplayed, input boxes will be provided to allow you to enter details for each row and column you have requested. For each cell you can specify: Heading Query Initial Record a heading for the cell, indicating the type of records which the search will find a query to run on the Modes data. This will use the same syntax as the Modes CGI 'query language', e.g. {Simple name}=*{coin}will search for records with Simple name beginning 'coin' an initial record to represent the search. The stylesheet specified at the beginning of the Data Grid options (by default lightbox.xsl) will be applied to this record. The default action is to display the first image associated with this record modessimplesearch The Modes simple search shortcode puts a word-based search into the current page. This shortcode can take the following parameters: datasource simplesearchindex targetpage the name of the data source which is to be searched the name of the index used to support the word search (by default 'Word search') the title of the page in which the results of the search are to be displayed

7 Modes Wordpress Plugin Free version documentation Modes Wordpress plugin: basic version debug 'yes' or 'no' (default 'no'). If set to 'yes', a series of debug messages is displayed as the page is created and displayed modeshitlist The Modes hit list shortcode displays a page of results for the current search. It has an optional "navigator" feature, which indicates (before and/or after the hitlist) the number of hits and supports navigation through the result set. Alternatively, a separate modesnavigatormodesnavigator shortcode can be declared. This shortcode can take the following parameters: datasource modesquery title navigatortype the name of the data source which is to be searched a fixed Modes query, which will be applied in the absence of a modes_query parameter for the current page a title to be displayed before the hitlist an indication of whether, and where, to place a navigator for this hit list. Possible values are: 'none', 'before', 'after', 'beforeandafter' recordsperpage the number of records to display at one time. Default value is 10 navigatorstyle pagestodisplay targetpage transform the type of navigator control to include. Possible value is: 'paged'. If this is not specified, an 'arrow' style navigator is displayed when the navigatorstyle is 'paged', this parameter specifies the number of pages to display as links. It is recommended that an odd number is specified, so that there are the same number of 'blocks' to the left and right of the current 'page'. Default value is 5 the title of the page in which individual records are to be displayed the XSLT transform which is to be applied to the retrieved records. By default, this is set to the Hit List Stylesheet as specified in the Modes Control Options. Default value is 'htmlsummary.xsl' modesdetail The Modes detail shortcode displays a single record for the current search. It has an optional "navigator" which indicates the number of hits and supports navigation through the result set. This shortcode can take the following parameters: datasource modesquery title the name of the data source which is to be searched a fixed Modes query, which will be applied in the absence of a modes_query parameter for the current page a title to be displayed before the record

8 Modes Wordpress plugin: basic version Modes Wordpress Plugin Free version documentation navigatortype an indication of whether, and where, to place a navigator for this hit list. Possible values are: 'none', 'before', 'after', 'beforeandafter' recordsperpage the number of records to display at one time. Default value is 10 navigatorstyle pagestodisplay targetpage transform imagemaxsize the type of navigator control to include. Possible value is: 'paged'. If this is not specified, an 'arrow' style navigator is displayed when the navigatorstyle is 'paged', this parameter specifies the number of pages to display as links. It is recommended that an odd number is specified, so that there are the same number of 'blocks' to the left and right of the current 'page'. Default value is 5 the title of the page in which individual records are to be displayed the XSLT transform which is to be applied to the retrieved records. By default, this is set to the Item Detail Stylesheet as specified in the Modes Control Options. Default value is 'htmldetail.xsl' The maximum size, in pixels, of any images that are displayed. By default this is set to the value of the Image Max Size as specified in the Modes Control Options (which has a default value of 200) modespagelink Displays a hyperlink to the page specified by the pagetitle or pageid parameter. Can take the following parameters: linkcaption pagetitle pageid The text to describe the link. Default value is the pagetitle, if specified The title of the page which is the target of the link The numerical id of the target page modeshome Displays a hyperlink to the home page for Modes searching. Can take the following parameters: homecaption pagetitle pageid The text to describe the link. Default value is 'Home page' The title of the page which is the target of the link The numerical id of the target page modessearchsummary The Modes search summary displays a user-friendly summary of the currently active search.

9 Modes Wordpress Plugin Free version documentation Modes Wordpress plugin: basic version This shortcode takes the following parameters: format leadin nosearch separator The format in which to display the search. Supported values are 'full' (default) and 'keywords'. 'full' gives a pseudo-english summary of the search parameters, while 'keywords' just displays the search terms The text to display before the search itself (default 'query: ') The text to display when no search has been specified (default 'No search specified') The string with which to separate multiple search terms (when using the 'keywords' option). Default '/' modesnavigator The Modes navigator can be declared explicitly as a free-standing shortcode in its own right, rather than implicitly via parameters in modeshitlist or modesdetail. As well as declaring a single navigator which contains all the required information, it is possible to declare two separate navigators for a datasource: one containing the navigation arrows/page buttons and the other displaying the navigation status. This design is intended to provide flexibility in how navigation information is incorporated into the web page. This shortcode takes the following parameters: datasource navigatorstyle displaystatus specifies the data source to be navigated the type of navigator control to include. Possible values are: 'paged' and 'status'. If this is not specified, an 'arrow' style navigator is displayed if set to 'no', the rubric 'Record(s) X [to Y] of Z' is suppressed, and only the navigator buttons or page links are displayed modeshitcount The number of hits found by the current search can be displayed separately, as well as forming part of the modesnavigator display. The shortcode is replaced by a <span> element containing just the number of hits (e.g. '485'). This shortcode takes the following parameters: datasource the name of the data source to which the hit count applies

10 Configuration Modes Wordpress Plugin Free version documentation 3 Configuration Before the Modes Wordpress Plugin shortcodes can be used to access your Modes data, you need to set up some system-wide settings. You do this in the Modes Browser Options dialogue, which you can find from the Wordpress Dashboard, by selecting 'Settings - Modes Browser'. 3.1 Search pages The Search pages section allows you to specify the pages which you are using to search for Modes records, and to display them on your site. This information is used by the modespagelink and modeshome shortcodes to construct links to these pages. If you use the Modes Page Creation plugin, the default values for these pages will be completed for you. Site pages Record the titles of all the pages containing Modes Wordpress plugin shortcode, separated by commas. Home page Record the title of the 'home page' for your Modes data searches. This page will typically contain a modesdatagrid shortcode, and/or a modessimplesearch. Hitlist page Record the title of the main 'hitlist page' which displays the results of your Modes searches. This page will typically contain a modeshitlist shortcode.

11 Modes Wordpress Plugin Free version documentation Configuration Item detail page Record the title of the main 'item detail page' which displays single records found by your Modes searches. This page will typically contain a modesdetail shortcode. 3.2 Connections This section must be completed before any connection can be made between the Wordpress site and your Modes environment. Domain name Enter the name of the domain in which your Wordpress site is installed. Omit the initial ' and any trailing '/'. By default, this will be set to the correct value by Wordpress. Script folder Enter the relative path within your domain to the scripts folder. This should include leading and trailing '/'s. Example: /scripts/

12 Configuration Modes Wordpress Plugin Free version documentation Published as Linked Data? If the locally-hosted Modes data which you are searching has been published as Linked Data (using the Modes Linked Data Framework), set this to 'yes'. Otherwise, set it to 'no'. Script domain If you access your Modes data using a different server to the one which hosts your Wordpress site, enter the domain name of the Modes server here. This will normally be a 'local' domain, i.e. a machine name or local IP address, e.g.: If you are using a script domain, you will need to have a copy of the cgiforwarder program installed in the Wordpress server's scripts folder. This program (as the name suggests) will forward all HTTP requests to the separate Modes server. Internal script folder If you have specified a 'script domain', enter the relative path within this domain to the scripts folder. This should include leading and trailing '/'s. Example: /cgi-bin/ Transport Specify the type of transport which the Modes CGI program should use to access the Modes server. Example: tcpip Server name Specify the name of the Modes server process which the Modes CGI program should use to access the Modes server. This will often be the machine name. Example: localhost 3.3 Media and display options This section sets up the defaults for searching, displaying records and retrieving images.

13 Modes Wordpress Plugin Free version documentation Configuration Hit list records per page Specify the number of records to be displayed at a time in a hit list. Default value is 10. Hit list stylesheet Specify the XSLT transform which will be used by default to display 'hit lists' (sets of retrieved records). Default value: 'htmlsummary.xsl'. Example: mymodeshitlist.xsl Item detail stylesheet Specify the XSLT transform which will be used by default to display 'detail' (individual retrieved records). Default value: 'htmldetail.xsl'. Example: mymodesdetail.xsl

14 Configuration Modes Wordpress Plugin Free version documentation Image folder Images will be displayed using the Modes image display program. Accordingly, the image folder should be specified as a local pathname, but with '/' instead of '\' between each level. Example: c:/modesresources/multimedia/pictures/ Image max. size Images will be displayed using the Modes image display program. Specify the maximum size, in pixels, that images should have by default. Default value is 300. Example: 200 Simple search index The name of the index to be used for simple searches (i.e. word searches). Defaul value is 'Word search'. Example: Phrase index Facets to display [premium] Specify the default set of indexes which are to be used when displaying modesfacets as part of the results of an indexed search. Enter a set of index names, separated by commas. Example: Simple names,place index,production date Facets stylesheet [premium] Specify the XSLT transform which will be used by default to display facet values. Default value: 'facets.xsl'. Example: myfacets.xsl 3.4 Data sources The Data sources section allows you to specify one or more sources of Modes data for your web site. It also allows you to say which data source should be used by default: this removes the need to specify a data source within your shortcodes.

15 Modes Wordpress Plugin Free version documentation Configuration Start by recording the number of data sources you wish to declare, and Save your settings. When the Modes Browser Options dialogue is re-displayed, there will be sections provided for you to record the number of data sources you have specified. Name Invent a name for the data source, and record it here. It is suggested that you use lower-case letters, and avoid putting any spaces into the name. Example: main_data Application Specify the name of the Modes application within which the data file lives. Example: Object File name Specify the name of the Modes data file. This should be the real filename (minus the '.nx1' suffix), not the 'friendly' name which is displayed in Modes. Example: MyData Image subfolder If the images for this file are stored in a sub-folder within the multimedia folder, specify it here. Example: public_images/ External domain It is possible to access Modes data in files which are hosted on external systems, so long as they have been published as Linked Data. Record the name of the domain here, minus the ' prefix. Example: collections.wordsworth.org.uk The system will use the application and filename you have specified to create suitable URLs. e.g.:

16 Configuration Modes Wordpress Plugin Free version documentation 3.5 Data grid options The Modes data grid acts as a 'home page' for users wanting to search your Modes data. It provides a set of ready-to-run searches which will give the user a good idea of what type of material you hold, without them having to second-guess this by running their own searches. The Data Grid Options dialogue lets you set up your data grid. Before you can specify the settings for your data grid, you must enter the number of rows and columns which the grid is to have, and then Save your settings. The Data Grid Options dialogue will then be re-displayed, with enough entries for you to record the details of your data grid: Data grid stylesheet This XSLT transform will convert the records you have chosen as Initial records so they can be displayed in the data grid. The default transform (lightbox.xsl) displays the first image associated with the record.

17 Modes Wordpress Plugin Free version documentation Configuration Heading The heading to be displayed in the data grid. This should concisely state the type of records which will be retrieved by selecting this cell. Example: Archaeology Query The Query specifies the search that will be carried out on the selected Modes data file. It uses the 'Modes query language', which is also used by the Modes CGI program. This takes the general form: {[indexname]}[relation]{[value]}where [indexname] is the index to search, [relation] is '=' (exact match) or '=*' (starts with), and [value] is one or more data values, with multiple values separated by ' '. Example: {Simple name}={coin token} Initial record The primary key of the record to be used as an example of this search. (As noted above, by default the first image associated with this record will be displayed in the data grid.) Example: BCRTM:1930.1

18 Page Creation plugin Modes Wordpress Plugin Free version documentation 4 Page Creation plugin The Modes Page Creation plugin is a 'support' plugin which creates a number of pages on your Wordpress site to support the Modes Wordpress plugin. To install the Page Creation plugin, download the file modespages.zip from the MUA web site, and use the option to install a local zip file. After you have installed the Page Creation plugin, go to Settings - Modes search pages in the Wordpress Dashboard, and use the menus there to specify and then create your pages. The Page Creation plugin will not provide you with a complete website. What it will do is to create the pages you decide to include in your site and put some initial content into those pages. In particular, it will put correctly-formatted Wordpress shortcodes into your Modes search and results pages. This will allow you to test that your Modes searches actually work with your data. You will need to use standard Wordpress page-editing facilities to give your web site appropriate content. You may also wish to create additional pages, or add blog posts to your web site. Again, there are standard Wordpress facilities which allow you to do this. 4.1 General Pages The plugin allows you to create all the pages required for a complete simple museum web site. First you are offered a set of general pages for this web site.

19 Modes Wordpress Plugin Free version documentation Page Creation plugin Decide which of the suggested pages you would like to have in your site, and ensure that the check box under Page required? is checked for those pages. If you wish, you can also alter the title of any page and its initial content. (Note, however, that you can alter the title, using the standard Wordpress editing facilities, at any time after the page has been created. You will certainly need to update the page content in this way.) 4.2 Modes search pages At the bottom of the main pages menu, there is a section for Modes search pages. Again, you can change the page titles if you wish, but the meaning of the Page required? check box is different. The plugin assumes that you will want to create at least one of each of these pages, so you should only check this box if you want more than one of any particular page. Once you have made your changes to the page details, press Save Page Details. You should now check and if necessary update the settings for individual Modes search pages. See the following sections for details. Once you have set up everything up to your satisfaction, press Create Pages to actually create your pages. The menu will be re-displayed, and the column on the right will indicate which of the pages listed have actually been created. 4.3 Specifying individual Modes search pages The following sections describe how to specify what will appear in the individual pages for searching your Modes data and displaying the results. Three types of pages are supported: Search pages Search results pages pages whose main purpose is to let the user search your Modes data, either by entering their own search criteria or by following a pre-selected search which you have set up pages which show an overview of the results of the current search. This overview may take the form of a paged list of records, a timeline

20 Page Creation plugin Modes Wordpress Plugin Free version documentation Item detail pages and/or a map. Controls may also be provided to refine the current search pages which show the detail of the individual items found by the current search. As with the search results pages, the user will be able to 'navigate' through the results For each type of page, a number of possible Wordpress shortcodes is listed. You can choose which of those shortcodes you actually want to appear on the page when the Page Creation plugin creates it. Once the page exists, you will need to use the standard Wordpress Pages command to edit it, since it will have no content apart from your Modes-related shortcodes. Some of the features listed in the different types of page are flagged as [premium]. If you are using the free version of the Modes Wordpress plugin, these shortcodes will still be inserted into the page if you select them, but they will have no effect when the finished page is displayed to your users. 4.4 Search Home Page There is a row of tabs across the top of the main Modes Pages Options screen. When the screen is first displayed, the Site Pages tab is active. To the right of this tab, there are tabs for specifying the content of individual Modes search pages.

21 Modes Wordpress Plugin Free version documentation Page Creation plugin The second of these tabs controls the content of the Modes search home page. This is the page from which users of your site can start to explore your Modes data. Before creating the page, you can specify which of the following features it will contain: Hit list page link Simple search Index search [premium] Data grid Data grid rows Data grid columns a hyperlink to the hit list page a simple (word-based) search box a set of index searches a data grid the number of rows in the data grid the number of columns in the data grid By default, the search home page will contain a simple search control and a data grid with two rows and two columns.

22 Page Creation plugin Modes Wordpress Plugin Free version documentation After you have made the adjustments to the page settings, press Save Page Settings to store your settings. Then press Create Page: Our Collections to actually create the page. 4.5 Search Pages The third tab in the Modes Pages Options screen controls the content of other Modes search pages, if you have asked to set up additional search pages. At the top of the page there is a drop-down list of the search pages you have created. Start by selecting the particular page whose settings you wish to specify and then press Update Page. Before creating the page, you can then specify which of the following features it will contain: Home page link Hit list page link a hyperlink to the home page for Modes searches a hyperlink to the hit list page

23 Modes Wordpress Plugin Free version documentation Page Creation plugin Simple search Index search [premium] Data grid Data grid rows Data grid columns a simple (word-based) search box a set of index searches a data grid the number of rows in the data grid the number of columns in the data grid By default, the search page will contain a link to the search home page and an index search control. After you have made the adjustments to the page settings, press Save Page Settings to store your settings. Then press Create Page: Modes Search Page to actually create the page. 4.6 Search Results Pages The fourth tab in the Modes Pages Options screen controls the content of your Modes search result page(s).

24 Page Creation plugin Modes Wordpress Plugin Free version documentation At the top of the page there is a drop-down list of the search result pages you have created. Start by selecting the particular page whose settings you wish to specify and then press Update Page. Before creating the page, you can then specify which of the following features it will contain: Home page link Simple search Map [premium] Timeline [premium] Hit list Facets [premium] Detail a hyperlink to the home page for Modes searches a simple (word-based) search box to refine the current search a map displaying the search results geographically a timeline displaying the search results temporally a paged list of the search results a set of facets, showing index entries which match the current search results as links which will further refine the current search a paged set of detailed records for the current search By default, the search result page will contain a link to the search home page, a simple search control, a hit list and facets. After you have made the adjustments to the page settings, press Save Page Settings to store your settings. Then press Create Page: Modes Search Results Page to actually create the page.

25 Modes Wordpress Plugin Free version documentation Page Creation plugin 4.7 Item Detail Pages The final tab in the Modes Pages Options screen controls the content of your Modes item detail page(s). At the top of the page there is a drop-down list of the item detail pages you have created. Start by selecting the particular page whose settings you wish to specify and then press Update Page. Before creating the page, you can then specify which of the following features it will contain: Home page link Hit list page link Simple search Detail a hyperlink to the home page for Modes searches a hyperlink to the search results page a simple (word-based) search box to refine the current search a paged set of detailed records for the current search By default, each item detail page will contain a link to the search home page, a link to the search results page and a set of detailed records. After you have made the adjustments to the page settings, press Save Page Settings to store your settings. Then press Create Page: Modes Search Item Detail Page to actually create the page.

26 Technical details Modes Wordpress Plugin Free version documentation 5 Technical details This section describes how the Modes Wordpress Plugin works, from a technical perspective. The Modes Wordpress plugin is designed to work 'out of the box' as far as possible, once the essential connection information has been specified. However, this does rely on certain software components and documents/controls being in the expected place. Files and folders When you install any Wordpress plugin, the installer creates a folder within the wp-content/ plugins folder in your Wordpress environment. Thus, the Modes plugin will be found here, in a folder called 'modesbrowser-free' (or 'modesbrowser' for the premium version). Within this folder, there are subfolders js containing the javascript code libraries, css containing CSS stylesheets, and xslt containing XSLT transforms. This installation strategy means that it is not possible for the plugin installer to ensure that all the necessary support programs are in place. [Could maybe add some runtime checks] Method of working The plugin uses standard PHP techniques to dynamically generate content for the target page. However, the actual operation of the plugin is carried out by javascript code, some of it generated on the fly by PHP, and some provided in pre-written javascript libraries. The plugin uses AJAX calls to get Modes content, and updates the page when this content is returned. Since this happens asynchronously, you can often see the page being updated with additional content after it has loaded. Most of the XSLT transforms are actually applied by the Modes CGI program which retrieves content from your Modes data files. This means that you need to copy the XSLT stylesheets which you intend to use from the xslt folder within the modesbrowser folder, and place those copies in the scripts folder where your copy of ModesCGI.exe is installed. If your web server is not the same machine as your Modes data server, this means that the XSLT copies need to go onto the data server machine.