Rudimental Context Awareness - code and citations.

[ajmetz]

At EPrints Services,
I had a few support tickets,
that involved context-aware ORCID link rendering,
and implemented a rudimentary means to achieve this,
by passing a 'for_use_in' key and corresponding value,
as parameters/options to render citation calls (described in the POD and xml epc comments of this pull request).

Following this, I've been advised to raise a Git Issue to discuss if the ORCID Support plugin should be updated to have some notion of context awareness: #32 (comment)

Do you think it should have some notion of context awareness?

I've forked the ORCID Support repository and created a new branch to show the kind of change(s) I had made in my support tickets.

A new or different approach could be taken,
or what I have done could be improved upon to deliver an ideal result.

Changes include:

• Additional POD and comments within #Rendering ORCIDs section.

• Tab spacing on 'use' statements to align with package statement.

• Additional use of fc and blessed,
  via feature pragma on Perl 5.16 and higher,
  and Scalar::Util packages respectively.

• Changes to initial variables:
  $repository instead of $session;
  $item and $for_use_in declared/defined;
  Some regular expressions defined.

• Replacement of $session with $repository.

• $uri definition refactored to ternary style.

• $orcid replaced with $valid_orcid (validated against a regex).

• Long-winded if statement, replaced with simply: if ($show_orcid).

• Initial creation of orcid link removed.

• Initial creation of static folder parameters for a get_url method added.

• Append child statements for an ORCID link replaced with a validated return value from a render citation call. Validation includes a check for child nodes as a means to ensuring non-empty xhtml. I am unsure if this is the best approach for that purpose.

• Original ORCID Link updates to $person_span now occur only if we have a $valid_orcid_link.

Regarding discussions and improvements...

'for_use_in' could perhaps be more specific - orcid_link_rendering_intent or orcid_link_for_use_in, or orcid_link_context;
or something broad could be adopted by EPrints across all render_citation calls.
Perhaps the mandatory 'in' from $state was originally intended to be used to derive context from, and could be adapted?

While working on the rudimentary means to achieve context-awareness for an ORCID link, I was hopping into z_orcid_support.pl and editing it multiple times, simply to change an ORCID link. Is an ORCID link a candidate for an object, and thus z_orcid_support could be left alone, and merely call a class to obtain a new ORCID link object instance as needed?

There are a bunch of display toggles in my rudimentary version.
A colleague has suggested in future, these toggles could be in config values set within cfg/cfg.d.
At an earlier stage, these were set using YAML config files, taking advantage of CPAN::Meta::YAML being in Perl Core since Perl 5.14 via the following:

use CPAN::Meta::YAML qw(LoadFile); # Standard module in Core Perl since Perl 5.14
my  $matches_yes            =   qr/^(y|yes)$/i; # case insensitive y or yes and an exact match - no partial matches like yesterday.
my  $email_display_setting  =   -e $repository->config('archiveroot').'/cfg/orcid_in_email.yml'
                                && (LoadFile($repository->config('archiveroot').'/cfg/orcid_in_email.yml')->{'Show ORCID In Email'} =~ $matches_yes);

# Example YAML Configuration File for email_display_setting:
%YAML 1.2
---
Show ORCID In Email: yes
...

On Perl 5.14 the YAML file needed a clearly indicated YAML document end via either a blank line at the end of the file, or a '...' rather than simply ending with an end of file and no blank line. Perl 5.16 didn't seem to care as much.

Email clients can be years behind web browsers. When rendering for an email context, consider whether linking to an svg file or more traditional gif or png incarnations of the ORCID ID badge image is more appropriate. A free trial of litmus could be used to make an assessment: https://www.litmus.com/email-previews
Email image embedding is not presently an option since EPrints Core does not currently implement content id headers for file attachments, and that could be changed.

The rudimental approach in this pull request currently requires a series of xml citation files to exist in cfg/citations/eprint/
Rather than all possibilities always being required to be accounted for with xml files,
a more dynamic approach could be taken. Similar to how a citation style is simply the filename of the citation to look for, there could be similar flexibility, allowing the xml citation files to be created as and when needed, rather than ever-present.
A middle ground would be a set of basic ones assumed to be present,
with more able to be created as needed.

The use of the fc feature for folded case comparisons,
means this rudimentary approach requires Perl 5.16 or higher.
That may or may not be desired,
and could be easily solved by requiring exact case sensitive matches.

I've used the standard EPrints POD footer, and its copyright notices,
and am unsure if that's appropriate for forks of this that will appear on the eprintsug / EPrints User Group.

The default behaviour is web page context.
Default assumptions may need to be discussed and decided upon.

As such, there is lots to discuss as regards the best way forwards,
with this as a starting point for these discussions.

[photomedia]

I think that context aware link rendering for ORCID would be a good feature, but could we elaborate here more clearly on what issues/pages/screens in the repository rendering this is currently needed? What are the rendering problems that currently show up with ORCIDs that this would solve? Thank you.

[ajmetz]

Thank you.

Does the elaboration below prove useful?
This is just what was done in my rudimentary approach,
and I remain happy to consider other ways forwards in this regard.

For email html body contexts:
This was looked at, when a client wanted improvements to ORCID badge rendering in Item Request Emails, Embargo Expiry Alert Emails, and Move With Author Emails.

• A full image link rather than a relative image link for the ORCID badge.
• Less reliance on CSS for a pop-up tooltip. In my rudimentary solution I resorted to providing an alt text attribute for the img tag instead for email contexts.
• Width and height defined for the ORCID badge so even if it does not load due to email client settings on image downloads, the image placeholder is a size that does not disrupt the layout of the email.
• The ability to easily toggle ORCID badges on or off for email contexts.

Coversheet context:
This was done for a client that didn't want the phrase "ORCID logo" appearing on their coversheets.

• Omit the ORCID badge from the ORCID link, rather than have it convert into the phrase "ORCID logo" written in the middle of the citation.

For CSV context:
This was done as part of a client's request to add a citation column to the CSV export of one of their custom reports.

• Here I actually used a virtual field ( https://www.youtube.com/watch?v=qu92uyXzHEA ) to get CSV appropriate citation rendering, as your standard conversion of xhtml to text via tree_to_utf8 left a lot of white space in citations that then required stripping, and part of the process was again (as with Coversheet context)...
• ...rendering an ORCID link intended for plain text contexts.

Overall:
The idea is to keep z_orcid_support.pl simple,
by deferring to different xml templates,
to account for different rendering contexts.
Then one can edit such xml templates to get things as desired for each different context.
Display setting toggles can also show or hide ORCID Links overall, or in specific contexts.