First Step: Logging In

When you log in to Mercury for the first time, a Mercury user account will automatically be created for you.  The login link is on the upper left of the Mercury website [http://hg.gatech.edu/]

Please note: The Mercury system is only available on-campus or while connected to the Georgia Tech VPN.

A group administrator cannot give you access to a group in Mercury until you have logged in for the first time.  So, if you expect to use Mercury and haven't ever logged in with your Georgia Tech account (e.g. gburdell1), please do so now.

Your Default Groups

As soon as you log in, you will become a member of two groups: Georgia Tech Events Calendar, and Hg Training.

The Georgia Tech Events Calendar group is a group in which all Mercury users are a member with the basic role of Author. Currently the main calendar on the Georgia Tech Web site is populated with any event created in Mercury that is in a published state, and part of the Georgia Tech Events Calendar group. This allows users to keep internally focused events on their own sites and only promote events open to the campus on the main calendar. Therefore, when entering events get in the habit of selecting the Georgia Tech Events Calendar group with your group selections if you want your event to appear on the main calendar. Note that you're also required to select one of your "home" groups.

The Hg Training group was set up for temporary training purposes. This group serves as a testing ground for helping users become familiar with generating Mercury content. However, any images, videos, or published content you add to this group will be viewable by others in the Mercury system.

For most major campus units, there is already a group set up - consult the groups directory (login to Mercury required) to request membership from the group's manager. If none of the existing groups apply to your needs, you can use the Group Request form to submit a request for a new group.

Once you have been set up within a group, your first step to enter content into Mercury is to select the appropriate group on the right-hand side of the page. Once your group is selected, you will be given numerous options to create content on the left-hand sidebar.

About Mercury Groups

Groups serve as buckets for content, and are often associated with an academic unit or office. Separate groups for sub-units can be added as needed. For instance, a research center could have its own Mercury group separate from its parent school or interdisciplinary research institute.

However, the main purpose of groups is not to sort or categorize content, but to control who can edit (and delete) content.

Users are associated with groups and may have varying permissions within each group; it is possible to have different roles in different groups. All Mercury users are members of one or more groups (at a minimum, your major affiliation plus the Hg Training group).

Consult the groups directory (login to Mercury required) to request membership from a group's manager. If none of the existing groups apply to your needs, please use the Group Request form to submit a request for a new group, or the support form to request an ownership update for an existing group.

A tutorial is available for managing group memberships in Mercury.

About Mercury Roles

Each Mercury group has different sets of permissions for different users. Each permissions set is collected into a "Role", of which these are the main types:

1. Author
2. Manager
3. Administrator

A tutorial is available for changing a user's Mercury role.

Author

Almost everyone you add to your group will have this role. An author can create content, but cannot make that content live (i.e. Publish it) and often cannot edit other people's content or feeds. This role is mainly useful if your group wants to:

• have some users moderate content before it is made public,
• allow people from other units to create draft content for your group, or 
• allow people from other units to automatically add their events/news to your group/calendar.

Manager

There can be only one...manager of a group. Similar to being an "Owner" of a web hosting site, it allows Mercury support staff to know who is primarily responsible for a group. They have the same powers as an Administrator, but can also bulk remove or modify more than one user at a time using "Operations".

Administrator

This role can add new members to a group, and can allow people to become "Authors" or "Administrators" for a group.

Groups and Users Sub-Topics

The Interface

In the navigation bar of Mercury, Groups > My Groups will let you choose from a list of the Groups of which you are a member.

Don't Use Groups as Categories

One of the most basic ways you can sort your Mercury content is by using Groups. However, since the purpose of groups is to control who can edit (and delete) content, you will have more control over which items show on your website by using manual feeds and talking with your counterparts in other groups about news or events you would each like to share.

How to Safely Share Content with Other Mercury Groups

If you want to share content between groups, you need to contact the group manager and make sure you both have the same understanding of what kinds of news/events to share and when. This is especially important if:

• A group is using automatic feeds, as any content you share may automatically be added to their calendar or list of news items.
• One of you edits or deletes a piece of content that the other group needs.

Sharing Events with the Main Georgia Tech Calendar Site

To have your event show on the main Calendar site, check the box labeled Include this event on the Campus Calendar (within the Categories and Keywords section).

Canceled or Postponed Events

If an event is canceled or postponed, rather than deleting it from the system, add the word “CANCELED:” or “POSTPONED:” to the beginning of the event "Title". This will prevent broken links and confused users who may be looking for updated event information. Currently, events are never removed from the main Calendar site, so this also helps clarify their status on that website.

Sharing News with the Main Georgia Tech News or Research Horizons Sites

Institute Communications

First, contact an Institute Communications person from the Media Relations, Campus Communications, or the Research News teams. Tell them about story you have that you think would be great on one (or both) of these sites.

Categories

If research-related, check the box next to the most appropriate topic under "Core Research Areas".

If not research-related, let Institute Communications know which of these categories your story best matches: Business and Economic Development, Campus and Community, Earth and Environment, Health and Medicine, Science and Technology, or Society and Culture.

Create and Attach Media Files Correctly

In addition, it is especially important than any media on a news story for one of these sites be correct in its:

• Aspect ratio: a 16 by 9 ratio is needed
• Order of the first and second images: the first image listed is used as the Thumbnail or small image, while the second image chosen under "Media" is shown at the top of the full story page for this news item on those sites. The only exception to this is that any story with a video will automatically use the video instead at the top of the full story page.

What is a Feed?

A feed is a list of content items from Mercury. Feeds let you organize any content from Mercury — your own and others' — and then display it on other web sites. The two most common types of content you will find in feeds are events and news.

Manual versus Automated Feeds

Content can be organized into two types of feeds in Mercury:

• As an arbitrary Manual Feed, where you have complete control but must make every change yourself
• Via a selection of rules in an Automated Feed that you set up once and don't have to touch again (unless you want to adjust those rules)

Examples of Automated Feed Usage

Commonly, people use relative dates, limit them to just one type of content (such as events only), and then connect these to hg_reader blocks and pages on their web site.

However, you can also use these to find related content, without connecting the feed to a website (thanks to Kathleen Moore for this idea!). For example, you could make an automated feed that helps you curate content you might add to a manual feed. It could search by keywords, or show content from other people's groups.

Examples of Manual Feed Usage

Commonly, people use this to control which news stories or events show up on the homepage of their website.

The only drawback to a manual feed is that nothing is added or removed from them, without someone's intervention.

Feed Readers

Readers allow your web site to pull in the feeds you create and display them on your site. Georgia Tech's Institute Communications offers a Drupal module, HG Reader, for getting this set up.

Feed Item Limits

As of the September/October 2017 Mercury refresh, all feeds can now contain a maximum of 200 items.

• For an automated feed, any items beyond 200 items will not be displayed.  
• For a manual feed, any new items beyond 200 will not be added.

Mercury Feeds Sub-Topics

Mercury provides a variety of ways to categorize and tag your content, and understanding their meanings will help you to utilize them effectively.

Core Research Areas

Georgia Tech has organized its research into core areas of special interest, and encourages you to tag News items with these areas in Mercury.  These research area tags are used to help find stories:

• By those reading our news sites, such as the main Newsroom, Research Horizons, and Research (which pull almost all their news from Mercury)
• By Institute Communications staff, to filter stories from our many brilliant units to feature on these central news sites
• By individual units to highlight their news stories based on topic (using Feeds)

List of Research Areas

Georgia Tech has organized its research into the following core areas of special interest:

• Bioengineering and Bioscience
• Cybersecurity
• Data Engineering and Science
• Electronics and Nanotechnology
• Energy and Sustainable Infrastructure
• Manufacturing, Trade, and Logistics
• Materials
• National Security
• People and Technology
• Public Service, Leadership, and Policy
• Renewable Bioproducts
• Robotics
• Systems

Categories

Category tags allow for easier sorting of content items.  Event category tags will help visitors browsing events on the main Georgia Tech Events Calendar to narrow down the list to those types of events they are most interested in attending.

News, Image and Video Categories

• Institute and Campus
  • Alumni
  • Arts @ Tech
    • Community
    • Education
    • Exhibitions
    • Performances
    • Art Research
    • Student Art
  • Congressional Testimony
  • Economic Development and Policy
  • Institute Leadership
  • Special Events and Guest Speakers
  • Student and Faculty
  • Student Research
• Research
  • Aerospace
  • Architecture
  • Biotechnology, Health, Bioengineering, Genetics
  • Business
  • Cancer Research
  • Chemistry and Chemical Engineering
  • City Planning, Transportation, and Urban Growth
  • Computer Science/Information Technology and Security
  • Digital Media and Entertainment
  • Energy
  • Engineering
  • Environment
  • Life Sciences and Biology
  • Military Technology
  • Music and Music Technology
  • Nanotechnology and Nanoscience
  • Physics and Physical Sciences
  • Policy, Social Sciences, and Liberal Arts
  • Robotics 

Event Categories

• Arts and Performance
• Career/Professional development
• Conference/Symposium
• Other/Miscellaneous
• Seminar/Lecture/Colloquium
• Sports/Athletics
• Student sponsored
• Training/Workshop

Invited Audiences (for Events)

This option lets you indicate who your event is aimed at. You can choose more than one audience, if you'd like, by holding down Control/Command while clicking on each audience.  Setting the invited audiences allows people to narrow down which events they might be interested in when browsing events on the main Georgia Tech Events Calendar.

You can choose one or more of the following audiences:

• Undergraduate Students
• Graduate Students
• Faculty/Staff
• Public

Keywords

Keywords allow you to tag Mercury content for later sorting.  This can be helpful when you need additional categories that aren't included in the shared Categories already offered.  Keywords:

• Are not generally displayed on central news or events sites, and are more often used for your unit's web site.
• Must be spelled and capitalized identically in order to be used for sorting and filtering.
• Are entered as a comma-separated list of terms describing the item, e.g. "aircraft" or "5th street."
• Should be kept as short and as plentiful as possible
• Should not be a repeat of the item title.

Preparatory Steps

Log In and Choose Your Group

After logging in to Mercury, your first step to enter content is to select the appropriate group in Groups > My groups

Once your group is selected, you will be given numerous options to create content.

Beware of Copy and Paste!

Microsoft Word and some other applications use several characters that do not work well on the Web. Common examples are ampersands (&), angled quotes (single and double) and long dashes (en and em dashes).

For most long fields in Mercury, you can get around the vast majority of these issues by clicking on the paste from word button. However, this button is not available for short text fields without an Editor Toolbar (particularly of note: Title, subtitle, summary sentence and any field that might contain a name with apostrophes. If you cut and paste from Word into these fields, you may want to re-type any punctuation from the pasted text as a precaution. Another approach is to put your text into a plain text program first (Notepad for PC or Text Edit for Mac) and copy and paste into Mercury from there.

Sharing With Georgia Tech News and Research Publications

Please see the guidelines for sharing news with the main Georgia Tech News Site or the Research Horizons Site if you are preparing this news item to be shared with either group.

Create Your News Item

Select Create News or Create External News

Required Fields

Title

Your news item might be shown in places other than your website. So, choose a Title that:

• clearly explains what your news item is about to a general audience (try to highlight the most important thing about it).
• is self-explanatory even when not on YOUR website.
• is concise, around eight words, so it doesn’t run over when feeding into other places across various websites.
• has a catchy or informative headline that will inspire the reader to actually read your news story. 
• you will not need to change, as changing the title cause duplicates on the news site or break links to this story.

Summary Sentence

• Provide information that adds to the information already given in the Title, and use only 10 to 12 words at most.
• This will show up on gatech.edu's GT News feed (if you share with their group).
• This often displays below the headline, so don’t be repetitive.

Summary

This appears in the news feed the day your news item occurs. Your summary should be one to two sentences in length, and can expand a bit from the Summary Sentence.

You may also use the same copy from the Summary Sentence — these two never show up at the same time. Be aware that this does not fill the main body space on the news item listing itself; the Body field will do that.

Dateline

These fields auto-populate with today’s date; leave as is.

Contact

If someone has questions, who can answer them? Or, who’s the author? 

Include that person’s name, email address, and phone number.

Groups

If you want this article to show up in multiple places, select all the relevant groups.

The news sites where this item will show up. Your group (example: "Office of Awesome") will automatically be chosen. As appropriate, you might also get permissions to share your news item with other groups (perhaps an affiliated School or Department). This allows you to syndicate the content to other sites.

Save as...

Change the workflow from “Draft” to “Published” so that your item shows up in news feeds.

Unless you’re not finished, in which case, save as a Draft to come back to publish it later.

Recommended Fields

Body

You can give a fuller description of the news item here. It can have lots of details, and multiple paragraphs are allowed. Avoid leaving the Body section blank. 

This section should provide information about the news item itself, such as whether it’s part of a series, activities that will take place at the news item, or context of why a speaker is relevant to campus. If you are copying and pasting text, refer to the “Beware copy and paste” note above. Hyperlink websites in your text (e.g., if your text reads “clough.gatech.edu,” make sure that text is clickable). For longer URLs, hyperlink words to the website so the URL is not messy within the news item link (e.g., for a long application link, use the words “Apply online,” and hyperlink those words to the application URL). Be as specific as possible, but know that you can link to other pages for more information (such as agendas, directions, or speaker bios).

Related Links

Drop this area down and include any relevant websites — perhaps any organizations/Schools/Units associated with the story. 

Repeat important links from the Body section here to make sure readers can find the information.

Category

The goal of these tags is to make your news item easier to find on OTHER news sites (especially the very large Newsroom site). Choose the category that best fits your news item. To select multiple categories, hold down the “Control” (ctrl) key while clicking each applicable category.

Keywords

These help your news item be associated with others that are about the same thing, and it also can be used to feed websites. Make sure you spell words correctly, place commas correctly, and try to use keywords that auto-populate as you type so you’re not creating too many new ones.

Commas will separate each keyword, so some things may need to be altered to work as keywords (e.g., “School of Literature, Media and Culture” should be entered without commas, or else it will be processed as “School of Literature” and “Media and Culture.”)

Core Research Areas

If your news applies to one of the Core Research Areas, check the corresponding boxes accordingly. Your selections here should match those in the “Category" and "Keywords” sections. 

Optional Fields

Subtitle

Give a little more detail than what's in the Title, and do not repeat the Title.

Media

Either upload an image here, or else scroll down in the pop-up window and type in the title of any image or video you have previously uploaded. Results will populate as you begin to type.

File attachments

This is an opportunity to attach files that do not fit into the image or video category, such as a PDF application, guidelines, or reports. However, this requires the user to download a file to be able to view it (unlike photos or videos items), so make sure anything you’re attaching here is worth the user’s time to download. News item flyers are generally better included as images rather than attachments.

Preparatory Steps

Log In and Choose Your Group

After logging in to Mercury, your first step to enter content is to select the appropriate group in Groups > My Groups

Select the main group to which this content is relevant.

Once your group is selected, you will be given numerous options to create content

Beware of Copy and Paste!

Microsoft Word and some other applications use several characters that do not work well on the Web. Common examples are ampersands (&), angled quotes (single and double) and long dashes (en and em dashes).

For most long fields in Mercury, you can get around the vast majority of these issues by selecting the paste from word button. However, this button is not available for short text fields without an Editor Toolbar (particularly of note: Title, subtitle, summary sentence and any field that might contain a name with apostrophes. If you cut and paste from Word into these fields, you may want to re-type any punctuation from the pasted text as a precaution. Another approach is to put your text into a plain text program first (Notepad for PC or Text Edit for Mac) and copy and paste into Mercury from there.

Create Your Event

Required Fields

Title

• clearly explains what your event or news item is about to a general audience (try to highlight the most important thing about the event).
• is self-explanatory even when not on YOUR website.
• is concise, around eight words, so it doesn’t run over when feeding into other places across various websites.

Canceled or Postponed Event Titles

If an event is canceled or postponed, rather than deleting it from the system, add the word “CANCELED:” or “POSTPONED:” to the beginning of the event "Title". This will prevent broken links and confused users who may be looking for updated event information. Currently, events are never removed from the main Calendar site, so this also helps clarify their status on that website.

Summary Sentence

• Give information that adds to the information already given in the Title, and use only 10 to 12 words at most.
• This will show up on gatech.edu's GT Events Calendar or News feed (if you share with their group).

Summary

This appears in the calendar feed the day your event occurs. Your summary should be one to two sentences in length, and can offer details not found in the Title or Summary Sentence.

You may also use the same copy from the Summary Sentence — these two never show up at the same time. No need to include the date, time, or location here, as they have their own places. Be aware that this does not fill the main body space on the event listing itself; the Body field will do that.

Contact

This is very helpful for your audience if they have questions, especially when your event is shown on OTHER CALENDARS (i.e. not yours). Include a specific name, department, email, and phone number.

Invited Audience

Choose the audience for which this event is intended

Event Category

The goal of these tags is to make your event easier to find on OTHER calendars (especially the very large GT Events Calendar).

There’s a checkbox labeled "Include this event on the Campus Calendar” (within the Categories and Keywords section). Including events on the campus calendar is as simple as checking this box. To exclude them from the campus calendar, leave the box unchecked.

Groups

The calendars where this event will show up. Your group (example: "Office of Awesome") will automatically be chosen. As appropriate, you might also get permissions to share your event or news item with other groups you belong to. This allows you to syndicate the content to other sites. Be sure to check with the managers in that group to clarify whether they want you to do this for their group, as their may be an approval process they would prefer.

Save as...

Choose "Published" or your item stays hidden and will not show up on any calendars or news feeds. Once published, anyone in the Mercury system can find your event and add it to their manual feeds.

The Draft option is there for times when you need to save incomplete work and come back to it later, or to show to others before making it live.

Date/Time

Specify a date/time for your event. Be sure to indicate AM/PM.

MULTI-DAY or REPEATING EVENTS

If your event takes place over more than one day, use the FIRST day as both the From and the To date. Then, use the Repeat options for including the additional days.

Optional Fields

Body

You can give a fuller description of the event here. It can have lots of details, such as times, agendas, etc. Multiple paragraphs are allowed.

This section should provide information about the event itself, such as whether it’s part of a series, activities that will take place at the event, or context of why a speaker is relevant to campus. Avoid leaving the Body section blank. If you are copying and pasting text, refer to the “Text” note about using the "Paste from Word" button. Read through your text for duplicate information you’ve already specified, such as the date, time, and location, and delete those pieces. Hyperlink websites in your text (e.g., if your text reads “clough.gatech.edu,” make sure that text is selectable). For longer URLs, hyperlink words to the website so the URL is not messy within the event link (e.g., for a long application link, use the words “Apply online,” and hyperlink those words to the application URL). Be as specific as possible, but know that you can link to other pages for more information (such as agendas, directions, or speaker bios).

Location

This is for physical locations for in-person events. Add the building name on campus in Location and also any link to the building you may have (if the building has a URL with directions, for instance). For online events, use the Related Links field.

Related Links

Use this to link to an online event. This is where you might enter a Zoom meeting link.

Keywords

Begin typing relevant keywords here to see what has already been used. When possible, use the same phrasing, wording, capitalization and spacing as keywords that appear while typing, so that related events can be grouped together. Commas will separate each keyword, so some things may need to be altered to work as keywords (e.g., “School of Literature, Media and Culture” should be entered without commas, or else it will be processed as “School of Literature” and “Media and Culture.”)

Media

Upload an image here, or scroll down in the pop-up window and type in the title of any image or video you have previously uploaded associated with this listing. Results will populate as you begin to type, with media from your group showing towards the top of this list.

File attachments

This is an opportunity to attach files that do not fit into the image or video category, such as a PDF application, guidelines, or reports. However, this requires the user to download a file to be able to view it (unlike photos or videos items), so make sure anything you’re attaching here is worth the user’s time to download. Event flyers are generally better included as images rather than attachments.

Step by Step Instructions

1. First, edit the image, if needed, on your computer. Best practices for images are:
   • If large, consider re-sizing your image to exactly the size that will look good on the desktop version of your site.
   • Use a consistent aspect ratio for your images: we recommend a ratio of 16 by 9, unless your image will only be for headshots or for Hg Reader thumbnails, which use a square 1:1 ratio.
   • Choose a good name for your image (all lower case, use hyphens instead of spaces, avoid punctuation, short but descriptive).
   • Make sure your filename ends in either .jpg, .jpeg, .png, or .gif (all lower case).
2. Select Create Image on the right side, and follow these instructions:
3. Provide a basic title for the image, which will appear next to the photo once the event is posted.
4. Select Browse and find the image that you would like to include, then select Upload
5. Select any appropriate categories from the list and enter any keywords for the image.
6. Choose the appropriate group(s) in the Groups audience field.
7. Select Save

Image Naming for Ease of Access

You can make it easier to find images in Mercury by using a simple pattern for the Title field, such as:

• Organization name or abbreviation: Clough
• Significant subprogram or subcategory for your organization: Art Crawl, or Students
• Date image was created or uploaded: 2013
• Short phrase describing image (1-4 words): Winners in photography

In this example, your title for this image would be: "Clough Art Crawl 2013 - Winners in photography"

Remember that this title field will be visible to the public, either as an image caption on some News sites or as alternative text for screen readers.

Where to Add Images for News/Events

On both the Create Event and Create News pages, you can add Images under the section called Media.

To attach individual images, start typing the title of an image you've created into one of these Media fields.

Overview of Steps

1. Upload your video to YouTube and add accessible captions.
2. Choose a name for your video.
3. Select Create Video on the left side and follow these instructions:
4. Enter a title for the video, which will appear next to the video within a news or event item.
5. Enter the You Tube URL for the video
6. Select any appropriate categories from the list and enter any keywords for the video.
7. Choose the appropriate group(s) in the Groups audience field.
8. Select Save.

Video Naming for Ease of Access

Make it easier to find videos when trying to add them to news items. Use a simple pattern for the Title field, such as:

• Organization name or abbreviation: Clough
• Significant subprogram or subcategory for your organization: Art Crawl or Students
• Date image was created or uploaded: 2013
• Short phrase describing image (1-4 words): Winners in photography

In this example, your title for this video would be: "Clough Art Crawl 2013 - Winners in photography."

Where to Add Videos for News/Events

On both the Create Event and Create News pages, you can add videos under the section called Media.

To attach individual videos, start typing the title of a video you've created into one of these Media fields.

This section is for tips and tricks to making Mercury easier to use.  Feel free to add to this section any tips or tricks you've discovered.

Tips and Tricks Sub-Topics

Occasionally, you may discover that an article that you or a colleague posted to your Mercury group needs to come down for some reason.  Your first instinct might be to just delete that article, but deletion may not be the best option in many cases.

While some websites that connect with Mercury may do a full synchronization with Mercury on a periodic basis, some websites may only do a one-way synchronization.  One-way basically means that the website grabs any new and updated articles, but pays no attention to articles that no longer exist.  Usually, such sites will stop mentioning deleted articles in any listings of news or events, but the article's full page may remain, meaning that anyone who has saved a link to that page could still access the article.  Worse, search engines might retain that link and continue to direct people to that page.

The better way to handle removing article content that needs to come down quickly is to simply edit the article and delete only the content.  Anything in the Summary and Body fields can be deleted, and any attached media can be unattached from the article.  Finally, the title could be changed to something like "Retracted Article" and an apology message added to the Body field.  Save your changes and they will overwrite any website copies of the original article the next time that any connected website synchronizes with Mercury.  After you are sure all connected websites have updated with your "Retracted Article", you could then delete the article completely from Mercury.

Bear in mind, that most sites only synchronize once every two hours, give or take, so your changes will not appear on your website immediately.  If you have admin rights on your unit's website and it is running the standard Mercury Reader, you can try to force updates immediately.  Otherwise, you'll just have to wait until the next scheduled synchronization.

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.

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).

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

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

• A great tutorial on XPath & XSLT from ZVON
• Mozilla Developer docs on XPATH & XSLT

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.

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.