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 particular theme.
TypeMetal attaches to a post template at up to six points, that correspond to properties of the post that you can edit right in the page:
- Featured Image
- Body
- Title
- Date
- Tags
- Categories
The “Body” and “Title” attachment points are the most important. “Date” is optional. The others are only necessary when a post has a featured image, tags, or categories to display.
A WordPress “page” doesn’t have Categories or Tags, so the “Tags” and “Categories” attachment points are never needed for viewing and editing WordPress pages.
If TypeMetal can’t find one or more of these attachment points in a post or page template, it will alert you at the top of a blog or post window’s content area:
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, or customize or upgrade your site’s theme, you’ll want to ask TypeMetal to download new theme templates from your site, by choosing Fetch Theme Templates from TypeMetal’s Blogging menu or by performing an “exhaustive” sync. 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 six attachment points that 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 was unable to find the template’s “Tags” attachment point. It also did not find attachment points for “Categories” and “Featured image”, but those are shown with a dimmed caution indicator because the post being displayed does not have categories or a featured image, and therefore does not need those attachment points.
To correct the problem that’s impeding complete display of the current post, you’ll need to tell TypeMetal how to find the “Tags” area. You can determine appropriate settings by examining the HTML markup for a tag-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 tags.)
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 “Tags”. The fields on that line become editable, enabling you to type in appropriate settings for your theme.
The default settings that TypeMetal suggests (shown as dimmed tokens until you click the row’s checkbox) can vary based on your site’s theme. Newer themes that are designed for WordPress Block Mode tend to use a more standard set of conventions. For older themes, there tends to be less CSS-class-name uniformity, so it’s more common to need to override TypeMetal’s best guesses. The default attachment point settings are:
| Attachment Point | Block Mode CSS Class | Non-Block-Mode CSS Class(es) |
|---|---|---|
| Featured Image | wp-block-post-featured-image |
entry-thumbnail |
| Body | wp-block-post-content |
entry-content |
| Title | wp-block-post-title |
entry-title |
| Date | wp-block-post-date |
entry-date |
| Tags | taxonomy-post_tag |
tag and not category |
| Categories | taxonomy-category |
tag and category |
Suppose the HTML markup for an example post’s tag 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 tags listed for a post using an HTML “class” attribute value of “topic-link”, instead of using the relatively standard class names shown in the table above. 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 tag lists, you’ll want to edit the “Tags” 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 tags aren’t marked up the way TypeMetal expects, you’d need to modify the markup template for a post’s tag list to add a “class” attribute of “taxonomy-post_tag ” (if using a newer theme designed for Block Mode) to the parent element that encloses all of the tags displayed for a post. 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.