CollectionSpace

CultureObject now has a provider for the open source CollectionSpace collections management system. Follow the instructions below to install and run an import from your CollectionSpace system.

1. Check requirements

The CultureObject plugin requires that you are running at least PHP 5.6. Some hosts will let you change the version of PHP you’re running – but make sure you don’t have any dependencies elsewhere that might break if you do this!

If your host doesn’t support later versions of PHP you should really consider changing host – many earlier versions of PHP are no longer supported and inherently insecure..!

Note also that CultureObject uses the Custom Post Type named “Object”, so will not work if you already have an existing declaration of this post type on your site. 

2. Update WordPress and any plugins

Run a plugin update, and if you need to update WordPress core then do that too. You’ll find notifications for both of these within the Updates section of your Dashboard (Dashboard > Updates).

3. Install CultureObject

CultureObject is available via the official WordPress plugin repository. In your Dashboard, navigate to Plugins > Add New, then search for CultureObject:

Click the Install Now button and wait for the plugin to download and install.

Once it has, you’ll notice two new menu items in the left hand Dashboard navigation: Objects and Culture Object.

4. Install the CollectionSpace boilerplate theme (optional)

We have provided a simple boilerplate theme based on the Bootstrap web framework which you can install if you wish. This will allow you to rapidly test Culture Object with your own collections data. To use this theme, download it from this page, then install it via Appearance > Themes > Add New > Upload Theme before activating it.

If you have an existing theme that you want to use with CultureObject, you can skip this step – details about the pages and code you need to add within your theme are outlined below.

5. Add your CollectionSpace details

Navigate to Culture Object in the left hand bar, then change the dropdown next to Sync Provider to “CollectionSpace”:

Leave the Sync Key box as-is.

If you check Import Images the plugin will import any images it finds to the WordPress Media Library and attach them to the corresponding record. We recommend that you don’t do this on first run – test the import without and then re-sync if you need later. We recommend that you don’t use the image import on large datasets – in this instance it makes better sense to serve the image from a 3rd party location such as a CDN, Cloudinary or a web file system with the means to re-size on the fly (we like cimage for the latter, which provides a powerful way of cropping, sizing and processing image on self-hosted instances).

Once you have done this, Save Changes and then click on the Provider Settings sub menu. On this page, input your CollectionSpace details:

..then click Save Changes. Once you do this (and provided the plugin can negotiate successfully with the CultureSpace API), you should see a message telling you how many objects are available to sync, and the estimated length of time this sync will take:

6. Perform a sync

To perform a sync, return to the main Culture Object page and then click the sync URL near the top of the page. This may take a while depending on your hosting and the number of objects available to sync. During this process you should see a page showing the status of the sync:

Note that you can copy the sync URL into a CRON job if you want your data to sync on a regular basis.

Once you have run a sync, you can click into the Objects menu and see the object metadata in a list:

Clicking on an individual record will then show you the details for that object. If you don’t see any fields, make sure that Custom Fields is checked in the fold-down for Screen Options at the top right of the individual object page.

7. Displaying your objects on the front end of your site

You’ll need to know a bit about WordPress theming in order to display your object records on your site. The information you need will be found on pages which talk about Custom Post Types and Custom Fields. In our instance, the Custom Post Type is “object” – and the Custom Fields are the ones displayed in step 6.

If you’ve installed the boilerplate theme then you should be able to click on View Object from the single record view and then see a simple, non-complete record with just a few fields displaying.

Note that if you get a “Page Not Found” error, then you’ll probably need to go to Settings > Permalinks and Save before checking the single object view again.

 

The template that is used by WordPress to display a single object is determined by the WordPress Template Hierarchy, so in our instance because the Custom Post Type is called “object”, we use a file called single-object.php within our theme folder to display the page above.

The paginated listing of all the objects can be seen at http://[yoursiteurl]/object. The template that determines this view is called archive-object.php.

8. Displaying individual fields

If you open up the single-object.php file in an editor such as Notepad, you will see some syntax that looks like this, within the WordPress loop:

 <?php if(cos_get_field("objectNumber")){ ?>
 
 <dt><?php echo cos_get_remapped_field_name("objectNumber"); ?></dt>
 
 <dd><?php cos_the_field("objectNumber");?></dd>
 
 <?php } ?>

We use three custom functions for displaying object content:

cos_get_field(“[FIELDNAME]”) fetches the data so you can check it exists (as in above snippet) or assign it to a variable.

cos_the_field(“[FIELDNAME]”) displays the data

cos_get_remapped_field_name(“[FIELDNAME]”) fetches the name of the field as defined in the Field Mappings section of the CultureObject Provider Settings page. This allows you to easily define the display names for each field so they are more user friendly than the original field names:

Note that in order to use this function, you must declare support for it within your theme functions.php file:

// Add theme support for COS remappings

function custom_theme_setup() 
{
 add_theme_support( 'cos-remaps' );
}
add_action( 'after_setup_theme', 'custom_theme_setup' );

Because we use standard WordPress custom fields, you can of course the normal routes into these fields – so for instance to display all the metadata on a record you could use something like this:

<?php
$custom_fields = get_post_custom();

foreach ( $custom_fields as $field_key => $field_values ) 
{
 foreach ( $field_values as $key => $value )
 {
 echo "<li>";
 echo $field_key;
 echo " = ";
 echo $value;
 echo "</li>";
 }
}
?>

Or, the equivalent using COS functions:

<?php
$custom_fields = get_post_custom();
foreach ( $custom_fields as $field_key => $field_values ) 
{
 foreach ( $field_values as $key => $value )
 {
 echo cos_get_remapped_field_name($field_key);
 echo " = ";
 cos_the_field($field_key);
 echo "<br />";
}
}
?>

Either will list all custom fields and their values. You can then use this to populate and design your template by calling the relevant COS fields.

9. Other bits and pieces

We tend to use a couple of extra plugins when installing CultureObject – they make searching and display a bit easier..