In citations with many authors, make the "et al." text a link that expands the full author list

[laurenwalker]

No description provided.

[mbjones]

That could work for the display, but we also need to be sure that the "Copy Citation" includes the full author list in the copied citation.

When designing this feature change, we might want to consider different solutions for different parts of the UI. The datset landing page seems like a good place to display the full citation always, whereas the search results listing might be best if we use the standard journal approach of using et al. for any list of 3 or more authors (e.g., Jones, Jones and Smith, Jones et al. are the only three formats that are traditionally used when abbreviating).

[robyngit]

How it works now

Decisions about how the authors are formatted in the MetadataView AND the search SearchResultsView are made in three areas of the CitationView, all under the render function:

• If the model (CitationView.model) set on the view is a CitationModel, then the authors are formatted here:

  metacatui/src/js/views/CitationView.js

  Lines 80 to 122 in 26e1a46

  	// Format the Author textarea else if (this.model.type == "CitationModel") {
  	if (authorText.length > 0) {
  	var authors = authorText.split(", "),
  	count = 0,
  	authorText = "";
  	_.each(authors, function (author) {
  	count++;
  	if(count == 6){
  	authorText += ", et al. ";
  	return;
  	}
  	else if(count > 6)
  	return;
  	if(count > 1){
  	if(authors.length > 2) authorText += ",";
  	if (count == authors.length) authorText += " and";
  	if (authors.length > 1) authorText += " ";
  	}
  	// Checking for incorrectly escaped characters
  	if (/&[A-Za-z0-9]/.test(author)) {
  	// initializing the DOM parser
  	var parser = new DOMParser();
  	// parsing the incorrectly escaped `&`
  	var unescapeAmpersand = parser.parseFromString(author, 'text/html');
  	// unescaping the & and retrieving the actual character
  	var unescapedString = parser.parseFromString(unescapeAmpersand.body.textContent, 'text/html');
  	// saving the correct author text before displaying
  	author = unescapedString.body.textContent;
  	}
  	authorText += author;
  	if (count == authors.length) authorText += ". ";
  	});

• If the model is not a CitationModel, but there is a model set on CitationView.metadata, then the authors are formatted in one of two places:
  • If the metadata model is an EML model, the authors are formatted here:

    metacatui/src/js/views/CitationView.js

    Lines 152 to 182 in 26e1a46

    	var authors = this.metadata.get("creator"),
    	count = 0,
    	authorText = "";
    	_.each(authors, function (author) {
    	count++;
    	if(count == 6){
    	authorText += ", et al. ";
    	return;
    	}
    	else if(count > 6)
    	return;
    	//Get the individual's name, or position name, or organization name, in that order
    	var name = author.get("individualName") ?
    	_.flatten([author.get("individualName").givenName, author.get("individualName").surName]).join(" ") :
    	author.get("positionName") || author.get("organizationName");
    	if(count > 1){
    	if(authors.length > 2) authorText += ",";
    	if (count == authors.length) authorText += " and";
    	if (authors.length > 1) authorText += " ";
    	}
    	authorText += name;
    	if (count == authors.length) authorText += ". ";
    	});

  • Otherwise, if the authors are formatted here:

    metacatui/src/js/views/CitationView.js

    Lines 185 to 210 in 26e1a46

    	var authors = this.metadata.get("origin"),
    	count = 0,
    	authorText = "";
    	_.each(authors, function (author) {
    	count++;
    	if(count == 6){
    	authorText += ", et al. ";
    	return;
    	}
    	else if(count > 6)
    	return;
    	if(count > 1){
    	if(authors.length > 2) authorText += ",";
    	if (count == authors.length) authorText += " and";
    	if (authors.length > 1) authorText += " ";
    	}
    	authorText += author;
    	if (count == authors.length) authorText += ". ";
    	});

Besides the MetadataView and the SearchResultsView, the CitationView is used in six other views the: CitationListView, MdqRunView, MetricModalView, ProvChartView, RegisterCitationView, and the EML211EditorView

The CitationView doesn't use a template, but creates each HTML element and adds classes in the render function as needed. E.g.:

metacatui/src/js/views/CitationView.js

Line 224 in 26e1a46

var authorEl = $(document.createElement("span")).addClass("author").text(authorText);

• Using a template would not only make this view consistent with the pattern we use in other MetacatUI views, but it would facilitate more easily making display changes. We could also easily switch out the template in different circumstances.

The copy citation button works by highlighting whatever text is in some targeted HTML element and adding it the the clipboard. To do this, it uses a library that looks for an element ID that is set on the button's data-clipboard-target attribute (see https://github.com/NCEAS/metacatui/blob/main/src/js/templates/metadataControls.html#L4)

How we can update it

Here is a path forward we can take to create the expandable author list:

• Create a default citationView.html template, to which we pass variables to insert. Remove the creation of HTML elements from the render function as much as possible.
• Remove the formatting of the authors from the render function. Pass the author list to the template, and allow the template to create the author string.
• Add an expandable boolean option to the template. When it's true, and when there are 6+ authors, make the "et al." text a link that expands the full author list. (If there is no bootstrap class that works for this type of expandable section, then the click/expand behaviour will need to be controlled in the CitationView)
  • When expandable is false, just show the et al. like we currently do
  • To decide: when the list is expanded, we presumably remove the et al. text. What should the user click to collapse back to the truncated author list? Perhaps add an icon?
• Update the behaviour of the copy citation button so that we copy the complete citation, not the truncated et al. version.
  • To decide: should the button first expand the citation, then copy it? Should citation be collapsed again after copying?
  • The button must work even if there is not an expandable section
• Add a boolean option to the citationView (e.g. expandable) that decides whether the template is rendered with the expandable section or without (when there are 6+ authors). Default to False. Set to True for the MetadataView.
• Test how the citations appear in all eight views in which the CitationView is used, and with 1, 2, 3, and 6+ authors.

Optionally, we should also:

• Make the whitespace / indentation consistent in the CitationView
• Add JSdocs to the CitationView (currently there are none)
• Remove the unused getAuthorText function from the MetadataView

[vchendrix]

@robyngit It is exciting to see that the citation functionality is being refactored! I wanted to point out that there is a ticket that we submitted a while back to be able to format the citation differently. What you are doing here might address this but I wanted to point you to this issue ticket just incase there are additional things you may be able to consider in this refactor.

[robyngit]

This is really helpful, @vchendrix, thank you! I think addressing both these issues at the same time makes a lot of sense.

[robyngit]

Update: The CitationView is tricky to make updates to at the moment since it formats a whole bunch of different models (EML models, solr results, Citation models, etc.) in a whole bunch of different ways depending on context. To resolve this, the plan is to add on to the CitationModel so that the model attributes can be populated from different sources (EML, Solr result, data object, etc.), not just the results from the metrics service. The Citation View will then render only the Citation Model. All of the logic that maps various model attributes to parts of a citation will be moved from the CitationView to the CitationModel.

This will hopefully achieve the following:

• make the CitationView consistent with how we separate model vs view logic in MetacatUI
• make the rest of the steps for this issue much more straight-forward
• provide a solid foundation for eventually implementing more flexible and configurable citation formats (Ability to format Citation #567)

[mbjones]

Sounds great!

[robyngit]

Update:

The Citation model now has new functionality for populating its attributes from other models used for citations. I've made it modular so that it's easier to modify how attributes are populated, and which attributes we pull in from source models (e.g. the "project" field, see #567).

The CitationView only renders content directly from the CitationModel, but can still be initialized with other types of models. (These are just passed to the CitationModel, which handles pulling in the right content). It still accepts both the "model", "metadata" and "id" init options so that it is backwards compatible. All HTML creation has been moved to a new template.

The CitationView currently works for the most common use cases, such as in the search results and the metadata landing page, but there's work to do to cover all contexts and render all available information, like the "Cites Data" list from the citationMetadata attribute.

Once this is done, I will add a template option for an expandable list of authors!

[robyngit]

The Citation view & model still need review, and the CitationModel needs unit tests, but otherwise they are both at a state now where we can easily add a template with an expandable section to show all authors.

While updating the view & model, I was able to make some other minor improvements:

Switch from using <span> tag to <time> tag for dates in citations. (more semantic)

Before:

<span class="pubdate">2017. </span>

After:

<time class="pubdate" datetime="2017">2017. </time>

Improve formatting of strings returned from the metrics service, remove curly braces.

Before:

After:

Add date and title to citations shown in the prov popup

Before:

After:

[robyngit]

I'm currently working on designing and building the new expandable author list layout. I've included some images showing the direction that I'm heading with it and welcome any and all feedback at this stage!

Before

Here is an example dataset as it's currently displayed on the ADC. It's not clear that there are so many contributors to this dataset. In fact, there are 46!

After

Here is the new WIP design.

When a user lands on a page, by default, as many authors as possible are displayed, plus the last author preceded by and ellipse. Bold, highlighted text at the end of the list indicates how many more authors there are for the dataset.

Either the more authors button or the ... ellipse text can be clicked to expand to see the complete list:

The "Cite this dataset" button below can be clicked to bring up a modal that shows the complete citation with all authors

Other details

• This design is based on layouts that are common in online scientific journals. In every example I could find, journals use the same collapsible/expandable list to accommodate publications with many authors. Here are a few examples with links to articles that have too many authors to display at once: Nature, Science, The Lancet, NEJM, Cell, Cancer
• I added the citation modal so that we have a place to eventually provide citations in different formats: improve citation display to support multiple styles #973

[dvirlar2]

That's awesome, Robyn! Does the dataset citation change based upon whether a user is viewing the condensed list or full list? For example, if someone's viewing the condensed list, would the "Cite this dataset" button truncate the author list to et al, and vice versa if they're looking at the expanded list?

I don't think it's a big deal one way or the other, just curious :)

[robyngit]

Thanks @dvirlar2! No, the "Cite this dataset" list will always show the full author list, regardless of whether or not the landing page list is expanded or collapsed. Is that the behaviour you think users would expect?

[dvirlar2]

@robyngit I asked Bruce how many authors he was expecting to add on his dataset, and he said between 24-30. You had asked him for a number, so I wanted to let you know! Here's the specific message if you want it.

As for the expected behavior, I think it's what I would expect, but I don't think it's what most users would expect. I'll have to think on that a bit more.