Beginnings of a section describing User interface programming.

Following is an edited version of a support email describing how to make additional elements from a finding aid appear in the results display. As such it may give you the flavor of the programming techniques needed to modify the behavior of the middleware at a fairly low level. Reading through this example deliberately should guide you through all the steps needed for this, which is just a specific instance of the general way a search set and a result set get things added to them, how the result set gets that new thing filtered and added to the output XML and finally how the XSL is used to get that XML out to HTML.

When one clicks on one of the links in the left-hand "outline" on a "standard view", the middleware does an XPat search for the container, or other region (seen as the focusrgn parameter on the URL) that contains a particular byte offset (the link having been created by the middleware when it created the "standard view".

If you add a debug=xml to that URL, you should see something like:

<FullTextResults>
  <Results>
    <DocContent>
      <RegionContent>
         <controlaccess>
....
       </controlaccess>
....

Look at DLXSROOT/web/f/findaid/text.xml, which is the file used by the "standard" view. (Note that you can always see what files are in play by adding a debug=tpl to the URL.) In this file you should see the following snippet of XML:

  <FullTextResults>
    <DocEncodingType><?DOC_ENCODING_TYPE_XML?></DocEncodingType>
    <Results><?RESULTS_XML?></Results>
  </FullTextResults>

It is the RESULTS_XML PI that is filled in with everything from DocContent onward. In this case, searches have been done by the middleware, at some point the EAD controlaccess region was searched for by the middleware and returned by XPat.

          <xsl:when test="$FocusRegion = 'controlaccess'">
            <xsl:apply-templates select="controlaccess"/>
          </xsl:when>

There is a RESULTS_XML PI in reslist.xml. So, what we have to do is make sure that, for a "search terms in context" view, (i.e., CGI params: view=reslist;subview=detail), the RESULTS_PI triggers not only the header and the hits "kwics" (aka keywords in context) and all the containers and other top level elements that include those kwics, but also the controlaccess element.

A useful technique is to run under the Perl debugger with the URL parameters and follow through the code. In this case, with view=reslist;subview=detail, FindaidApp.pm takes us to DetailViewSearchesAndFilter_XML. From there to FindaidClass::SubmitItemKwicSearches. This leads us to DLXSROOT/lib/DLXSApp/FullTextApp::DetailViewSearches and this goes to FindaidClass::DoDetailResultsSearches. This in turn uses DLXSROOT/lib/DLXSClass/FullTextClass::AddSimpleSearches (or AddBooleanSearches). This adds "ScopingHeads", that is, the containers and such that contain the kwics.

Having gone through all that code, you can see how the kwics and their "ScopingHeads" are added to the search set. Finally, the search set is submitted (back up in FindaidClass::DoDetailResultsSearches) and the results are added to an XPatResultSet.

Later, the result set is filtered. As in all cases, the result set is an iterator and the results one by one are handed to the middleware, in occurrence order, so that a container head will come before any kwics within that container and so on.

So, you'll want to subclass FindaidClass.pm (see this reference to writing DLXS subclasses) so that you can override of SubmitItemKwicSearches. In that method, you add a call to a routine that will add, to the search set called 'kwicresults', a search for the proper additional controlaccess region within your finding aid.

Then comes the filtering step. You will need to add an extra elsif block to the method ScopedDetailResultsFilter_XML in your FindaidClass.pm subclass. You'll see that there are various if, elsif blocks that check for different labels (added at search time) so that the code knows how to package/filter the result for output to the XML file. Your new elsif will check for results with a label (such as "additionalcontrolaccess" or some such) and add the returned XML to the output results.

Then of course, you'll probably have to deal with some XSL to filter the new controlaccess region in a way that fits the output for this HTML page rather than the "focused region" type of "standard view" output for "subject terms/controlaccess."