While being able to embed HTML and text anywhere you like in your blog content is cool enough, using embed attributes can give your embeds even more power and flexibility.
For example, when embedding a map from Google, the height and the width of the map are set on Google’s website and inserted into the HTML Google generates for you. But it probably takes some trial and error get the dimensions for the map right, which means you would normally have to keep editing the HTML by hand, or keep going back to Google Maps to enter new values for the width and height before cutting and pasting the regenerated HTML back into your blog post.
But instead of this back and forth and playing with the map’s messy HTML code, you can simply create an embed for the map (call it my-map), and then edit the map’s HTML once to replace the hard coded width and height values with attributes called %width% and %height%. E.g.
change: <iframe width=”425” height=”350” frameborder=”0″…
to: <iframe width=”%width%” height=”%height%” frameborder=”0″…
Now insert your embed into a post as before, but this time you can supply it with values for the width and height attributes:
[my-map width=”500″ height=”400″]
Then if you find that the values are not correct, you can just edit in new values right there in your post.
As an added bonus, you can use the same map in other places in your blog using a different width and height.
Defining Attributes
To add an attribute to an embed, simply insert a word enclosed by % signs. For example, %width%, %height%, %a%, %color%, %item1%, and %bg-color% are all valid attribute names. Only alphanumeric characters and ‘–‘ and ‘_‘ can be used in attribute names, and they are not case-sensitive. (%COLOR% is the same as %color%).
When you use attributes with global embeds, the plugin identifies the attributes you have used in an embeds and displays them in attributes column in the table. This is useful information for when it comes to using an embed with attributes.
You can add as many attributes as you like, and you can use the same attribute more than once in the same embed.
You cannot set an attribute value to an HTML string and have interpreted as HTML, but you can use attributes to set things like HTML tag name, attribute names and values, and CSS class names.
Check out the following three examples for an embed called hilite to see the difference:
This first one does not result in any HTML tags being embedded:
The embed: %open%Hello World%close%
In the post: [hilite open=”<b>” close=”</b>”]
Result: <b>Hello World</b>
But if you put the angle brackets in the embed itself, you do get valid bold tags:
The embed: <%tag%>Hello World</%tag%>
In the post: [hilite tag=”b”]
Output: Hello World
Better yet, you can specify a CSS style attribute in the embed instead:
The embed: <span style=”color:%col%;”>Hello World</span>
In the post: [hilite col=”red”]
Output: Hello World
The %content% Attribute
There is one special attribute that allows you include some text from your post in an embed. For example, instead of just putting the words “Hello World” in red, as in the example above, if you want to be able to highlight any text you like in another color, you can use the %content% attribute:
The embed: <span style=”color:%col%;”>%content%</span>
In the post: The Giants[hilite col=”red”]WIN[/hilite] the [hilite col=”blue”]World Series![/hilite]
Output: The Giants WIN the World Series!
Use the extended embed (shortcode) format to enclose the text you want to be highlighted. Everything you put between the embed’s begin and end tags automatically replaces the %content% attribute.
Notes On Attributes
If you define an attribute in your embed. but forget to include it when you use the embed, it will be replaced by an empty string. This will also happen if you misspell the attribute name. This is useful in cases where the attribute is optional, but can lead to some unexpected results if you are not careful.
If your embed contains text that can be mistaken for an attribute name (i.e. a string with only valid characters for embed names surrounded by % signs like %word% or %test-1%) then you can prevent the plugin from processing the text as an attribute by adding !! to the front of the name.
For example, %word% should be %!!word% and %test-1% should be %!!test-1%.
The extra !! will be stripped out by the plugin, leaving the original string unchanged.