Mercury Developers Guide

Mercury Developers Guide afrank30
Drupal Version
Tags

This section provides help, tips and tricks for using the Mercury Reader (hg_reader) module for Drupal 7, or other techniques, for bringing Mercury news and events into your Drupal website.

If you are looking for assistance with posting news and events to the Mercury server, we have several Mercury Users Guide.

Methods for Bringing Mercury into Drupal

Drupal sites on campus have three options for getting news and events from this campus repository:

  1. Using the Mercury (Hg) Reader module provided by Institute Communications (only available for Drupal 7 at this time)
  2. Using a custom module to grab XML Feeds of content, which can then be parsed and stored locally on your Drupal site.
  3. Using Feeds Extensible Parsers to bridge between a Mercury XML feed and Drupal's Feeds Importer.

By far, the first option is the easiest one to implement, and is thus the recommended option as well.


Mercury Developers Topics

Mercury Reader Installation

Mercury Reader Installation esembrat3
Drupal Version
Tags

The Communications Team at Georgia Tech developed a module, Mercury Reader (hg_reader), to provide turnkey access to importing news and events from Mercury into your Drupal site. If you just want a simple news or events page or pages, and you don't need to amend the data once it comes out of Mercury, Mercury Reader is a powerful ally.

Installation Instructions

Install the module as you typically install modules (upload to /sites/all/modules, enable on the module configuration page.)

Check module permissions to make sure the proper roles have access. The permission options include:

  • Administer Mercury Reader — A permission for users with a "Super Administrator" role (i.e., a role with access to advanced site configurations)
  • Manage Mercury Nodes — A permission for users with an "Editor" role (i.e., a user who does typical content management tasks)

Next, either select an existing content type to serve as your "Mercury" content type, or create a new content type, and select the checkbox under Mercury settings of the content type's configuration settings.

Create a new node of your Mercury content type, and provide the Feed ID number for your Mercury feed in the Mercury settings field set. You can also specify how many items to display from your feed. The Feed ID number for your feed is part of the URL for your feed in Mercury (i.e., for the URL http://hg.gatech.edu/node/1234 the feed ID would be "1234.") Save the node and you should now see Mercury items from your feed appear the body of the node.

Mercury Reader Common Issues

Mercury Reader Common Issues esembrat3
Drupal Version
Tags

This page details common issues that are encountered with the Mercury (Hg Reader) module.

Images Not Showing for Events on my Site

If you are using the Mercury Reader (hg_reader) module on your site, then it is currently designed to display images for news items, but not for events. To change this, you'll need to edit the feed template (hg_feed.tpl.php).

Theming Mercury

Theming Mercury
Category
afrank30
Drupal Version
Tags

Mercury Reader's out-of-the-box appearance can be customized to meet your unit's needs.  The sub-sections below describe different ways of custom theming Mercury blocks and pages on your Drupal 7 site.


Mercury Theming Sub-Topics

Editing Existing Mercury Reader Theme Files

Editing Existing Mercury Reader Theme Files
Category
esembrat3
Drupal Version
Tags

This page documents how to customize your Mercury feeds using changes to your local theming files, which are identified by the file-type ".tpl.php".  Both full item pages (/hg/item/item-ID) and feed lists in blocks and pages can be custom themed.

To override the templates listed below, make a duplicate of the desired template in your local theme directory (usually located at sites/all/themes/YOURTHEME/templates), and modify as you see fit. Template-specific documentation is included in the templates themselves. Be sure to convert underscores to hyphens in your templates (use hg-feed.tpl.php instead of hg_feed.tpl.php.)

There are three templates included in Mercury Reader:

  1. hg_feed.tpl.php - Controls the appearance of a feed
  2. hg_item.tpl.php - Controls the appearance of full item displays
  3. hg_media.tpl.php - Controls the appearance of the related media box shown on item pages.

Custom Theming Examples

Removing Images From All News Lists

You could copy the hg_feed.tpl.php file to your theme's templates directory, and then alter the markup so that no thumbnail images are included in a list of news. This would change all lists of news in every Mercury block, or Mercury node on your site.

Removing Images From a Specific List of News

To do this, you'll need to first create a template file that corresponds to a class provided in the "Feed Classes" field that you added to your Mercury block, or Mercury node. For example, if you added the class "newslist," you'd need to copy the hg_feed.tpl.php file to your theme's templates folder, and then rename it hg-feed--newslist.tpl.php (note the use of hyphens instead of underscores in the template file.) You could then alter the hg-feed--newslist.tpl.php file to suit your needs, and any Mercury block or Mercury node that has the "newslist" class listed in its Feed Classes field will display its content based on the markup of the hg-feed--newslist.tpl.php file.

Note: currently if you want to have a multi-word class in your Feed Classes list you'll need to use underscores instead of hyphens for the class, but be sure to stick with hyphens for the template file. This will be fixed in a future update to the Mercury Reader module.

Restyling Mercury Feeds and Content With Only CSS

If you don't want to mess with template files you can also just make use of the "Feed Classes" field to add CSS classes that will apply to a particular Mercury block or node, and then add your desired styling based on those classes to your subtheme's style sheets. All of the classes you add via the Feed Classes field will be output in the outer wrapper <div> of a Mercury feed, or item. For example, if you added "newslist" to the Feed Classes for a Mercury block, the outer <div> of that block would look like:

<div class="hg-feed-wrapper newslist">

Theming a Mercury Image

Theming a Mercury Image
Category
afrank30
Drupal Version
Tags

When using the Mercury Reader, you can reference an image attached to a news story or event and display it elsewhere in different sizes.  Please note, however, that the range of sizes available depends on the size of the image the story creator uploaded - if that person uploaded only a small image, you won't be able to get a larger version out of Mercury.

You will first need to get the image node ID.  One way to do this is to right-click on the image on the story or event page, and open it in a separate tab or window.  Look at the URL of the resulting page - the long integer near the end of the URL is the ID number.  In the URL "/hg/file/41282/200xX_scale", the image node ID would be "41282".  The code after the integer (in this case, "200xX_scale") is the format of the image.  If you want to display this image somewhere else, but in a different size, just change that code to one of the other image style presets in Mercury

Of course, this doesn't help if you wanted to change the display of the image when it is displayed in a node dynamically generated by Mercury Reader (when you are using just the reader, without making local copies of your news stories and/or events.)  If you want to change the default display of images in Mercury Reader's dynamically generated nodes, you'll have to create a custom template.  Here is an example of code you could use to make all images appear in the "200xX_scale" format:

<img src="/hg/file/<?php print render($items[0]); ?>/200xX_scale" alt="<?php print($element['#object']->title); ?>" class="<?php print render($classes); ?> field-name-myfield-image-file" />

Image Style Options in Mercury

Image Style Options in Mercury
Category
esembrat3
Drupal Version
Tags

Below is a list of preset image styles (mainly based on size) that you can use when theming Mercury items.

  • 100x133_scale_crop
  • 100x75_scale_crop
  • 100xX_scale​
  • 150x112_scale_crop​
  • 150x150_scale_crop​
  • 150x200_scale_crop​
  • 150x84_scale_crop​
  • 150xX_scale​
  • 1920x700_scale_crop​
  • 200x150_scale_crop​
  • 200xX_scale
  • 250xX_scale​
  • 300x400_scale_crop​
  • 400x225_scale_crop​
  • 400x300_scale_crop​
  • 400xX_scale​
  • 40x40_scale_crop​
  • 40xX_scale
  • 600xX_scale​
  • 80x80_scale_crop​
  • 80xX_scale
  • 860xX_scale

Using the Mercury Reader API Functions

Using the Mercury Reader API Functions
Category
afrank30
Drupal Version
Tags

Module developers can utilize API functions within the Mercury Reader module to fetch data and files (including images) from the Mercury server.  This would allow you to write a custom module to format that data for your users without having to recreate all of the code needed to interface with the Mercury server.  All of the hg_reader API functions can be found in the hg_reader.api.php file, and some of the more useful ones are documented below:

The "hg_reader_get_file" Function

To fetch files (including images) from Mercury, we'll be using the hg_reader_get_file function (found in the hg_reader.api.php file). You must pass it three parameters:

  1. type: is this an 'image' or a 'file'?
  2. int: the unique Mercury ID number for the image/file that you are displaying (sometimes called the node ID)
  3. option: only required for images, where you can enter one of the preset image style options.

Why Use hg_reader_get_file?

Because hg_reader will cache the image as befits the friendly, fluffy little creature it is.

What if I'm Not Using hg_reader to Retreive my Mercury News and Events?

If you are pulling in Mercury content via Feeds and making local copies on your website, you can STILL use this function. All you need is to:

  • enable (turn on) the hg_reader module
  • create a Mercury block for each feed you are importing (you don't have to show these blocks on any pages: they are how you create a local hg cache that lets you leverage hg_reader's API)
  • make sure your import is capturing the node id number of those images (because you need an image's Mercury nid to use the above function)

Example Code for Images

In your template file for a field or content type, you can call an image in Mercury using this code like this:

print hg_reader_get_file($type, $id, $option = 'original');

Alternatively, to display a 200-pixel wide version of the image that accompanies your news item, you might use this code:

print hg_reader_get_file('image', 232661, '200xX_scale'); 

Function Code From API

Below is the full code of the hg_reader_get_file function.

function hg_reader_get_file($type, $id, $option = 'original') {
  switch ($type) {
    case 'image':
      // We still want to support the deprecated function signature.
      $format = (isset($_GET['f']) && $_GET['f']) ? check_plain($_GET['f']) : check_plain($option);
      echo hg_reader_file_helper($type, $id, $format);
      break;
    case 'file':
      $option = 'other';
      echo hg_reader_file_helper($type, $id, $option);
      break;
  }
}

Importing News and Events via Feeds Extensible Parsers

Importing News and Events via Feeds Extensible Parsers
Category
esembrat3
Drupal Version
Tags

Feeds Extensible Parsers is the module normally used to do XML and JSON imports of news and event data from the Mercury server.  (This module supersedes an older module called "Feed XPath Parser", which is no longer supported and should not be used.)

Editor's Note:  While this method is being utilized by some units on campus, it can not be recommended due to the Feeds Extensible Parsers module still being in a beta release since April 2015, and not being covered by the Drupal organization's security advisory policy.  We strongly recommend that you try to utilize the built-in functionality of the Mercury Reader Module whenever possible, and only use Feeds Extensible Parsers as a last resort.

Setting Up Feeds Extensible Parsers

  1. Install CTools and Job Scheduler (dependencies of "Feeds")
  2. Install the Feeds module
  3. Install the Feeds Extensible Parsers module.
  4. Go to the Feed importers on the Structure administrative menu to create a new importer that you will use to map Mercury content to your local news/event content types.

But, before you get started with building importers you’ll want to first set up your content types with fields that match the basic structure of Mercury news/events, such as adding fields for a summary, summary sentence, related links, boilerplate, etc. For fields that can have multiple values be sure to also configure your local node’s field to do the same (such as with related links, or keywords.)

For images associated with a Mercury item you can either map/store the node ID of the image (which would then require using hg_reader functions for building the display of the images,) or download the image directly to your site 

Feeds Settings

Basic Settings

If you prefer to create a content type to use as an importer, you can assign one under “Attach to content type,” or you can choose to “Use standalone form.” The standalone form usually works for most purposes. All standalone importers can be found at yoursite.com/import

Periodic import - If you want imports to run automatically then choose an interval. For most cases it’s best to have it automatically import only twice a day, and then manually override it if you want something to show up sooner.

All other setting can be left as is.

Fetcher

  • Fetcher - Select HTTP Fetcher.
  • HTTP Fetcher Settings - Leave as is (don’t check either option)
  • Parser - Select XML XPath parser

Processor

  • Processor - Skip down to Processor (we’ll return to XPath XML processor settings after mapping) and select the Node processor option.
  • Node Processor Settings - If you plan to add additional fields to your news/event nodes that are not populated from Mercury you’ll want to set it to update existing nodes. If you plan to only include Mercury content in your local nodes you can opt for Replace existing nodes, but most users stick with the Update existing option.

    For Text format it’s best to select an input format that allows most block-level HTML tags, or at least the same options that you see in the body field of Mercury items. Select your content type that you want to map Mercury content to, the default author of your local nodes (typically a site administrator), and an Expire setting if desired (usually this is left at Never).

Mapping

  • Node Processor Mapping - Now you’ll want to add the mapping for the fields of your local news/event content type that you plan to populate with Mercury content. For each field select the “xpathparser” option, then a field from the target drop-down, and select the Add button. Note that you’ll need to select a field to serve as a unique target. For this choose the “GUID” option for the target, and you’ll later map this to the item’s Node ID in Mercury.

XML Parser Settings

Now that you’ve identified the fields to be mapped you need to provide an XPath value for each field.

Enter “node” for the Context field.

For each field that you’ve added you’ll want to provide the appropriate value based on the XML tags in Mercury’s feeds. So for instance with your title field you’d enter “title”, for the body field “body,” etc.

For the “field_image” above note that it’s set to use the “image_full_path” value. This will return the full path to the image file on Mercury, and since it’s mapping to an image field in the local content type it will pull a copy of the image down to your server and store it with your local node. However, you can not map image titles or descriptions from the Mercury version to the additional fields available with an image field type (such as the alt text, description, etc.) So to display the full details of a related image it would be best to instead map the image’s “nid” value in Mercury and use hg_reader functions to build the display of the image in your local content type where you could add a title and description as intended by the original contributor. If you went this route you would need to provide the XPath value as: hg_media/item/nid

The same could be done if you were to set up a field in your local node to store video files uploaded to Mercury. Note that these days most users are uploading YouTube IDs instead of the actual video file, but you would still want to build the display of the YouTube video via its Mercury “nid” value so that you could display the title and description as intended by the original contributor.

For related files that are uploaded with a Mercury item you can map them as actual files and download them to your server (use the “full_path” value), but you will lose the option of including the title provided for the file.

You may instead choose to set up related files as a “link” field type in your local node so that you can include the provided title of the file. The Feeds module will allow mapping for both the title and link values of link fields (link fields are provided by the link module: drupal.org/project/link)

Alternatively, you could set up separate media content types in your local site and map all media from your news and event feeds, but it’s preferred that you leverage the hg_reader functions as much as possible to display Mercury content.

Note the “@id” entered for the “guid” field above. This is referring to the node ID that’s published in the XML feed as an attribute of the node element in the XML tree (i.e., ). This is stored as a unique value for your local news/event node and will help prevent duplicates being imported to your site (check out W3schools.com for more on the Xpath syntax: http://www.w3schools.com/xpath/)

However, note that it’s only unique to the importer, so if you have two importers set up for two different Mercury feeds and an item is added to both of those feeds it will still be duplicated on your site.

You may want to also map the “changed date” (Xpath value = changed) to your local nodes to help Feeds identify when an item has been updated in Mercury.

Once you’ve got your importer set up you can go to /import on your site to view all importers created, and initiate a pull from Mercury (as well as delete items pulled in from Mercury.)

Fields

Each one-to-one mapping within XPath is composed of a few common types:

  • String literals are marked by "Text". Best used for static values for a field.
  • @attribute selects attributes on a tag (such as href, class, id).
  • value/ selects a tag.

Pictures / Images

Full Import

Note: If the website in question is using OIT Web Hosting, you may have to contact OIT Web Hosting support to enable curl_init()

To retrieve photos (with metadata) imported, follow the directions below:

  1. Install the Mercury Reader (hg_reader) module.
  2. If you open up hg_reader.api.php, you can read all about the Mercury API. The function in question is this:
function hg_reader_get_file($type, $id, $option = 'original')
/**
 * This function fetches files (including images) from Mercury.
 *
 * @param string $type
 *   Either "image" or "file"
 * @param int $id
 *   Either a Mercury image node ID or a Mercury file ID (note that this corresponds to node/files/
 *   item/fid within a node's XML.
 * @param string $option
 *   For images, the name of the Mercury ImageCache preset desired.  For files, this option will be automatically set to "other."
 */

So in your own theme template file, if you insert:

print hg_reader_get_file('image', 232661, '200xX_scale');

You'll get a 200-pixel wide image of the chair of the physics department. Furthermore, hg_reader will cache the image as befits the friendly, fluffy little creature it is.

XPath Import

Another option is to simply import the image path URL using XPATH and the XML.

  • concat("http://hg.gatech.edu/",hg_media/item/image_path)

Please note that this implementation may have firewall issues when viewing images from off-campus.

For more information

Forcing Updates in Mercury Reader

Forcing Updates in Mercury Reader afrank30
Drupal Version
Tags

Have you made a new event or updated one of your news items in Mercury, but those changes are not showing up on your website?

This usually means you need to flush caches for Mercury on your site, forcing it to go check for the latest items and updated information.  Flushing caches just means wiping clean the temporary files Drupal produces to help speed up your website and rebuilding them with the latest settings, content, and configurations. You can learn more on drupal.org's article on clearing caches.

You can flush caches two different ways:

  • Log into your site (NOTE: you may need Administrator privileges to complete the following steps)
  • Navigate to the Mercury block that is out of date, or to a news or event item's individual page
  • Select the grey button that says "Flush this item from the cache". You will find this link directly underneath the page title and above the body text on the page, as shown below.

Configuring Mercury Reader Blocks

Configuring Mercury Reader Blocks esembrat3
Tags

This page details the common ways that blocks are configured to take full advantage of Mercury's rich feature-set.

Show only Current Events in a Block

  • When you create a feed in http://hg.gatech.edu/, be sure to set Event Start Date to the following:
    • "Is greater than or equal to"
    • "now"

New events not showing?

If you notice your front page's events are out of date, add “?clearcache=1” to the end of the URL in the address box of your browser, so you have http://MYSITE.gatech.edu/?clearcache=1.

Selecting Specific Mercury Items in a Block

Create a page or add a block, You will see a pair of boxes on the page edit form: "Feed ID," and "Maximum items." 

  • Feed ID: The feed ID is the five- or six-digit number shown in the URL when viewing a feed. You can find this within Mercury at http://hg.gatech.edu, for a feed that you or someone else has created. For example, the Georgia Tech homepage feed is available at http://hg.gatech.edu/node/42142, and the feed ID is 42142. You are not required to have a Mercury account to include feeds on your site. If you do not have an account and wish to display an existing feed, contact the administrator of that feed to get the ID number.
  • Maximum items: The maximum number of items you wish to display, or 0 for unlimited.

When you save the page, you should see the feed items listed below the body copy, if there is any. Each title will link to the full item at /hg/item/item-ID.

Re-order or Reverse events

If you notice your block or page is showing events backwards, check the "Reverse sort" checkbox on the Mercury configuration form.

Experimental and Deprecated Mercury Projects

Experimental and Deprecated Mercury Projects klp

GT Calendar

GT Calendar afrank30

GT Calendar Configuration/Usage

GT Calendar Configuration/Usage afrank30

GT Calendar Installation

GT Calendar Installation afrank30