Handling Microdata in your HTML


#1

HTML5 makes a lot of new features available to use with your websites. One of those features gives you the ability to tell search engines more about your pages. We’ll show you the best way to incorporate microdata into your Surreal-powered sites.

If you’re not already familiar with the microdata schema, you may want to catch up a bit before continuing.

Microdata in editable regions

As you’re probably aware, adding microdata to your sites requires markup with special attributes:

<span itemprop="addressLocality">Orlando</span>,
<span itemprop="addressRegion">FL</span>
<span itemprop="postalCode">32801</span>

What you may not be aware of is that these attributes will get stripped by the editor if you put them in a content region. As it turns out, there’s a really good reason for this to happen.

Let’s say, for example, that you want to change the above address from Orlando to Miami. In a WYSIWYG environment, a user would highlight the entire line (city, state, and ZIP), hit delete, and then type in the new address. The underlying markup would go from this:

<div class="editable" id="address">
    <span itemprop="addressLocality">Orlando</span>,
    <span itemprop="addressRegion">FL</span>
    <span itemprop="postalCode">32801</span>
</div>

To this:

<div class="editable" id="address">
    <span itemprop="addressLocality">Miami, FL 33101</span>
</div>

Or possibly even this:

<div class="editable" id="address">
    Miami, FL 33101
</div>

Now your microdata is useless, and you can’t blame your client—how can they edit something they can’t see?

Making microdata editable

But all that doesn’t mean you can’t edit microdata in Surreal. You just have to define your regions a bit differently. Let’s start by pulling it out of the existing content region:

<span itemprop="addressLocality">Orlando</span>,
<span itemprop="addressRegion">FL</span>
<span itemprop="postalCode">32801</span>

Now let’s make each span a separate content region:

<span class="editable" id="city" itemprop="addressLocality">Orlando</span>,
<span class="editable" id="state" itemprop="addressRegion">FL</span>
<span class="editable" id="zip" itemprop="postalCode">32801</span>

Now you can safely edit your microdata without issue.

Editing microdata attributes

If you need to edit microdata attributes, you’ll need to dive into the HTML directly. You can do this in Surreal by going to Edit > Edit Page Source in the editor.

And if you have a really savvy client that needs this capability, you can give them access in to Users > Privileges > Edit Page Source.

JSON Linked Data (JSON-LD)

Another option is to use JSON-LD to embed the same meta data into your pages without the need to add special HTML attributes.

This approach is just as effective as using microdata, and is even supported by major search engines. Here’s Google’s documentation on Structured Data, which features JSON-LD as the recommended way to embed this sort of meta data into your pages.

Here’s an interesting excerpt from Google about JSON-LD:

Markup is placed inside a script tag in the head of the HTML page. The markup does not have to be interleaved with the user-visible text, which makes nested data items easier to express, such as the Country of a PostalAddress of a MusicVenue of an Event. Also, Google can read JSON-LD data when it is dynamically injected into the page’s contents, such as by JavaScript code or embedded widgets in your content management system.

Moving forward, we’ll be recommending JSON-LD to all users looking to embed meta data into their pages.

This post was originally published to the Surreal CMS blog on June 4, 2015. It was migrated to the community forum on November 25, 2016.


Altering code that contains schema.org