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> ....
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
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.
text.xsl, which is used to transform the
text.xmldata, you will find:
The template for<xsl:when test="$FocusRegion = 'controlaccess'"> <xsl:apply-templates select="controlaccess"/> </xsl:when>
text.components.xsl. To add this to the "Search terms in context" view, we have to make sure that
reslist.xml, which is what is used for that view (again
debug=tplwill show that), has to have a PI that triggers a handler that eventually requests XPat to do a search for the
controlaccesswithin the finding aid in question.
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:
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
A useful technique is to run under the Perl debugger with the URL
parameters and follow through the code. In this case, with
takes us to
DetailViewSearchesAndFilter_XML. From there
FindaidClass::SubmitItemKwicSearches. This leads us
and this goes to
This in turn uses
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
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
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
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
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
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."