=== Scholar Metrics Panels ===
Contributors: reviewer2tools
Tags: research, openalex, institutions, academia, shortcode
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display customizable OpenAlex research panels for a specific institution or country using two explicit shortcodes.

== Description ==

Scholar Metrics Panels adds two independent research-intelligence panels to WordPress:

* An institution panel with research statistics, output trends, papers, topics, and collaborators.
* A country panel listing leading institutions for the selected research topics.

Panels appear only where you add a shortcode. The plugin does not inspect posts, match taxonomies, add panels automatically, create institution approval queues, or schedule cron jobs. An institution shortcode never falls back to a country panel, and a country shortcode never tries to resolve an institution.

Both panel types share a configurable visual system. Shared colors and frame styling are managed on Design, while each panel tab has its own layout selection and panel-specific controls. Each panel tab provides its own searchable subject selector, live preview, and shortcode generator.

= Shortcodes =

`[smpxq_lab_panel id="I27837315" layout="editorial"]`

Displays the OpenAlex institution with that ID using the editorial layout. The `institution` attribute is also accepted as an alias for `id`.

`[smpxq_country_panel country="Germany" layout="compact"]`

Displays leading institutions in the specified country using the compact layout. A two-letter country code can be passed with `code`, for example `[smpxq_country_panel code="DE" layout="card"]`.

Both panels support the shared `card`, `bordered`, `compact`, `flat`, `editorial`, `ledger`, `masthead`, and `minimal` layouts. Institution panels also support `profile`, `dashboard`, and `split`; country panels also support `atlas`, `leaderboard`, and `directory`. If omitted or invalid for that panel type, each shortcode uses its saved default.

Each shortcode requires an explicit institution or country. Invalid or unavailable subjects render no panel.

= Data and caching =

The Get started tab controls research topics, the look-back window, cache duration, request timeout, and the OpenAlex API key. The Institution panel tab controls its paper heading, paper count, and list style.

Cached data refreshes during a shortcode request after it expires. If OpenAlex is temporarily unavailable, the plugin uses its last good cached panel when one exists. No scheduled tasks are created.

== External services ==

This plugin connects to the OpenAlex API (`https://api.openalex.org`) to retrieve public scholarly information.

Requests occur when an uncached or expired shortcode panel is viewed, when an administrator searches for an institution or topic, or when an administrator previews a real institution.

Depending on the action, requests can contain an explicit OpenAlex institution identifier, a two-letter country code, selected OpenAlex topic identifiers, an administrator-entered institution or topic search phrase, the site's home URL in the user-agent header, and the API key configured by the administrator. OpenAlex also receives normal HTTP request metadata such as the site's server IP address and user-agent.

The plugin does not send visitor form data, cookies, page URLs, or WordPress user data to OpenAlex. It sets no cookies and creates no visitor profiles.

OpenAlex is operated by OurResearch.

* Service information: https://openalex.org/
* API documentation: https://developers.openalex.org/
* Terms and privacy: https://openalex.org/legal

== Installation ==

1. Upload the `scholar-metrics-panels` folder to `/wp-content/plugins/`, or install the ZIP from Plugins → Add New.
2. Activate Scholar Metrics Panels.
3. Open Scholar Metrics in the main admin menu and begin on Get started, then configure Design, Institution panel, and Country panel.
4. Add an institution shortcode or country shortcode to any shortcode-capable content area.

== Frequently Asked Questions ==

= Does the plugin add panels to posts automatically? =

No. It registers no content filter or automatic placement logic. A panel appears only where its explicit shortcode is used.

= Does it match institutions from categories, tags, custom fields, or post content? =

No. The institution ID and country are supplied directly in their respective shortcodes.

= Will an institution panel fall back to a country panel? =

No. The two shortcodes are completely separate and do not fall back to one another.

= Does it create cron jobs? =

No. Expired data is refreshed on demand when the relevant shortcode is viewed.

= Do I need an OpenAlex API key? =

Not strictly. The plugin can make anonymous OpenAlex requests without a key, but those requests have a very limited allowance. A free API key provides a much larger daily quota and more reliable access, so it is strongly recommended. Create a key in your OpenAlex account, then add it under Get started.

= How do I find an institution ID? =

On Institution panel, search for a real institution. The result shows its OpenAlex ID. You can also find IDs on OpenAlex.

= Can I customize each panel type? =

Yes. Shared colors and frame settings apply to both from Design. Institution and country layouts are selected independently on their dedicated tabs and included in the generated shortcode. Other panel-specific content controls also remain independent.

= Does this plugin track visitors? =

No. It sets no cookies and stores no personal visitor data.

== Screenshots ==

1. Institution panel settings, shortcode, and live preview.
2. Country panel settings, shortcode, and live preview.
3. Get started and research-topic configuration.
4. Shared Design tab and Tools-tab cache controls.

== Changelog ==

= 1.0.0 =
Initial release.
