BHS Client

A WordPress plugin for fetching and displaying assets from a bhs-storehouse server.

Built for the Brooklyn Historical Society by Hard G.

This plugin is currently under active development. Do not use on a production site.

Requirements:

• PHP 5.3+
• WordPress 4.4+

Use

BHS Client offers a number of ways to integrate BHS Storehouse data into a WordPress site, depending on your needs and your level of technical expertise.

Before using the plugin, be sure that you've configured an API Base: the base URL associated with your BHS Storehouse site. This value can be set via Dashboard > Settings > BHS Client, or by defining the BHS_API_BASE constant in wp-config.php:

define( 'BHS_API_BASE', 'https://example.com/wp-json/bhs/v1/' );

The Shortcode and Template functions methods both take advantage of a robust caching system, which ensures maximum performance and minimum traffic to the Storehouse server, by caching content for 24 hours. All local record caches are invalidated when you save a WordPress post, which makes it easy for content authors to clear old data from the cache without waiting for the 24 hour expiration.

Method 1: Shortcode

The [bhs_record] shortcode allows post authors to display content in a WordPress post. A few examples:

Display record abc123

[bhs_record identifier="abc123"]

Display record abc123, showing even those fields that are empty

[bhs_record identifier="abc123" hide_empty=0]

Display record abc123, showing only the Title and Description fields

[bhs_record identifier="abc123" fields="title,description"]

The markup generated by the shortcode is in the following format:

<ul class="bhs-record-data">
    <li class="bhs-field-title">
        <div class="bhs-field-name">Title</div>
        <div class="bhs-field-value">This Is The Title Of My Record</div>
    </li>

    <li class="bhs-field-description">
        <div class="bhs-field-name">Description</div>
        <div class="bhs-field-value">This Is The Description Of My Record</div>
    </li>
</ul>

Minimal styling is included, which can easily be overridden in your own stylesheet. See the special note below about the Archer font.

Method 2: Template functions

If you're building a WordPress theme or page template, you can access records via PHP using the \BHS\Client\Record class. These records contain collections of \BHS\Client\RecordField objects, which provide a few handy methods for retrieving and displaying content. Some examples:

Get record abc123 and show each of its fields

$record = new \BHS\Client\Record( 'abc123' );
foreach ( $record as $field ) {
    printf(
        'The name of the field is %s and the value is %s',
        $field->get_field_label(), // Escaping is handled for you.
        $field->get_field_value()  // By default, array values are collapsed using <br /> tags.
    );
}

Get record abc123 and display the values of one of its fields as a comma-separated array

$record = new \BHS\Client\Record( 'abc123' );
$subject_field = $record->get_field( 'subject' );

printf(
    'The subjects for record abc123 are %s',
    $subject_field->get_field_value( ', ' )
);

Get record abc123 and get some raw values for custom processing

$record = new \BHS\Client\Record( 'abc123' );
$subject = $record->get_field( 'subject' );

$subjects = $subject_field->value;
foreach ( $subjects as $subject ) {
    // etc.
}

Method 3: JavaScript and asynchronous processing

Storehouse data is accessible at API endpoints that can be accessed using any language that understands JSON. You don't need the BHS Client plugin to access data in this way. But the plugin provides a JavaScript variable containing the API Base from your Settings, as a convenience for developers. Example:

Fetch record abc123 using jQuery and put one of its fields into a DOM element.

$.ajax(
    url: window.BHS_Client_Settings.api_base + 'record/abc123',
    method: 'GET',
    success: function( r ) {
        var description = r.description;
        $( '#abc123-description' ).html( description );
    }
);

Shortcode styling

Shortcode output is styled using the Archer font, when available. To use Archer in your WordPress theme, define the font-face in your style.css as follows:

@font-face {
    font-family: Archer;
    src: url( 'fonts/ArcherPro-Book.otf' );
}

@font-face {
    font-family: Archer;
    font-weight: bold;
    src: url( 'fonts/ArcherPro-Bold.otf' );
}

@font-face {
    font-family: Archer;
    font-style: italic;
    src: url( 'fonts/ArcherPro-BookIta.otf' );
}

@font-face {
    font-family: Archer;
    font-weight: bold;
    font-style: italic;
    src: url( 'fonts/ArcherPro-BoldIta.otf' );
}

This CSS assumes that you'll be using all four listed variants of the font face, and that they'll be stored in a fonts directory alongside your stylesheet. Adjust as necessary.