Picklist customization for serial articles

From DLXS Documentation

As of Release_15, new functionality has been added to picklists to create a volume/issue view for serials.

Since the particulars are collection-specific, an API is available in DlpsLocalUtil. However, to use this API, a collection-specific TextClass subclass must be created, and the relevant subroutines from DlpsLocalUtil must be overridden. (I.e., you do not directly invoke the methods from DlpsLocalUtil.)

(Visit Programming Issues to learn more about subclassing and related programming topics.)

In this brief guide, we'll describe how this new functionality works and explain enough to get started developing customized picklist views.

By default, picklists are rendered in “classic mode”, which is the original picklist mode.

If “issue/volume mode” is enabled, picklists will be rendered to show the contents of a collection, volume or issue based on where the idno is truncated.

To understand how idno trunction works, consider a sample idno, “5550190.0011.b02”, which corresponds to an article in the ARKIVOC collection.

Normally, the collection portion of the idno is “5550190”, so we would say that a partial idno of “5550190” maps to a collection view.

Since we map a volume to “5550190.xxxx”, this means that “5550190.0011” maps to a particular volume (probably volume #11, which is named after the year of publication, 2010).

Sicne we map an issue to “5550190.xxxx.x”, which means that “5550190.0011.b” maps to a particular issue (probably volume #11, issue #11).

Since this mapping is arbitrary, subroutines in DlpsLocalUtils.pm (MapCollectionToIdno, MapVolumeToIdno and MapIssueToIdno) can be overridden with the appropriate regular expression to map these values for a given collection.

Let's say we have a collection for which a volume is represented by “xxxxxxx.xx” and an issue is represented by “xxxxxxx.xxxx”. (E.g., “abcdefg.0503” would be volume 5, issue 3.) If we created a subclass called “Example1TC.pm” that subclassed TextClass.pm (and this collection's collmgr record is set to use Example1TC), we would need to turn on the new functionality and override the two mapping subroutines:

 sub UseVolumeIssuePicklist { 1 } # Enable issue/volume mode
 sub MapVolumeToIdno { '\w+\.\w{2}' }
 sub MapIssueToIdno { '\w+\.\w{4}' }

Now when the idno CGI parameter corresponds to “abcdefg.05”, the picklist view for volume 5 is rendered. However, which the idno CGI parameter is “abcdefg.0503”, the picklist view for volume 5, issue 3 is shown.

The API supports many detailed customizations. The most common is a serial that only has issues or volumes but not both (DisableIssuesForPicklist and DisableVolumesForPicklist).

Let's say we have a hypothetical collection that has issues but not volumes, and the issue corresponds to “xxxxxxx.xxxx”. In “Example2TC.pm”, we would need to include the following:

 sub UseVolumeIssuePicklist { 1 } # Enable issue/volume mode
 sub MapIssueToIdno { '\w+\.\w{4}' }
 sub DisableVolumesForPicklist { 1} # Disable volumes

More advanced features includes modifying how volume and issue numbers are located in the item's XML, customizing the logic that determines which view should be rendered, as well as a hook for sorting items in an issue, etc. However, the above should meet most collection-customization needs.

Additionally, the picklist XSL in picklist.xsl and picklistheader.xsl is highly modular and designed for easy customization. For example, you could override :

 <!-- The context is Picklist/Volume -->
 <xsl:template name="groupByVolume">
   <!-- Want to use HTML 5 features like section element and h1 header for each section -->
   <section>
     <h1><xsl:value-of select=”VOLNO”/></h1>
     <xsl:call-template name="IterateIssues"/>
   </section>
 </xsl>