Page History

...

webui.submit.upload.required

JSPUI: Per item visual indicators for browse and search results

Visual indicators per item allow users to mark items in browse and search results. This could be useful in many scenarios, some of them follow:

1. If your repository contains items of different type (articles, book chapters, pictures) you can mark the type of each item using an icon.
2. If your repository has items with bitstreams but also has items with no bitstream, you could indicate this fact to the users using the visual indicators
3. If you have applied copyright licences in the bitstreams or items, you could notify users about that in the browse or result list
4. If you want your users to spot some items out of the list easily or if you want to differentiate some items from the others you could use the visual indicators

The visual indicators extension has the following specs:

1. Multiple marks can be added per item (i.e. mark the type of the item and the availability of the bitstreams) 
2. Easy configuration of the strategy of what mark to display in every item 
3. Marks based on images or a generic class (i.e. a glyphicon icon for bootstrap) 
4. Display tooltip when hovering the mark + localization of the tooltip 
5. Easy addtion of new strategies for any type of mark the user desires 
6. Add css styles for the user to configure the position of the marks in the list row 

Some theory:

A mark is an instance of the class: org.dspace.app.itemmarking.ItemMarkingInfo.

Each mark can have the following properties:

• imageName: a path to the image that will be displayed for the specific mark
• classInfo: the css class to be applied in the mark (useful if you do not want to add an image but just an icon from the bootstrap glyph icons)
• link: the link to be applied in the mark (optional)
• tooltip: the tooltip to be shown when hovering over the mark (optional)

When you need to add a mark in an Item then you need to create a strategy that determined what mark to display per item. Strategy classes need to implement the interface: 

org.dspace.app.itemmarking.ItemMarkingExtractor

Your strategy class just needs to implement the following method from the above Interface:

public ItemMarkingInfo getItemMarkingInfo(Context context, Item item) throws SQLException; 

Which is, given an item, return the Mark info to display.

Currently, there are three Strategies included by default:

ItemMarkingMetadataStrategy

This strategy decides the mark to display per item based on a value of a metadata field (i.e. dc:type)

It accepts two properties:

• • metadataField: the metadata field to be used for searching the value in the form “schema.element.qualifier”
  • mapping: a Java Map of Strings to ItemMarkingInfos

If the String (key of the map) is found as a value in the metadataField field, then the mark denoted by the value of the map will be displayed.

ItemMarkingCollectionStrategy

This strategy decides the mark to display per item based on the collection this item belongs to.

It accepts one property:

• • mapping: a Java Map of Strings to ItemMarkingInfos

The String (key of the map) is the collection handle (i.e.: 123456789/1) and if an items belongs to this collection, the mark denoted by the object of the map will be displayed

ItemMarkingAvailabilityBitStreamStrategy

This strategy decides the mark to display per item based on the availability (exists or not) of a bitstream within the item.

It accepts to properties:

• • nonAvailableImageName: the image to display for the mark if no bitstreams exist for the item
  • nonAvailableImageName: the image to display for the mark if at least one bistream exist for the item

Moreover, this strategy add a link in the mark (in case there are bitstreams in the item) to the first bitstream of the item

How to:

In order to enable a mark for the result or browse list you need to change the option:

webui.itemlist.columns

of the dspace.cfg file.

You need to include a ‘mark_[value]’ key in any column order you like. Do not add the brackets and you can replace the “value” with any word has a meaning for your marking type. You may add multiple marks (i.e.: one in the first column and one at the last)

For example, the following line is a valid option value:

webui.itemlist.columns = mark_type, dc.date.issued(date), dc.title, dc.contributor.*, mark_availability

In the aforementioned case, you just added two marks, one in the first column for the type of the item and one in the last item for the availability.

Now it’s time to declare what “mark_type” and “mark_availability” means. This is done in the Spring configuration file config/sping/api/item-marking.xml, via the dependency injection feature.

In this file, for each “mark_[value]” key you add in the dspace.cfg file, you need to add a Spring bean with id=org.dspace.app.itemmarking.ItemMarkingExtractor.[value]. The class of this bean must be an implementation of org.dspace.app.itemmarking.ItemMarkingExtractor.

That’s all!

For our example, we need to declare two beans (one for “mark_type” and one for  “mark_availability”).

<!-- Enable this strategy in order to mark item based on the value of a metadata field -->
<bean class="org.dspace.app.itemmarking.ItemMarkingMetadataStrategy" id="org.dspace.app.itemmarking.ItemMarkingExtractor.type">
     <property name="metadataField" value="dc.type" />
     <property name="mapping" ref="typeMap"/>
</bean>

<!-- Enable this strategy in order to mark items based on the availability of their bitstreams -->
<bean class="org.dspace.app.itemmarking.ItemMarkingAvailabilityBitstreamStrategy" id="org.dspace.app.itemmarking.ItemMarkingExtractor.availability">
     <property name="availableImageName" value="image/available.png" />
     <property name="nonAvailableImageName" value="image/nonavailable.png" />
</bean>

For the “mark_type”, we have declared the strategy to be ItemMarkingMetadataStrategy which means that the value of a metadata field (dc.type in our case) will determine the mark of each item. Here is the mapping:

<bean class="java.util.HashMap" id="typeMap">
       <constructor-arg>
             <map>
       	        <entry>
                   <key>         
 					  <value>image</value>
                   </key>
                   <ref bean="type1MarkingInfo"/>
                </entry>
                <entry>
                   <key>         
					  <value>video</value>
                   </key>
                   <ref bean="type2MarkingInfo"/>
                 </entry>
              </map> 
       </constructor-arg>
</bean>

Thus, if the value of dc.type field is equal to image the “type1MarkingInfo” bean will be used for the marking, if it is equal to video the “type2MarkingInfo” bean will be used, otherwise, no mark will be displayed.

<bean class="org.dspace.app.itemmarking.ItemMarkingInfo" id="type1MarkingInfo">
       <property name="classInfo" value="glyphicon glyphicon-picture"/>
       <property name="tooltip" value="itemlist.mark.type1MarkingInfo"/>
</bean>
<bean class="org.dspace.app.itemmarking.ItemMarkingInfo" id="type2MarkingInfo">
       <property name="imageName" value="image/type2.png"/>
       <property name="tooltip" value="itemlist.mark.type2MarkingInfo"/>
</bean>

Tooltip property contains the localized key to display.

Keep in mind that the Strategy that you may write can have its own logic on how to create the ItemMarkingInfo per item. The only requirement of the feature is to add in the Spring configuration file the initial beans one for each mark you have declared in the dspace.cfg file.

Styling:

The title for the column of each mark is titled based on the localized key “itemlist.mark_[value]”, so you just need to add the specific keys in the messages.propertied files.

Moreover, the following CSS styles are applied to the various aspects of the mark:

• mark_[value]_th: a style applied to the column header
• mark_[value]_tr: a style applied to the each row

Add these classes to the css file and apply any style you like (like centering the text or the image)