Using Your WordPress Site’s Theme with TypeMetal
TypeMetal provides two ways to view and edit your WordPress posts and pages:
- using your site’s theme
- using a clutter-free “Clear View” theme
“Clear View” mode — which can be toggled using the “Clear View” toolbar button — helps you focus on your content, by providing a simple theme that’s free of distracting page elements. “Clear View” mode also provides a reliable fallback, that can be useful if TypeMetal has difficulty attaching to your site’s theme templates. — See below.
WordPress Themes, and TypeMetal Attachment Points
WordPress page templates can vary widely in their HTML markup structure. TypeMetal attempts to attach to your theme’s templates by looking for widely-used WordPress theme HTML attribute name conventions, but TypeMetal sometimes needs a little help adapting its attachment settings to your theme.
TypeMetal attaches to a post template at five points, that correspond to properties of the post that you can edit right in the page:
A WordPress “page” doesn’t have Categories or Tags, so the “Tags” and “Categories” attachment points aren’t needed for viewing and editing WordPress pages.
You can click “Dismiss” to disregard this warning, if you want. TypeMetal will still be able to display and provide for editing of your posts and pages using “Clear View” mode, but might not be able to do the same using your site’s theme.
It’s recommended that you instead click “Resolve…” to find out what’s wrong and attempt to fix the problem. When attachment point adjustments are needed, you should only need to make them once for a given version of a blog’s theme — potentially revising them only when you subsequently customize or upgrade your theme or switch to a different theme.
When TypeMetal syncs with your blog for the first time, it constructs a set of “template” files that it can use to present your posts and pages using your site’s theme. If you subsequently choose a different theme for your site, or customize or upgrade your site’s theme, you’ll want to ask TypeMetal to perform an “exhaustive” sync to pull down new template files. You do this by holding down the Option key while clicking either the “Sync” toolbar button or the “Login” button in the “Account” popover.
You can also summon the attachment point customization sheet by choosing Attachment Point Settings… from TypeMetal’s Blogging menu.
Configuring Attachment Point Settings
When you click the “Resolve…” button in the alert banner pictured above, TypeMetal displays a sheet that identifies the problem attachment points and prompts you to customize the attachment point settings for your blog’s theme:
The sheet lists the five attachment points TypeMetal looks for, and marks those it was unable to bind to with a yellow diamond icon. In the case pictured above, TypeMetal is indicating that it failed to bind to a template’s “Categories” attachment point.
To correct the problem, so that TypeMetal can correctly present your posts for editing using your WordPress site’s theme, you’ll need to tell TypeMetal how to find the “Categories” area. You can determine appropriate settings by examining the HTML markup for a category-bearing example post on your site. (The “Inspect” tool in Safari’s web page inspector provides an easy way to find the corresponding HTML markup, by clicking on the page area that lists your post’s categories.)
Alternatively, you can customize your site’s theme to add the standard attributes TypeMetal is looking for. That will enable TypeMetal to find its attachment points without requiring any customization of attachment point settings.
If you choose the former approach of customizing TypeMetal’s attachment point settings (generally the quicker solution), you just need to tell TypeMetal what to look for. To do so, click the checkbox to the left of the word “Categories”. The fields on that line become editable, enabling you to type in appropriate settings for your theme.
Suppose the HTML markup for an example post’s category list looks like this:
<span class="topic-links"> <a href="http://riggingtest.wordpress.com/category/food-groups/butter/" title="View all posts in Butter" class="topic-link">Butter</a>, <a href="http://riggingtest.wordpress.com/category/food-groups/wine/" title="View all posts in Wine" class="topic-link">Wine</a> </span>
This theme, for whatever reasons, marks up each of the WordPress categories listed for a post using an HTML “class” attribute value of “topic-link”, instead of using a “rel” attribute value that contains both “tag” and “category”, as TypeMetal is expecting. That’s fine. There are few hard and fast rules when it comes to WordPress.
To adapt TypeMetal to this theme’s conventions for marking up post category lists, you’ll want to edit the “Categories” line in the attachment point settings sheet to read: “Attribute class contains topic-link”. (You can leave the field to the right of “but not” empty.)
Click “OK” when you are satisfied with your settings, or “Cancel” to close the sheet without making any changes.
You can remove any or all custom attachment point settings for a blog by unchecking the corresponding check boxes. This reverts settings for the given attachment point to TypeMetal’s defaults.
Customizing Your Theme
As mentioned above, instead of providing TypeMetal with custom attachment point settings, you might choose to modify your theme files so that TypeMetal’s default attachment point settings will be able to find all of the desired attachment points. Only do this if you are comfortable modifying WordPress themes.
In the above example, where post categories aren’t marked up the way TypeMetal expects, you’d need to modify the markup template for a post’s category list to add a “rel” attribute of “category tag” to each category’s enclosing element. Note that doing so may affect the appearance of your pages. Be sure to adjust your theme’s CSS, if needed, to maintain the desired appearance.