=== CitePress ===
Contributors: Ying-Tsong Chen
Tags: ORCID, publications, bibliography, Crossref, research
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.6.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Build consistent publication lists from ORCID, with bibliographic metadata normalized through Crossref and Europe PMC.

== Description ==

CitePress creates publication lists for researchers from their public ORCID records.

ORCID is used primarily to identify which works belong to a researcher. When a DOI is available, CitePress uses Crossref as the primary bibliographic metadata source and uses Europe PMC conservatively to fill missing fields. For genuine non-DOI works, CitePress can fall back to metadata stored in ORCID, including contributors and EID when available.

Design principle: missing metadata is preferable to confidently displaying the wrong publication.

CitePress is standalone and does not require Researcher Profiles for ORCID. It includes its own presentation CSS.

Author and maintainer: Ying-Tsong Chen 陳盈璁 (with ChatGPT)

== Tested Work Types ==

The following ORCID work types have been tested with CitePress:

* journal-article
* preprint

Other ORCID work types may be returned by the API but are not currently claimed as tested display formats.

== How It Works ==

For works with a DOI:

ORCID -> DOI -> Crossref -> bibliographic metadata

If selected Crossref fields are missing, Europe PMC may fill those fields without replacing valid Crossref data.

For works without a DOI, CitePress reads the individual ORCID work. It may use ORCID contributors, journal, year, and EID. A conservative title-based Europe PMC DOI recovery is attempted only when the normalized title matches exactly and at least publication year or journal also corroborates the match. Ambiguous matches are rejected.

Preprints use a separate platform resolver. CitePress does not assume that an ordinary Crossref container-title is the preprint server. Known platform metadata and recognized hosting domains can identify bioRxiv, medRxiv, arXiv, ChemRxiv, or Research Square. If the platform cannot be determined confidently, it is left blank.

== Installation ==

1. In WordPress, go to Plugins -> Add Plugin -> Upload Plugin.
2. Upload the CitePress ZIP file.
3. Install and activate CitePress.
4. Go to Settings -> CitePress.
5. Enter the researcher ORCID iD and your ORCID Public API Client ID and Client Secret.
6. Save the settings.
7. Insert a CitePress Publications block, or use a CitePress shortcode, in a page or post.

== ORCID Public API Credentials ==

CitePress uses the ORCID Public API with the /read-public scope.

Create ORCID Public API credentials through the developer tools associated with your ORCID account. ORCID will provide two values:

* Client ID
* Client Secret

Copy both values to Settings -> CitePress and save them.

These credentials are not your ORCID password. CitePress uses them only to obtain a read-public access token and read publicly visible ORCID data. CitePress does not write to or modify ORCID records.


== Gutenberg Block ==

CitePress 0.6.0 adds a native CitePress Publications block for the WordPress block editor. The block uses the same PHP renderer as the shortcode.

Block settings are intentionally limited to a small tested set:

* Works to display: Journal articles (default), Preprints, or All works
* Year range: All years or Since YYYY
* Order: Newest to oldest (default) or Oldest to newest
* DOI: Show (default) or Hide
* Layout: Authors -> Title -> Journal -> Details (default), or Title -> Authors -> Journal -> Details
* Additional CSS class(es), using WordPress's standard Advanced block setting

CitePress does not add per-field font, color, or spacing controls. Site-specific presentation can be customized with CSS using CitePress's stable CSS classes.

== Shortcodes ==

Journal articles (default):

[citepress]

All works:

[citepress type="all"]

Preprints:

[citepress type="preprint"]

Optional presentation parameters:

[citepress since="2020" order="desc" doi="show" layout="authors-first"]

The Gutenberg block and shortcode share the same renderer.

The Gutenberg block uses the Researcher ORCID iD configured in Settings -> CitePress. Shortcodes use the same site-wide ORCID by default. For backward compatibility, an explicit orcid="..." shortcode attribute is still accepted and overrides the site-wide value.

== Displayed Metadata ==

Tested journal-article display includes, when available:

* Title
* Authors
* Researcher's own name in bold
* Journal
* Publication year
* Volume
* Issue
* Page range or article/e-location number
* DOI
* EID fallback for genuine non-DOI records

Tested preprint display includes, when available:

* Title
* Authors
* Researcher's own name in bold
* Publication year
* Preprint platform
* DOI

The citation line is rendered in the form:

Journal Year Volume(Issue): pages/article number

Journal/platform is bold italic, year is italic, volume is bold, and issue and locator use normal weight.

== Data Refresh and Cache ==

CitePress does not run scheduled background synchronization and does not create a WordPress cron job.

CitePress 0.4.3 adds two cache/refresh modes:

* Automatic (default): uses normal cache lifetimes and lazy refresh.
* Manual: successful publication metadata does not expire automatically and remains unchanged until Clear CitePress Cache is used. Failed/missing lookups still expire after a short period so temporary API failures are retried.

In Manual mode, CitePress also keeps one rollback snapshot. When you choose Prepare Manual Update, CitePress first saves the current CitePress cache, then clears the active cache. The next publication-page request retrieves fresh data. If the refreshed result is unsatisfactory, use Restore Previous Version to restore the saved cache state. Only one previous version is retained; a later manual update replaces the older rollback snapshot.

Instead, it uses lazy refresh. Cached data are checked when a page containing a CitePress publication list is requested. If a cache entry is still valid, CitePress uses it. If it has expired, fresh metadata are retrieved on that page request and the cache is rebuilt.

Long-lived normalized metadata may be cached for up to one year, researcher profile/detail data for up to one week, and selected discovery/error results for one day. The ORCID works list itself is currently cached for one day. Therefore CitePress does not promise a single fixed synchronization interval; it refreshes individual cached resources on demand according to their cache lifetime.

If you have just changed your ORCID record, upgraded CitePress, or are simply impatient, go to Settings -> CitePress and click "Clear CitePress Cache".

Clearing the cache does not perform an immediate background synchronization. It removes CitePress cached metadata; fresh data are retrieved the next time a page containing the relevant CitePress shortcode is requested.

== Cache Summary ==

* ORCID works list: 1 day
* ORCID individual work details: up to 7 days
* Researcher canonical ORCID name: up to 7 days
* Successful normalized DOI metadata / selected successful resolutions: up to 1 year
* Failed or missing lookup results: generally 1 day

These lifetimes are implementation details and may change in future releases.

== External Services and Privacy ==

CitePress communicates with external scholarly metadata services to build publication lists.

ORCID:
Used to retrieve public researcher profiles and works. Requests contain an ORCID iD and use a read-public access token obtained from the configured Client ID and Client Secret.

Crossref:
Used to retrieve bibliographic metadata for DOI-identified works. Requests contain publication DOIs.

Europe PMC:
Used as a conservative fallback for missing bibliographic fields and, in limited cases, for DOI recovery. Requests may contain a DOI or publication title and bibliographic information used to verify a match.

CitePress does not send ordinary website visitor names, email addresses, login credentials, or browsing profiles to these services for publication-list generation. External services receive normal HTTP request information such as the requesting server's network address in the usual course of web requests.

Use of these services is subject to their respective terms and privacy policies.

== Styling ==

CitePress 0.4.x includes its own CSS and does not depend on Researcher Profiles for ORCID or theme-specific ORCID styles.

Primary CSS classes include:

.citepress-publications
.citepress-year
.citepress-list
.citepress-item
.citepress-title
.citepress-authors
.citepress-citation
.citepress-journal
.citepress-citation-year
.citepress-volume
.citepress-doi
.citepress-eid

Site administrators can override these selectors in their theme if desired.

== Troubleshooting ==

= I changed my ORCID record but CitePress still shows the old data. =

Use Settings -> CitePress -> Clear CitePress Cache, then reload the publication page.

= The first page load is slow. =

This can be normal after installation or a cache clear because CitePress may need to contact ORCID, Crossref, and Europe PMC. Subsequent requests use cached metadata.

= A publication has only a title. =

Check the metadata stored in ORCID. Older records may have only an EID or incomplete contributor/journal metadata. If a DOI exists, adding the DOI to the ORCID record is the most reliable solution.

= Why does CitePress sometimes leave a field blank? =

CitePress intentionally uses conservative metadata matching. If a value cannot be determined reliably, it prefers to omit it rather than guess.

== Changelog ==

= 0.6.1 =

* Removed the ORCID iD field from the Gutenberg block.
* Added a site-wide Researcher ORCID iD setting under Settings -> CitePress.
* Gutenberg blocks always use the site-wide Researcher ORCID iD.
* Shortcodes now use the site-wide ORCID when no orcid attribute is supplied.
* Existing shortcodes with an explicit orcid attribute remain compatible.


= 0.6.0 =
* Added a native Gutenberg CitePress Publications block.
* Added All years / Since YYYY filtering.
* Added newest-first (default) and oldest-first ordering.
* Added Show / Hide DOI display control.
* Added Authors-first (default) and Title-first layouts.
* Uses WordPress's native Additional CSS class(es) support instead of adding a custom styling panel.
* Refactored shortcode and block output to use one shared PHP renderer.
* Existing cache, Manual mode, and rollback behavior are unchanged.

= 0.5.0 =
* Added one-level rollback for Manual cache mode.
* Prepare Manual Update saves the current CitePress cache before clearing it.
* Restore Previous Version reinstates the saved publication-data cache if a refresh is unsatisfactory.
* Only one previous snapshot is retained; each new manual update replaces the older rollback snapshot.
* Rollback restores the full CitePress metadata cache, not only rendered HTML.
* Automatic mode behavior is unchanged.


= 0.4.3 =
* Added Automatic and Manual cache/refresh modes.
* Manual mode keeps successful cached publication data indefinitely until Clear CitePress Cache is used.
* Failed/missing lookups still use short-lived cache entries even in Manual mode.
* Changing cache mode automatically clears existing CitePress transients so the selected policy takes effect immediately.
* No scheduled background synchronization or WP-Cron job is used.


= 0.4.2 =
* Added formal author/maintainer and GPLv2-or-later metadata.
* Added WordPress.org-style plugin documentation.
* Documented tested WordPress 7.1 compatibility.
* Documented ORCID Public API credential setup.
* Documented external services and privacy behavior.
* Documented lazy refresh, cache lifetimes, and manual cache clearing.
* No resolver or publication-rendering behavior changed from 0.4.1.

= 0.4.1 =
* Added publication year to each bibliographic citation.
* Journal/platform remains bold italic; citation year is italic; volume is bold.
* Large year-group headings inherit the site's normal text color.

= 0.4.0 =
* Made CitePress standalone at the presentation layer.
* Removed dependency on legacy ORCID plugin CSS.
* Added CitePress-owned publication styling.

== License ==

CitePress is free software licensed under the GNU General Public License version 2 or any later version.


== Changelog ==

= 0.6.2 =

* Added a work-type display filter to the Gutenberg block: Journal articles (default), Preprints, or All works.
* The filter affects rendering only; updating still retrieves the complete ORCID works list.
* Shortcode defaults to journal articles; use type="all" to display all work types.
