August 2022 - Citation formats and CITEME.txt
August 2022-current: Citation formats and introduction to CITEME.txt
Citation formats and the creation of a CITEME.txt file have been introduced recently in Symbiota (Pull Request #261).
Default formats
Symbiota portals have now a standardized way for users to cite them and their data. These default, dynamic, citation formats have been introduced (and can be customized as necessary) and can be found in the [root]/includes directory:
- General portal: found in the
citationportal_template.php; - Collection (for collections not published in GBIF):
citationcollection_template.php; - Collection published in GBIF:
citationgbif_template.php; - Dataset:
citationdataset_template.php;
Additionally, the template for the Usage Policy page ([root]/includes/usagepolicy_template.php) has been updated to include the dynamic formats as well. This means that portal managers that would like to customize citation formats should only do it by modifying the formats themselves.
Where in Symbiota are formats used?
The citation formats are inserted in certain context-specific pages and in downloads.
The general portal format will be seen by default in the Usage Policy page.
The collection formats will be inserted in each Collection Profile page, depending on whether each collection is published to GBIF or not.
Example of collection profile page that has not been published to GBIF in the NEON Biorepository Data Portal.
Example of collection profile page that has been published to GBIF in the NEON Biorepository Data Portal.
The dataset format will be inserted in each Dataset page.
All of the formats might be included, one at a time, in the CITEME.txt file included with the downloaded package from a Symbiota portal, depending on the context in which a package was requested. For instance, downloading the results of a search will include a CITEME.txt file that will contain a citationportal.php format. On the other hand, downloading a DwCA from a collection page (which is published to GBIF), will include the citationgbif.php format. This behavior was designed to better inform users where their occurrence data is coming from and when.
Example of a CITEME.txt file packaged within a DwCA download from the NEON Biorepository Data Portal.
Activating format usage
To make sure your portal uses the citation formats, all you have to do is make a copy of each citation format template, and remove the _template string from their file name.
Customizing formats
Please note that the citation formats should only include plain text and/or PHP. No HTML should be included in the formats, because they are used in different contexts.
To customize each format, open the copies of the templates and make the desired changes. Save them. As the copies of the templates (without the _template string in the file name) won't be tracked by Git, they won't be overwritten by future releases.
GBIF widget
The Collection Profile page ([root]/collections/misc/collprofiles.php) has been updated to include each appropriate citation format (if not published to GBIF, it will include by default the citationcollection.php format; if published to GBIF, it will include the citationgbif.php format).
If a collection has been published to GBIF, the page will fetch the GBIF citations widget using the collection-specific GBIF Dataset Key.
Example of a GBIF widget added to a NEON Biorepository Data Portal collection profile.
Dependencies
For collections that publish to GBIF, data referring to the GBIF-specific citation format will be fetched from the uses GBIF's API v1 to fetch collections information (like gbiftitle and DOI).]