Journal
Templating in Textpattern
14 September 2005 › 16 comments
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>. 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>, 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.
Discussion + Dissension
Comments closed after 2 weeks.
#1 Craig
Nice write up. I’ve been getting a lot of emails asking how I set up my if statements and whatnot. I’m not too keen on showing people my php code though. I’m really nervous about that sort of stuff.
#2 Yannick L.
Thanks Nathan. Really helpful article. I decided the other day to recode my website and also make a few changes to the look and now I’ll be using more of the output forms to.
You take care and all the best with the new job!
Peace and God Bless!
#3 Nick Dominguez
Nice write up Nathan.
I think we’re going to see Textpattern get alot more exposure with release 4. This will definetly help alot of newcomers like myself and more in the future.
I like the fact that you addressed some of the terminology in Textpattern which does seem to be a little misleading. “Forms” should be called “includes” or something, seems to me that is more of the function they actually serve.
#4 Nathan Smith
Craig: I’m confused as to why you’re nervous about showing off your php code. Would this somehow compromise the security of your Textpattern installation? I’m no guru, so I’m not sure why it’s an issue. Enlighten me. :)
Yannick: Thanks, I’m really enjoying my new job. Our office looks like the Nebechanezzer from the Matrix, with cool futuristic furniture. I’ve even got dual monitors on flexible arms. w00t!
Nick: I agree, that Textpattern seems to be taking off, with alot of interest since it’s been dubbed “stable.” I’m not sure though, that “includes” would be an accurate name, as TXP forms can be used as includes, but also as filters for manipulating data. I think Snippets or Chunks would be good, as these words are a far enough departure from familiar words like form or include. In my opinion, they are more flexible and versatile than WP includes (begin flaming).
#5 Yannick
Nathan: If you notice your furniture and computer missing tomorrow when you go into work, I had nothing to do with it okay. (Yannick runs and hides)
That is good though that you have a nice environment to work in. I am sure it will get those creative juices flowing. We are running on Win2k machines and a single 17inch CRT where I work.
Now go show those machines what you’ve got Nathan “Neo” Smith. :P
#6 Nathan Smith
Ha, thanks Yannick. It’s been fun thus far, and I’m looking forward to learning alot from all my new co-workers in the future. I feel like a kid in a forest, with these other great designers and thinkers towering above me. Lucky for me, they like to share their knowledge. :)
#7 Craig
@Nate
I guess I’m just anal or something. Some of my PHP relies on .htaccess and has some server specific markup so I don’t like showing this stuff. I had someone keep asking me to see my pre-parsed code and I just can’t bring myself to doing it.
You tutorial has nothing to do with this. In the beginning of your article you state that you were getting a lot of emails asking you to explain how you set up your TXP pages. It just reminded me of the requests I was getting.
Sorry for the confision.
#8 Nathan Smith
Oh, okay. That totally makes sense. I don’t think I’d want to show my .htaccess file either, and this is why I went with a purely CSS-based nav indicator, so that I wouldn’t even have to mess with additional server-side PHP, etc. Glad to hear I haven’t somehow compromised my TXP security.
#9 Jeff Adams
Have you seen the newly revised section and category tags. They seem to be pretty useful.
Also, it would be nice to see a photo of your new work space sometime.
#10 Nathan Smith
Jeff: I noticed that today, it seems very useful. This is something that Craig has been pushing for ever since Textpattern came out. However, I’m not using it on my site yet, because hard-coding
/about/etc. doesn’t bother me too much. I like that it lets you output specific navigation, and doesn’t just do a laundry list of sections, as you don’t always want every section on a navigation bar, or evey publicly viewable for that matter. The TXP crew has done a great job in implimenting the demands of the general populace. :)I'll try to get some photos up of both my workspace and my home office, once I find the USB cord to my digital camera. It seems to have got lost in the move, and I never bothered to shell out for a flash card, because it has on-board memory.
#11 Katie Dixon
Great article! Thanks for sharing your knowledge and experience with those of us that are new to TXP or simply wanting a better understanding of its inner workings. When is the next installment? ;)
#12 Nathan Smith
Katie, it’s funny you should mention that, because I’m actually planning a tutorial that will take the reader from start to finish, from downloading Textpattern, to getting it set up on a server, and actually customizing a template. This article will be written in conjunction with a set of comprehensive tutorials being featured at ErraticWisdom.com.
#13 Katie Dixon
That sounds great, Nathan! I will check back for that one soon.
#14 Sean
Great article. I am in the process of switching over from e107 because I liked the control that TextPattern gives. But I must say the learning curve is not a small one for themeing.
Is there a difference between the txp:s and the txp:section tags. They appear to do the same thing?
Also, if there is, is there a place I can get a complete list of the built in tags as the TextBook does not have the s one listed.
Thanks in advance.
#15 Sean
Sorry one more question. You say you don’t put the title in with your doctype form due to the dynamic nature of the the title. When I experimented with this though, it appears to work find with a dynamic title in the form that is fed into the page. I probably should be asking these questions in the textpattern forum but since you brought it up, I was just curious if I am missing something.
#16 Nathan Smith
Sean: That’s correct, the
txp:sandtxp:sectiontags do the same thing. I think that the shorter one is there for “legacy” support, so you might be better off using the full word, section. As far as doctype / code examples, you should check out these two links: Kusor TXP Tag Manual | Godbit TXP Code.