View Definition

Views are defined as an individual xml file based on the global view element of the protocol schema.

Local Views

The name of a local view corresponds to the filename ignoring its suffix .xml.

View Sections

A view consists out of several sections:

<view>
  <structure> ... </structure>
  <indexingElement> ... </indexingElement>
  <mapping> ... </mapping>
  <filter> ... </filter>
</view>

Structure section

The structure section contains a pure xml schema document starting with the <xs:schema> element. There is no TAPIR specific information in this section. The structure described by this xml schema is the structure the xml response document will have the wrapper produces.

How data from the local database maps to this structure is defined in the mapping section.

Indexing Element section

The indexing element is just a single element giving the xpath to the local element/concept of the structure which defines a record. There can be multiple indexing elements and every indexing element in a response is considered as a record which is the basis for counting records and paging.

    <indexingElement path="/dataset/record"/>

Mapping section

This section maps the locally defined view structure to well known concepts. So keep in mind that finally the wrapper does a two way mapping - one mapping between the local database schema and conceptual schemas, and then another between a view structure and conceptual schemas. This way it is possible to define views independent of the local database schema.

Every element of the local structure can be mapped like this with the <node> being the local structure (and therefore is identified without a namespace) and <concept> a concept taken from a conceptual schema:

    <mapping xmlns:dwc="http://digir.net/schema/conceptual/darwin/2003/1.0">
      <node path="/dataset/record/DateLastModified"/>
        <concept path="dwc:/DateLastModified"/>
      </node>
      <node path="/dataset/record/InstitutionCode"/>
        <concept path="dwc:/InstitutionCode"/>
      </node>
      ...

It is also possible to use fixed value, literals, in a view mapping. Within a <node> tag you can use as many concepts or literals as you want. They will be concatenated in the output:

      ...
      <node path="/dataset/record/InstitutionCode"/>
        <literal value="InstCode "/>
        <concept path="dwc:/InstitutionCode"/>
      </node>
      ...

... will result in the output to e.g InstCode? BGBM if the InstitutionCode? concept produces BGBM from the backend database. If the concept(s) used in a view mapping have multiple mappings to the backend database, all possible permutations of the different mapping combinations within a single mapping will be created by the wrapper. So something like this:

      ...
      <node path="/Specimens/Specimen/Taxon/HigherTaxon"/>
        <literal value="Higher taxon: "/>
        <concept path="foo:/Taxa/Taxon/HigherTaxon"/>
      </node>
      ...

with a database mapping like this (see datasource specific DraftConfigurationFiles):

   <concept path="/Taxa/Taxon/HigherTaxon">
      <mapping><dbattribute attribute="Family" tablealias="taxa" type="text" /></mapping>
      <mapping><dbattribute attribute="Order" tablealias="taxa" type="text" /></mapping>
      <mapping><dbattribute attribute="Class" tablealias="taxa" type="text" /></mapping>
   </concept>

will result into the following mappings:

    <mapping>
        <literal value="Higher taxon: "/>
        <dbattribute attribute="Family" tablealias="taxa" type="text"/>
    </mapping>
    <mapping>
        <literal value="Higher taxon: "/>
        <dbattribute attribute="Order" tablealias="taxa" type="text"/>
    </mapping>
    <mapping>
        <literal value="Higher taxon: "/>
        <dbattribute attribute="Class" tablealias="taxa" type="text"/>
    </mapping>

with a possible result being:

<Specimens>
 <Specimen>
  <Taxon>
   <HigherTaxon>Higher taxon: Asteraceae</HigherTaxon>   
   <HigherTaxon>Higher taxon: Asterales</HigherTaxon>   
   <HigherTaxon>Higher taxon: Magnoliopsida</HigherTaxon>   
  </Taxon>   
 </Specimen>   
</Specimens>

Automapping

If we want to create a view for DarwinCore? or ABCD, which are also conceptual schemas, we would have to copy the ABCD schema document into the structure section, define an indexing element /DataSets/DataSet/Units/Unit and then tediously map every single concept of ABCD to the local node. For those cases when all local structure xpaths are identical to a concept of an conceptual schema, the PyWrapper has an automapping function. To simply map all local ABCD view nodes to the identical ABCD concepts do this:

    ...
    <mapping automapping="true"/>
    ...

Filter section

The optional filter section is used in local views only. This is the only difference to views referenced vie URIs in search requests. The main purpose of a filter (which looks exactly like filters in a normal search request) is to define parameters inside the filter which act like literals in the context of filters but do not have a fixed value. Instead they take the value from http-get parameters with the same name as defined in the parameter tag.

Example filter to search for records via their scientific name, country or id in a simple http get based URL:

    <filter xmlns:dwc='http://digir.net/schema/conceptual/darwin/2003/1.0'>
    	<and>
        <like>
            <concept path='dwc:/ScientificName' />
            <parameter name='scientificname' />
        </like>
        <like>
            <concept path='dwc:/County' />
            <parameter name='country' />
        </like>
        <like>
            <concept path='dwc:/CatalogNumber' />
            <parameter name='id' />
        </like>
        </and>
    </filter>

When creating filters in views be aware that parameters are treated slightly different from the regular DraftFilterEvaluation by the wrapper. In the filter above 3 different parameters are defined that can be combined in a view operation. You want them to be combined with a logical and not an or, so searching for specific names in a country is possible. But what happens if one parameter is not supplied? In the regular filter evaluation a non existing concept evaluates to False. If a non supplied parameters would evaluat to False in an <and> based filter, the entire filter will always be False. So non supplied parameters are simply removed from the filter - no matter if they are within an <or> or <and>.