The BPS Query Tool
This guide explains how to configure the querytool for different schemas than ABCD and how to create different skins that look very different from the default querytool.
Contents
What are skins and how do I modify them
Skins are reusable configurations for the query tool, that can change the look, form entries and data standards/schemas being used. Each skin is kept in a seperate folder within the querytool configurations configuration/querytool/skins.
Additionally to the skins inside each datasource configuration there is a querytool_prefs.xml file with datasource specific querytool configurations. There you for example specify which skin should be used for this datasource.
Datasource Preference File querytool_prefs.xml
This file is found at configuration/datasources/YOUR_DATASOURCE_NAME/querytool_prefs.xml. New datasources that are created with the configtool use a copy of the datasource skeleton found at configuration/configtool/dsa_skeleton/.
This file is dependant from the "skin.xml" file which is situated in: {BioCASEInstallationFolder}/configuration/querytool/{skinName}/skin.xml.
The preferences file consists of some schema blocks and a single parameters <Skin> that defines the (folder)name of the skin to be used:
<Querytool xmlns="http://www.biocase.org/schemas/qtprefs/1.1">
<Skin>default</Skin>
<Schema ns="http://www.tdwg.org/schemas/abcd/2.06">
<Concepts>
<Concept path="/DataSets/DataSet/Units/Unit/Gathering/Country/Name"/>
<Concept path="/DataSets/DataSet/Units/Unit/Gathering/LocalityText"/>
<Concept path="/DataSets/DataSet/Units/Unit/UnitID"/>
</Concepts>
</Schema>
<Schema ns="http://digir.net/schema/conceptual/darwin/2003/1.0">
<Concepts>
<Concept path="/recordset/record/ScientificName"/>
<Concept path="/recordset/record/Family"/>
<Concept path="/recordset/record/Genus"/>
<Concept path="/recordset/record/Country"/>
</Concepts>
</Schema>
</Querytool>
For every (conceptual) schema, which is identified by its namespace, a list of concepts is given, which will appear on the entry form in the specified order.
Each path written in "querytool_pref.xml" must match a path already defined in the "Concept" element within the file "skin.xml".
Name of the field on the interface will correspond to the name which is defined in the "label" attribute of "Concept" element in "skin.xml". See below for a more detailed description of the "skin.xml" file.
Note: it seems that the element "<Skin>" is not active in the current distribution of Biocase (the query tool always displays the skin which is defined as the default skin).
Querytool Skin Files
Every skin configuration folder configuration/querytool/skins contains all the files needed to produce the output. This includes some html templates (unfortunately without any include mechanism; so no seperate headers or footers), XSLTs to transform the wrapper responses and a general configuration file called skin.xml. The default skin contains the following files:
biocase@peyote:~/bps2/configuration/querytool/skins/default$ ls -1 DarwinCore_Overview.xslt DarwinCore_UnitDetail.xslt datasource.html details.html en_ABCD1.2_CommonTemplates.xslt en_ABCD1.2_DataSetOverview.xslt en_ABCD1.2_UnitDetail.xslt en_ABCD2.0_CommonTemplates.xslt en_ABCD2.0_DataSetOverview_short.xslt en_ABCD2.0_DataSetOverview.xslt en_ABCD2.0_EFG_CommonTemplates.xslt en_ABCD2.0_EFG.xslt en_ABCD2.0_UnitDetail.xslt form.html grouping.html readme.txt recordlist.html skin.xml
The html files are simple html templates used by the corresponding python cgi scripts of the querytool. The recordlist.cgi and detail.cgi scripts need additional XSLT stylesheets to process the wrapper responses and present them as html.
Any editing, deleting, rearranging, translating etc. of the text content and the graphical layout that you may want to do to adapt the default installation to your needs can concern html pages as well as the xslt stylesheets. While the html pages rule the general layout, the xslt stylesheets are responsible for the arrangement of the search results. If you are not acquainted with xslt but would like to change, e.g., the language of captions in the search results, you can safely edit any text within the xslt templates that is NOT included in angle brackets (< >).
skin.xml
This file inside a skin configuraion folder is essential and lists all concepts that can be used in the querytool_prefs.xml. For every concept is gives a label that will be shown in the forms and a datatype, so the forms know whether a like, equals greater/lesser than operation can be performed.
The default skin.xml file looks like this at the top:
<Skin xmlns="http://www.biocase.org/schemas/qtprefs/1.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.biocase.org/schemas/qtprefs/1.1">
<Schema ns="http://www.tdwg.org/schemas/abcd/2.06" label="ABCD 2.06">
<Concepts>
<Concept cops="~" label="Scientific_Name" path="/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/ScientificName/FullScientificNameString" />
<Concept cops="~" label="Higher_Taxon" path="/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/HigherTaxa/HigherTaxon/HigherTaxonName" />
<Concept cops="~" label="Country" path="/DataSets/DataSet/Units/Unit/Gathering/Country/Name"/>
<Concept cops="~" label="Locality" path="/DataSets/DataSet/Units/Unit/Gathering/LocalityText"/>
<Concept cops="~" label="Unit_ID" path="/DataSets/DataSet/Units/Unit/UnitID"/>
</Concepts>
<Grouping concept="/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/ScientificName/FullScientificNameString"/>
<Recordlist stylesheet="en_ABCD2.0_DataSetOverview_short.xslt" limit="10">
<NoRecordMessage>There is no valid record available for your query! <br/>All available records were invalid.</NoRecordMessage>
</Recordlist>
<Details>
<Detail name="unit" stylesheet="en_ABCD2.0_UnitDetail.xslt">
<RecordID parametername="inst" path="/DataSets/DataSet/Units/Unit/SourceInstitutionID"/>
<RecordID parametername="col" path="/DataSets/DataSet/Units/Unit/SourceID"/>
<RecordID parametername="cat" path="/DataSets/DataSet/Units/Unit/UnitID"/>
<NotAvailableMessage>The original data provider seems to be out of service. <br/>No details currently available.</NotAvailableMessage>
</Detail>
</Details>
</Schema>
<Schema>
...
This file defines the configuration of the 3 servlets which are displayed the queytool:
1.Concepts
- This part of the schema defines the input fields of the main query form.
It is dependant from the "querytool_prefs.xsd" file which is situated in: {BioCASEInstallationFolder}/configuration/schemas/ Element "Concepts/Concept" defines the fields which will be available for input in the search interface (they must also be repeated in the "querytool_prefs.xml" which is situated in the configuration folder of a specific skin).
Attribute "Label" defines the legend associated to this field in the search interface.
Attribute "cops" defines a possible numeric comparator ("greater", "smaller", "equals") which can be associated as a filter for a search.
Attribute "Cops" is bound to the "cops" simple type which is defined in the schema "querytool_prefs.xsd" and enumerates the possible comparators.
2.Grouping
- This part of the schema defines the way all the records returned by a search are displayed on an intermediate page.
- It is dependant from an XSLT file which is situated in the same skin folder.
- Details FIXME...
3.Details
- This part of the schema defines the ways the details
- This part of the schema defines the way all the records returned by a search are displayed on an intermediate page. It is dependant from an XSLT file which is situated in the same skin folder.
- Details FIXME...
Details FIXME...
The main query form
The first page of the querytool is the form that allows you to submit searches. The default form looks like this: Upload new attachment "form.jpg"
Apart from the form itself all other html is taken from the above mentioned form.html skin template. In this template there is a place holder for the entry fields. The kind of field, its label and allowed operations () is defined for each datasource in its [# prefs querytool_pref.xml file]
The grouping.cgi page
FIXME...
The recordlist.cgi page
FIXME...
The detail.cgi page(s)
FIXME...
Querytool Scripts
Inside the folder www/querytool you can find the central index.html file redirecting to the form generating CGI script. All the other CGI scripts can be found there, too. Please do not modify them, as they are used for all skins! If you need to change anything modify an existing skin or create a new one based on the default skin folder (duplicate it).