=== Primo Vars ===
Contributors: zurtri
Tags: shortcode, variables, contact details, phone, email
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Your phone number, email address and social links, defined once on one settings screen and output anywhere with a shortcode or block.

== Description ==

Contact details have a habit of appearing on a dozen pages. When the phone number or email changes, you get to find every one of them - a real pain!

Primo Vars fixes that. Define a value once on a single settings screen, give it a name, and use its shortcode wherever you need it. Change the value and every page follows.

Each variable has a **type**, and the type does the fiddly work for you:

* **Phone**: renders a tappable `tel:` link, while displaying the number exactly as you typed it, brackets, spaces, country code and all.
* **Email**: renders a `mailto:` link with the address obfuscated against scrapers.
* **Link**: renders an anchor, with an optional custom label.
* **Address**: a multi-line field that keeps your line breaks.
* **Multi-line text**: the same, for opening hours, a disclaimer, anything that runs to more than one line.
* **Text**: renders plain text, for anything else.

= Usage =

    [primo_var key="phone"]
    [primo_var key="email"]
    [primo_var key="facebook" text="Follow us"]
    [primo_var key="phone" raw="1"]

`raw="1"` returns the plain value with no link, for when you are building your own markup around it.

In a theme template:

    <?php echo primo_vars_get( 'phone' ); ?>
    <?php echo primo_vars_get( 'phone', true ); // raw ?>

= In the block editor =

Insert the **Primo Var** block, pick a variable from the dropdown, and it
renders exactly what the shortcode would. Use the shortcode when you want a
value inline in a sentence, and the block when it stands on its own.

= Starter variables =

A fresh install creates seven empty variables to fill in: phone, email,
address, facebook, instagram, linkedin and youtube. Delete the ones you do not
want, or add your own. A YouTube channel is just a Link, the same as any other
social profile.

= For developers =

Filter `primo_vars_output` to change what any variable renders, from the
shortcode, the block and `primo_vars_get()` alike. It fires for a variable
that is defined but left empty, which is what the example below relies on;
it does not fire for a key that is not defined at all, since all three entry
points return an empty string before reaching this filter in that case.

    add_filter( 'primo_vars_output', function ( $html, $var, $atts ) {
        if ( '' === $html && 'phone' === $var['type'] ) {
            return 'Call the office';
        }
        return $html;
    }, 10, 3 );

The HTML handed to the filter is already escaped. Anything your callback adds
is yours to escape.

= Phone numbers with extra text =

Real phone numbers are messy. `+61 491 570 156 Option 2` and `(08) 8123 1234` both display exactly as typed, and both produce a correct dial link. The trailing "Option 2" is not dialled.

Where the number cannot be worked out automatically, no link is shown rather than a wrong one. That covers vanity numbers like `1300 PRIMO`, and two numbers written in one field such as `(08) 8123 1234 (0412 345 678)`. Fill in the optional **Dial as** field on that row and it will link exactly as you specify.

== Installation ==

1. Upload the plugin to `/wp-content/plugins/` and activate it.
2. Go to **Settings → Primo Vars**.
3. Fill in the values for the starter variables, or add your own.

== Frequently Asked Questions ==

= What happens if I use a shortcode for a variable I have not filled in? =

Nothing renders. Visitors never see a placeholder or an error message.

= Why was my web address rejected? =

A link needs its scheme, so use `https://facebook.com/you` rather than `facebook.com/you`. The plugin tells you which variable it refused and leaves the old value in place rather than saving something that would not work.

= Does this work in widgets? =

Yes. Widget areas have been block-based since WordPress 5.8, so add the Primo
Var block, or a Shortcode block holding `[primo_var]`, to any widget area or
site editor template.

Navigation menu labels are the exception: WordPress does not run shortcodes
there, and this plugin deliberately does not add a filter to make it, because
broad `do_shortcode()` filters widen the injection surface for everyone.

= Does it phone home? =

No. No external requests, no tracking.

== Screenshots ==

1. The Primo Vars settings screen.
2. The Primo Var block in the editor.
3. Contact details rendered on the front end.

== Changelog ==

= 1.0.0 =
* First release.
