Using Embeds

An embed is simply an arbitrary piece of text or HTML that can be embedded within a blog post or page. For example, you might want to embed a map from Google into a post to provide directions to a local meet-up you are organizing. You can use Google Maps to generate the HTML you need, and you could embed it directly into the post, but mixing the generated HTML with your post’s text gets messy and confusing, and there is a good chance that the WordPress editor could mess up the inserted HTML if you are not careful.

However, if you create an embed called “meetup-map” for the map’s HTML instead, the only thing you need to put in your post is [meetup-map] where you want the map to appear, and the map’s HTML will be embedded in your post automatically. Keeping the map’s HTML separate makes it much safer to edit your post, and allows you to reuse the same HTML in other posts later.

The Embedder plugin gives you two ways to define an embed:

  • If you only want to embed some text or HTML into one post or page, you can use a Custom Field to quickly create a local embed for that post or page.
  • However, if you want to use an embed in multiple posts or pages, then you need to create a global embed using the Embeds settings page.

Local Embeds

To create a local embed, edit the post or page you want to put it in and scroll down to the Custom Fields section. There you can create an embed by adding a new custom field.

For the custom field Name enter the name of the embed enclosed in square brackets: i.e. [name] and for the custom field Value enter the text or HTML you want to embedded in the post or page above. (The square brackets around the name tells the Embedder plugin that this custom field is a local embed.)

To use the local embed you created, simply insert the embed’s name (complete with the square brackets) anywhere in the post’s contents.

For example, to embed a cool smiley face icon in your post, create the following custom field:

  • Name: [smiley]
  • Value: <img src=”//”/>

Then to have the smiley face appear simply add [smiley] somewhere in the post. (Which is exactly what I just did here!).

And, of course, you can use the same embed as many times as you want in the same post.

Global Embeds

The true power of embeds is revealed when you start creating global embeds for use in any or all of your blog posts and pages. To continue with the example above, if you want use the cool smiley face icon in all your posts, you can create a single global embed for it, and then the smiley face will be available to you whenever and wherever you want to use it.

Creating a global embed is just as easy as creating a local one:

  1. Go to the Manage Embeds settings page (Settings >> Embeds).
  2. Click the Add New Embed button.
  3. On the Add Embed page, enter the Name of your embed (without the square brackets).
  4. Optionally, you can enter a Description for your embed, to help you remember what you are using it for.
  5. In the Value field, enter the text or HTML of your new embed.
  6. Finally, ignoring the other options for the moment, click the Add Embed button at the bottom of the page.

And that’s it. You have created your first embed which you can use anywhere in your blog.

So, to create a global embed for that cool smiley face icon above, you would enter the following information in the Add Embed page:

  • Name: smiley
  • Description: Just a cool smiley face icon
  • Value: <img src=”//”/>

Once you have added the embed, you can use it in any blog post or page content by inserting [smiley] into the text.

All the global embeds you create will be displayed in the table on the main Manage Embeds settings page. From there you can edit, rename, copy, disable, and delete your embeds. You can also click on the links in the column headings to sort the embeds in the table.

Notes on Embeds

Be careful when renaming a global embed that’s already in use. The places where you are using it will stop working until you also rename the shortcodes in the posts and pages you are using the embed in. (Auto-embeds do not have this problem.)

If you define a global embed and a local embed with the same name, the local embed will be used. This allows you to override the a global embed in a specific post or page, if necessary.

Be careful when you are using other plugins that use shortcodes. If you use the name of an embed that is recognized as a valid shortcode by another plugin, the results will be unpredictable. However, there is no reason why you can’t use the Embedder plugin alongside other shortcode-using plugins, just be careful to avoid the names that the other plugins use.

There is a known bug in WordPress that will cause a embed (or shortcode) not to be processed if it placed immediately after another embed (or shortcode).  For example, if you placed [map][directions] in the text of a post, only [map] will be processed, and you will see the text “[directions]” appearing after the map. The workaround is to put something between the two embeds, like a space character, or an empty <em></em> element, if the extra space causes formatting issues.