Templating in Textpattern

— Topic: cms

I'm Not Dead

I know it's been awhile since my last post, nearly two weeks of neglect, but with a good excuse. If you've been keeping tabs on my site, you'll know that I recently got a new job. We've spent the last week on the road, moving cross-country, and are finally in our new place. We still don't officially have internet access, but I managed to pick up a stray wireless signal from a neighbor, who is sharing bandwidth either benevolently or unknowingly.

I have been getting quite a few emails asking me to help set up Textpattern sites, but am a little to busy for that right now. So, I decided to do the second best thing, and that's to write a brief tutorial. This by no means should be considered to be comprehensive, as there are already a slew of TXP resources out there. I just wanted to share a few things that I've figured out while working with this CMS that might help save others some initial learning-curve headaches.

TXP Forms

Forms is not really an accurate name for this Textpattern feature. They are not your typical HTML forms that you would enter various data into for storage or email. Instead, think of them as chunks or snippets of code that are used often. These can also be used to format the output of articles, links and just about everything else. The backbone of your templates will most likely be built on forms.

There are two very handy features to forms. First of all, they can be called from within a <txp:article_custom /> tag, to manipulate the way various portions of an article are displayed. For instance, you could output an article's title, date, body and comments, or pick and choose which aspects you want to be displayed. This is done by going to your Presentation » Forms section. Your default form will have the syntax present for displaying a typical blog entry, such as the aforementioned aspects. You can of course change this to suit your needs.

There is already a cheat-sheet built into TXP to help you with using the various syntaxes, which is easily accessible via the links to the left of your interface. So, rather than go into great detail about using the these tags to format your forms, I will focus on the second a second aspect of forms, the <txp:output_form />. This can be used to pull chunks of often used code into your pages.

For the longest time, I just used to have non-dynamic aspects of my pages hard-coded into each of my page templates, and used only <txp:article /> tags to pull in the dynamic, blog-type articles. While this is great for various write-ups that are journal entries, it's not so usable in a situation requiring straight code to be reused multiple times.

For instance, on this site I use the same persistent XHTML 1.1 DOCTYPE and CSS styles throughout, so there's really no point in having this all written out in the <head> of each page template. So, I made a form entitled doctype which contains everything except the <title> of the page, as these change dynamically based on site section. At the very top of each of my templates, there is <txp:output_form form="doctype" /> which is then replaced with the appropriate HTML. This saves a lot of file-size as opposed to having all of the various parts (other than the article) hard-coded into the template, not to mention that you can call these reoccurring paragraphs and snippets into other pages just as easily.

Note: For instance, compare these templates: Small | Large.

My static template drives most of the sub-sections of this site, ones that change infrequently. Basically, whenever I have a section of text or code that I want to reuse throughout the site, but it does not fall under the category of an article, I go to the Presentation » Forms section, and make myself a new form. While the form type can be whatever, I recommend using the misc category from the drop-down menu, to help distinguish your custom made output_form from the other article / link types.

All About the "S"

No, this isn't a plug for Sketchers shoes, though I do have a pair and they are very comfortable. I will now turn my attention towards the obscure <txp:s /> tag, found in the previous small static template example. If you take a look at it again you will notice that this TXP tag appears twice, once in the <title> and another time in the <body> tag.

All this does is output the name of the section that you are currently in. Big deal — So what? Well, considering that you can use this to assign varying styles to your pages based on section, and by using the same page template, this is a very handy tag indeed. By using it to add a class to your body tag, you can subsequently style everything that it further down the cascade. This is how my sub-pages style the corresponding button with a small arrow indicator. For instance, check out this CSS snippet…

body.about #nav a.n2,
body.archive #nav a.n1,
body.contact #nav a.n8,
body.desktops #nav a.n7,
body.journal #nav a.n1,
body.portfolio #nav a.n4,
body.questions #nav a.n2,
body.resources #nav a.n5,
body.search #nav a.n1,
body.services #nav a.n3,
body.theology #nav a.n6 {
	background: url(/img/arrow.gif) no-repeat center top;
	border-top-color: #996;
}

All that garbled schtuff just means that when there is a body.classname, then make the appropriate section's link on the #nav have a darker border-top and add in the arrow image. I've named the a.class with a N (for nav) and a number afterwards (because CSS classes cannot begin with a number). I did this to correspond with their order in the navigation bar, as well as in keeping with the numbering of each accesskey.

Note: While I came up with the above method on my own, I just realized that there is already a very similar method out there, pioneered by Jon Hicks. Mine varies only slightly in that I use a class for the body rather than an ID. There is also another cool <txp:s /> method that involves a bit of PHP trickery, and was developed by Craig Erskine.

You Talking to Me?

Another frustration that is shared by many Textpattern users is that of customizing and styling how the comment_form is displayed. Prior to the Textpattern 4.0 stable release, previous versions offered little options to tweak the appearance. Most people were forced to hack their PHP file in order to get usable ID or classes into the form. Thankfully, the latest release has an ID called #txpCommentInputForm in the HTML <form><input type="hidden" name="phpMyAdmin" value="7f5f0aec2286bb95a2290f59f32bfc82" />. Based on this, you can customize quite a bit of the appearance, without having to hack your PHP.

Realizing this, and wanting to keep my CSS to a lean minimum, I hacked the zem_contact plugin from Threshold State to be able to reuse the same styling I gave to the comment_form on my site. In the Textpattern interface, if you go to Admin » Plugins, you can edit any that you have installed. First, I would suggest copying and pasting the code into an HTML editor. I use Araneae because it's free, but anything with line numbering will work just fine.

At around line 72, you will need to add id="txpCommentInputForm" into the <form><input type="hidden" name="phpMyAdmin" value="7f5f0aec2286bb95a2290f59f32bfc82" />, and this will enable all the styles you give to your comment form to apply to your email contact form. You may also want to do a find and replace to get rid of the <b> tags and replace them with <strong> in order to keep your XHTML valid. Or, in my case, I simply got rid of these tags altogether, as all they do is indicate required fields. In my opinion, if fields are not required, just don't include them, as this helps streamline things for the user.

Etcetera

If you are extremely picky about your comment form, and want to force the tab index to flow better than TXP does by default, you might want to check out the article over at Jaredigital that explains how to do this. You might also want to check out this cool hack done by my coworker Cody Lindley, enabling <div> support in textile. This allows you to easily insert one into your articles.

I guess that about sums things up for this brief tutorial. If anyone has any further Textpattern questions, or would like to see other topics covered in a future tutorial, just let me know and I'll see what I can do.

Me, elsewhere