The MIRCqueryresult Schema

From MircWiki
Jump to: navigation, search

This article describes technical requirements for participation in the MIRC community as a storage service. Additional information is provided in The MIRCquery Schema and The MIRCdocument Schema.

The intended audience for this article is the developer or system administrator of a teaching file system who is implementing a MIRC storage service to make the system’s teaching files available to the MIRC community.

1 The MIRCqueryresult Schema

The reply of a storage service to a query service is an XML object in the MIRCqueryresult schema. A MIRCqueryresult object is in the form:

<MIRCqueryresult>
    <preamble> . . . </preamble>
    <MIRCdocument docref=”...URL...”>
        <title> . . . </title>
        <author> . . . </author>
        <abstract> . . . </abstract>
        <access> . . . </access>
        <peer-review/>
        <level> . . . </level>
    </MIRCdocument>
</MIRCqueryresult>

There is exactly one MIRCqueryresult element in a query reponse message.

There are zero or one preamble elements in a MIRCqueryresult element. There are zero or more MIRCdocument elements in a MIRCqueryresult element, one for each separate document found by the storage service to match the search criteria in the query.

1.1 preamble

The preamble element is provided in the schema to allow storage services to pass status information to be displayed at the top of the list of query results for the site. The RSNA storage service software, for example, passes the total number of query matches in the preamble element. The value of the preamble element is well-formed HTML text, which must be contained within HTML paragraph tags. The following is an example:

<preamble>
    <p>Total query matches: 751</p>
</preamble>

The preamble element is optional.

1.2 docref

Each MIRCdocument element in a MIRCqueryresult must have a docref attribute containing the URL that references the document. The URL must be a fully qualified path name, including the protocol. The MIRC query service uses this information to provide a list of results to the MIRC user.

1.3 title

The query service uses the title element to provide a heading for the document in the list of query results provided to the user. The title element may not contain other elements.

1.4 author

The query service uses the author element to display the name of an author of the document. If the document has multiple authors, multiple author elements must be provided. The author element may not contain child elements.

1.5 abstract

The query service uses the abstract element to describe the contents of the document to allow a user to determine whether the information is of interest. The abstract element may contain HTML elements to assist in rendering the abstract; however, all the elements must be well-formed.

1.6 access

If the access element is present in a MIRCdocument element, the query service displays its contents in the list of query results to indicate to the user whether the document is freely available. The possible values of the element are:

  • public
  • restricted
  • owner

1.7 level

If the level element is present in a MIRCdocument element, the query service displays its contents in the list of query results to indicate the educational level of the document. The possible values of the element are:

  • primary
  • intermediate
  • advanced

1.8 peer-review

If the peer-review element is present in a MIRCdocument element, the query service displays the words Peer-reviewed under the document in the list of query results. If the element is missing, the query service does not display anything for the peer-reviewed status of the document.

Note that the peer-review element in a MIRCqueryresult is always empty.

2 How a Query Service Renders a MIRCqueryresult

The query service uses the storage service’s MIRCqueryresult to produce an HTML ordered list where each MIRCdocument element generates a list item in the form:

<li>
    <a href=”docref_attribute_value”>title_element_value</a><br/>
    author_element_value<br/>
    access_attribute_value<br/>
    <p>
        abstract_element_value
    </p>
</li>

HTML elements within the title element are not copied.

HTML elements within the abstract element are copied.