Quick Reference Guide

This page is a quick reference guide to all the main feature of the Embedder plugin.

Local Embeds

• Use local embeds when you are only embedding HTML into one post or page.
• To create a local embed, edit your post or page and add a custom field.
• The custom field Name should be the name of your embed enclosed in square brackets (e.g. [hulu_video])
• Add the HTML you want to embed to the custom field Value.
• If you want to use the local embeds in the post’s comments, create another custom field for the post, and call it embed-comments. The value can be set to anything. (Note: this will make all local embeds on this post usable by anyone who can add a comment.)
• Local embeds can also be used in the post or page’s title.
• Local embeds can use embed attributes and default values (see below).

Global Embeds

• Use global embeds when you want to embed HTML into multiple posts or pages, or in sidebar widgets (including their titles).
• To create a global embed, go to admin page Settings >> Embeds and click the Add New Embed button.
• Global embeds can have the following settings:
  • Name: a single word (no spaces) shorter than 64 characters. “-” and “_” can also be used as word separators, but “_” is recommended.
  • Group: select a group for the embed to belong to.
  • Description: (optional) can be used to add helpful information about what the embed does.
  • Value: the HTML or text you want to embed in your blog.
  • Options: (optional)
    • Allow the embed in comments: the embed can be used in any comment on the blog. (Caution: setting this option means that any commenter can also use the embed.)
  • Auto Embed: (optional) automatically use the embed in one or more of the following locations:
    • Before the content of a single post on a page
    • After the content of a single post on a page
    • Before the content of all posts on pages with multiple posts
    • After the content of all posts on pages with multiple posts
    • Before the content of a page with no posts on it
    • After the content of a page with no posts on it
  • Priority: (optional, when auto-embed is selected) used to specify the order in which the auto-embeds should appear when there are two or more auto-embeds in the same location. Embeds will appear in numerical order (e.g. priority 10 before priority 20). The positioning of embeds with the same priority is undefined.
  • Include/Exclude: (optional, when auto-embed is selected) used to select the posts and/or pages the auto-embed should appear in:
    • Categories: use category names or slugs, separated by commas. If the category name has a comma, only the slug can be used. All posts in the specified categories’ children will also be included/excluded.
      • Include Categories: the auto-embed should appear in posts that are in these categories.
      • Exclude Categories: the auto-embed should be excluded from posts that are in these categories.
    • Tags: use tag names or slugs, separated by commas. If the tag name has a comma, only the slug can be used.
      • Include Tags: the auto-embed should appear in posts/pages with these tags.
      • Exclude Tags: the auto-embed should be excluded from posts/pages with these tags.
      • (Note: for tagging pages, I highly recommend the TagPages plugin.)
  • Wrap Embed: (optional) place the embed inside a <span> or <div> element to allow for extra styling of the embed:
    • Wrapped by span: use the span element when you want the embed to appear inline with the content around it.
    • Wrapped by div: use the div element when you want the embed to appear in a block on its own.
    • CSS Class Name(s): one or more CSS class names separated by spaces. The specified classes must be included somewhere in the style sheet for the web page the embed will appear on. If they do not exist, no styling will be applied. Embed attributes may also be used in this field.
    • CSS Style(s): one of more CSS styles separated by semicolons. Any valid CSS style may be used, and embed attributes may also be included.
  • Call User Function: (optional) when selected, you can specify a PHP function to call when the embed is used in the blog’s content (like a typical WordPress shortcode). The function should exist somewhere in the blog’s source code (typically in the theme’s functions file—functions.php—or in another plugin. The function is called before the embed attributes are processed. When you use this option, the Value field is optional.

Global Embed Table

• The main Manage Embed admin page lists all the global embeds defined for the blog, and provides access to the following actions on each embed:
  • Edit: edit the embed settings.
    
  • Rename: rename the embed. The new embed name must be unique.
    
  • Copy: copy the embed and all of its settings. The new embed must be unique.
  • Export: export the embed and all of its settings. A serialized (text-version) copy of the embed will be displayed, where it can be copied using the clipboard to a file or editor for importing into another blog using the Embedder import feature.
  • Disable/Enable: Disable/enable the embed. (Caution: Disabled embeds will be excluded from the blog’s contents which might cause unpredictable results in some cases, if the post depends on the embedded HTML for correct formatting.)
  • Delete: Delete the embed. (Caution: Deleting an embed that is still being used in the blog will cause the embed’s shortcode (e.g. [hulu_video]) to appear instead.)
• Global embed settings can also be changed at any time by clicking on the embed name in the table.
• Embeds can be sorted by name, description, or value (in alphabetical order and reverse alphabetical order). Click on any of the blue column headings to sort.

Embed Attributes

• Embed attributes can be used to replace almost any part of the HTML placed in the embed’s Value settings field.
• They allow you to specify different values in the embed each time you use the embed in your blog.
• To specify an attribute, include its name in between two % signs: e.g. %width% and %color%
• When using the embed, you must specify the attribute value by including it in the embed: e.g. [bar width=”50px” color=”green”]
• Attributes may also have default values, specified using the format %name=value%: e.g. %width=50px% and %color=red%.
• Attributes with default values become optional and can be omitted: e.g. [bar width=”100px”] will automatically use red for the color attribute.
• The special attribute %content% is used to include post text placed between the embed’s start and end tags in your embed. Thus in the example, [fgcol c=green]Hello[/fgcol], the %content% attribute will be placed by Hello.
• An attribute can appear in the same embed more than once. All instances of the same attribute will use the same value.
• For multiple instances of the same attribute, their default value only needs to be set in one place.
• A attribute’s default value can be set to an empty string like this: %name=%
• To include a % sign or backslash in an attribute value, it must be preceded by a backslash (): e.g. %width=50%% or %text=matter\mind%
• Embed attributes may also be used in the Wrap Embed fields (CSS Class Name(s) and CSS Style(s))
• Do not use embed attributes without default values when you are auto-embedding.

Embed Groups

• Embed groups can be used to organize your global embeds into groups to make them easier to track and manage.
• To create a new group, click the Add New Group button at the top of the main Manage Embed pages.
• Group names can be up to 63 characters long, and can include spaces, and upper-case letters.
• The Default group is automatically created when the Embedder plugin is installed.
• Embeds are listed by group in the main Manage Embeds settings page, and the groups are listed in alphabetical order.
• Empty groups are listed at the bottom of the page.
• Groups can be expanded or collapsed. Click on the blue icon next to the group name to expand/collapse a single group.
• Click on Expand All Groups to display all embeds in all groups.
• Click on Collapse All Groups to display only the group names.
• Most groups have the following actions available:
  • Rename: rename the group. The new group name must be unique.
  • Disable All: disable all the embeds in the group.
  • Enable All: enable all the embeds in the group.
  • Export All: export all the embeds in the group.
  • Delete: delete the group. The embeds will not be deleted. They will be moved to the Defaults group.

Import Embeds

• Click on the Import Embeds link if you have one or more embeds to import.
• Paste one or more previously exported embeds into the text box and click the Import button.
• If an embed with the same name as an import exists, the imported embed will be renamed.
• Imported embeds are disabled and have (IMPORT) added to their description so that you have a chance to examine them before they are made available in your blog.
• Error messages will inform you if the import failed. Correct the problem and try again.
• If there is an error while you are importing multiple embeds, some of the embeds may have been imported successfully before the error occurred.

Additional Notes

• Unicode characters (UTF-8) can be included in an embed’s Description and Value fields only.
• WordPress limitation: Do not place two embeds directly next to each other. Always use at least one space to separate them. If a space would mess up the formatting, you can use <em></em> instead.
• WordPress limitation: You cannot nest two embeds with the same name inside each other. As a work-around, add a digit (0-9) to one of the embeds and the plugin will still recognize it as the same embed. For example, instead of using [bigger] [bigger] [/bigger] [/bigger], use [bigger] [bigger2] [/bigger2] [/bigger].