Textpattern Building Block Mechanics

by Destry Wion  ::  published 30 May 06    

Overview

Here is the second article of a two-article series about Textpattern building blocks. If you missed the first article, Understanding Textpattern Building Blocks, you might check it out too.

The intended audience of this article is still people new to Textpattern, but I now assume a reader has decided to install Textpattern and is ready to begin doing something with it.

Attention: If you’re just looking for code examples, you won’t find that in this article. Code examples (and their topics) are better served in separate articles for simplicity and focus, and in any case are subjects to approach after understanding the mechanics I present here. Nevertheless, this article is filled with tips, leads, and other gems of information that should be useful to many.

My primary aim for this second article is to cover building block mechanics; in other words, how you create them and where you do it. However, it will be worthwhile to first cover some additional (but important) concepts that should go a long way at saving newcomers some grief. These concepts include:

• Site structure blueprints — important for ensuring that when site creation take place, it’s done with some reason and efficiency.
• Article flow and the underlying building block defaults — important for understanding Textpattern’s publishing mechanism.
• Post-installation configuration — important for ensuring you are on the right track before pimping your Textpattern ride, as it were.

As in the first article, building block components are referenced with capitalizations and italics (e.g., Sections) so there’s no confusion between them and other similar, but general, terms. Also, it is my interest to support Textpattern documentation efforts already in progress, not reinvent the wheel, so I’ll be referencing various documentation pages in the TextBook wiki as I go along, particularly the various Site Administration pages as they correspond to the building blocks in focus.

Recapping the Building Blocks

To begin, let’s recap the various building blocks presented in the first article, and include the basic concepts learned:

• Sections — provide pseudo-structure and give a place to assign a Page (the XHTML template) and a Style (the accompanying CSS styling).
• Pages (a.k.a. templates) — are a type of managed (stored in database) content serving a presentational role; they provide the XHTML framework in which various other content types will be dynamically inserted, most notably from Forms and Tags.
• Forms — discrete “chunks” of XHTML markup and Textpattern Tags that define various sorts of content (headers, navigation, lists, and so forth) to be displayed in a Web view.
• Tags — the fundamental components of Textpattern that designate how content pieces are to be processed and/or inserted in a Page for Web rendering; can be added directly in a Page template or inserted via a Form.
• Styles — another type of managed content serving a presentational role; the CSS styling (aesthetics) of content rendered in browser view.
• Categories — provide grouping abilities for usable content (text articles, images, links, et cetera), which in turn allows—by way of clever Tag and Form use—multiple displays of said content.

All that ring a bell? Good. Now, before I dive into the mechanics of things, let’s cover the additional insights I mentioned, starting with the all-important site blueprints.

Blueprints for Success

At this point in the game you should really have an idea of your anticipated site structure, even if it’s just a sketch on paper, though hopefully it’s a bit more conceived than that. Consider this the blueprints for your site. Your blueprints should include the main sections you expect your site to have (About, Journal, Contact, whatever), the differing template elements and layout you anticipate having from one Web view to another, the various topic groupings desired, and the linking strategies between it all. That’s the first part of the blueprints, the user-side perspective (the part that designers show clients as pretty mockups).

Once you have the user-side reasonably worked out it’s easier to conceive the various custom building blocks you will ultimately need, and that brings you to the administration side (admin-side) of things. A significant consideration in the admin-side of things is how you name your custom building blocks. Except for Tags, all building blocks you create will need to be labeled, and you want to do this with some consideration to simplicity, semantics, and building block associations. I’ll touch upon this labeling concept again later as we get into creating the building blocks themselves.

Also, don’t underestimate how valuable it is to reuse Textpattern’s default building blocks in your actual site creation, and therefore take them into account in your structural blueprints. Recycling default building blocks reduces your need for additional custom components, which in turn reduces bloat in your site architecture, refines your admin interface, and generally lowers your overhead maintenance. Furthermore, default components in Textpattern cannot be deleted (the important ones anyway), even if you did not want to use them; hence, they provide a measure of content safety that you might as well take advantage of.

Of course nobody has perfect blueprints from the start, you will likely tweak things as you go along, and there is no better learning than from trial-and-error development, but if you don’t have even basic blueprints to start with, you will waste many hours (if not days or weeks) changing and rechanging things; even more, you will likely end up with a back-end that has more than a few spare parts lying around.

Article Flow and Building Block Defaults

When you first install Textpattern, it is ready to begin working for you immediately. You don’t have to create Sections, Pages or anything else, you can simply write your first article, hit the “Save” button, and the article will be posted live to the world on the home page (the default page). If you continue in this manner, each article you publish will be added to the home page in reverse chronological order and continue to accrue into a very long scrollable page.

The ability to publish immediately is made possible by a number of building block defaults that are already in place, and the behavior of Textpattern to always publish articles to the main page is known as article flow.

Article Flow

A good understanding of article flow can work in a designer’s favor; a lack of understanding can lead to high frustration. However, it’s not an overly complicated concept; arcticle flow is simply Textpattern’s default publishing mechanism that pushes published articles to the main (default) page.

Article flow is not something you can switch on or off; it’s always there, working, and a designer must work with it, work around it, bend it to his/her needs in clever ways in order to make articles of various topic nature appear in different places of a Web site. For example, you may not want your About and Contact information showing up on the home page, you’ll probaby want those topics being published in different site locations as site visitors generally expect them to be. How does one do this? With the building blocks, of course, and especially with the all-powerful Tags, using them in strategic ways to create various publishing channels outside of the systems default tendancy.

Building Block Defaults

Below is our list of building blocks again, but this time the names of their associated default components (in bold) are indicated:

• Sections: article (There’s also an about Section, which is not used for anything by default but is simply made available for you to use later.)
• Pages: default
• Styles: default
• Forms: There are a number of system default forms, each meant to serve a different need or to provide you with a place to start. All of these can be customized, of course, but you don’t need to for anything to work, and the only one we need to be concerned with at the moment is default.
• Categories: There are no default Categories. These will come about from your own creation process.
• Tags: Every Textpattern Tag can be considered a default, they are simply there in Textpattern waiting for you to use; but as you might guess, there are a few basic Tags put in place already, such as in the “default” Form, which I’ll talk more about shortly.

Here’s how Textpattern makes these work for the default article publishing process. For any Section to work in Textpattern, it must have a Page and Style assigned to it, and Textpattern ensures this right out of the box. The “default” Page and Style are (by default) associated to the “article” Section. These three building block components—Section, Page, and Style—effectively establish the functioning home page to which the article can be published.

The article itself is composed of different article pieces (title, body, author, etc.) which are defined in the “default” Form by XHTML and a special group of Textpattern Tags called Form Tags. The “default” Form (or any Form) is called by another special group of Tags called Page Tags, which are added directly in Page templates to indicate where the Form code will be dynamically inserted, which in turn will output the defined article pieces in Web view. Normally you would generate the Tag markup yourself using Tag building tools in the administration interface (which I’ll discuss in the last section of this article on Tags), and you will for custom Pages and Forms you come to create, but for default purposes all the needed code is in the “default” Page template already.

As indicated earlier, there are no Categories involved in the default publishing process.

Now, let’s look at the default Form a little closer, which again is the article Form Textpattern uses to publish articles to the main page by default. For clarity, I’ll replicate the first portion of the “default” Form below (lines of code are wrapped a bit here for convenience):

<h3><txp:permlink><txp:title /></txp:permlink> &#183; 
<txp:posted /> by <txp:author /></h3>
<txp:body />
<txp:comments_invite wraptag="p" />

If you are familiar with XHTML markup, then you should recognize the <h3>...</h3> header tag in the Form snippet above. All the other Tags containing txp: are Textpattern Tags, and each serves a unique purpose.

The “permlink” Tag (<txp:permlink>...</txp:permlink>) defines the direct link location of the article itself. In other words, each article you will come to publish in your site will be stored in the database and given a unique location value (translated into a given URL); the permlink is that specific location, and the permlink Tag is what you use to tell Textpattern where to go to find that article’s various content pieces (and those of every other article, as necessary). As you can see, the permlink Tag is composed of both an opening and closing element, and is thus called a Container Tag. An important thing to realize here is the permlink Tag only knows where to find a given article, it doesn’t actually tell Textpattern which pieces of that article will be used. Outputting article pieces is the responsibility of other Tags, the next four of which are examples.

The “title” Tag (<txp:title />) is associated to the title of a given article. Wherever you use this Tag an article title will be output as content in a Web page view. In the default Form snippet shown earlier the title Tag is contained within the permlink Tag; this makes the article’s title a link to the article’s permanent location in the database. The value of doing this is to give your site visitor’s a means of bookmarking the article for future reference (very important if you want visitors to easily come back to your articles). If you were to simply use the title Tag without the permlink container, the title would still be output, but it would be just a regular text header with no link. Note also the title Tag is a Single Tag (having its own closing fore-slash), as are the rest of them being described here.

The “posted” (<txp:posted />) and “author” (<txp:author />) Tags are two more that correspond to pieces of a given article; in this case, the date the article was first saved in Textpattern (which can be manually changed any time) and the author of the article, respectively. You can see how I am using these two Tags to output my name and article publish date at the top of this article (assuming you are not reading this from print).

The “body” Tag (<txp:body />) is of course the body of a given article. Whenever you use this Tag in an article Form, the main body of an article will be pulled from the article’s location in the database and displayed as published content. The body Tag is very significant with respect to how Textpattern functions. Whenever Textpattern makes a call to a given article, it does so to the article’s body. The other article pieces (title, date posted, author, etc.) are all ancillary; the body is the key that ties them all together.

The last Tag in the “default” Form snippet noted earlier is the “comments invite” Tag (<txp:comments_invite />), which simply provides a link to the comments form (a real XHTML Web form this time) for each article being published with the default Form. You’ll see there is a “wraptag” attribute being used here (<txp:comments_invite wraptag="p" />), which is being used here to help control how standard XHTML markup behaves in conjunction with the comments form.

The Tags I described above are only a few of all that exist. As you become more comfortable with Textpattern, it is the Tags you will spend most of your time working with (with the exception of your writing, of course). I’ll come back to Tags again near the end when introducing the Tag building utilities. I’ll also point out the best online resources for helping you get up to speed with Tags.

Now that you understand a bit about article flow and the underlying default building block components, it’s time to switch attention to the workshop where creating, modifying, and customization takes place.

Administration Interface (Building Block Workshop)

The administration interface is where you will manage every aspect of your Textpattern site, well beyond just the building blocks themselves. Assuming one may be looking at the administration interface for the first time, I think it would be prudent to go over a few important checkpoints (and associated workflow) that anyone should address before jumping into creativity.

Basic Configurations and Error Checking

The administration interface will always be located at .../textpattern/index.php relative to where you have Textpattern installed (i.e., whether at the domain root or in a subdirectory). You will likely want to bookmark that location for convenience. After installing Textpattern, you will be required to log in with the log in details you created during the installation process.

Manage Languages (First Log In View)

Upon your first log in, you’ll be immediately taken to the Language view of the Preferences panel. You won’t have to do anything there if you just installed Textpattern for the first time as your language selection will be part of the initial installation process, but note the language file you added during the installation. Whenever you upgrade your Textpattern site to a new stable version, you will be brought to the Language view again when first logging in and will need to update your language file manually. This is a simple click of the “Install” link next to the language of choice. The language files are subject to improvements between Textpattern releases, which is why the manual updates are necessary.

Basic Preferences (Just the Fundamentals)

Next you want to get your basic preferences in order, this could take you a few minutes so don’t be in a rush. At the top of the Language view you’ll see two other button links: one for Basic and one for Advanced. You don’t have to immediately worry about Advanced; you can peruse that another time when you’re curious (and it is worth doing). However, you do need to click the Basic button and configure your Publish and Comments settings. Of most importance is the Publish settings (and especially the Site URL field), but you’ll likely want to cover both.

Site Diagnostics (System Status)

Next you most definitely need to check your site diagnostics and make sure everything is in order. Click the Diagnostics panel, which is immediately left of the Preferences subtab panel discussed above. The Diagnostics panel is a wonderful feature of Textpattern, and the forsight of the developers to include such a feature in a publishing system should be applauded. There is a wealth of information in the Diagnostics details, should one understand server technology at a higher level. Not only does the diagnostics information help you troubleshoot your Web site on your own, but in more complicated situations, you can bring your diagnostics information to the Textpattern Support Forum’s Troubleshooting area where developers (and others) can more effectively help you remedy your problem. The Textpattern community is a wonderful and helpful bunch.

If everything has gone well up to this point, you should see one diagnostics error showing, which is indicated in red text at the top of the Diagnostics panel. The error should be telling you that you still have a “setup” folder in your administration directory, namely ../textpattern/setup. Again, this is a folder, not a file, and you simply need to go delete it (along with all of its contents). Do that and your one diagnostic error should go away after you refresh your panel view.

That’s more or less it with the basic, critical setup stuff. You are encouraged to spend plenty of time getting to know the entire administration interface on your own, and fine tune your configurations as you ultimately desire. Also, be sure to spend time with your administration panels after each upgrade too, as there are sometimes new features added that you’ll want to be aware of. In any case, you should get a little heads up in the Announcements area of the Forum when new releases are made. Such announcements will indicate what kinds of changes have been made and what features may be new.

The Building Block Panels

Without further delay…

Sections (and Pages and Styles)

Sections are created and managed in the Sections panel. At the top of the panel are the site section controls for creating new Sections. As new Sections are created, they are added to the Sections panel in alphabetical order, and each is provided with another series of customization controls. TextBook does a good job of describing all of these controls in detail, so I’ll leave you to reading more there.

I’m guessing most Textpattern users, myself included, tend to create their Sections first, and there’s nothing wrong with doing so. This is probably because from a conceptual standpoint Sections represent the structural foundation (albeit pseudo-structure) of our site, and it makes sense to lay the foundation first.

However, if your site’s blueprints call for a particular Section to use a Page or Style other than the defaults provided, then you must first create the custom Page and/or Style before you can assign it to a new Section. If you are a precision freak, that is to say someone who strives to do things in the most optimal manner possible, then you would not give into the urge to create your Sections first, but rather create your Pages and/or Styles first and then your Sections. I’m not a precision freak, so I always create my Sections first and then come back to them again later to reassign any new Pages and/or Styles as they become ready.

One more thing to note here. When you give your sections a name (label), make the labels as simple and relevant as possible. Since Sections essentially represent the main sections of your site, as reflected in your primary navigation and site URLs, it makes sense to use the same labels for your Section names too. Best rule of thumb is one-word labels, all lower-case. Lower-case is good because if you use clean URLs in your architecture, you might choose to use a format that shows Section labels, and it’s generally preferable to have all lowercase URLs for improved usability.

As an example of Section labeling, consider my primary navigation here at wion.com; at the time of this editing, there are five navigation options (about, journal, portfolio, archive, contact). In fact, each of these is an unique Section by the same name in the Sections panel of my admin interface. If you look at the URL for this article, you’ll see what appears to be a subdirectory called “journal;” that’s actually a Textpattern Section (not a folder) and the label is pulled directly from the Section’s title, which I can manage via the Sections panel.

Pages (Revisited)

Pages are created and managed in the Pages panel. The panel is composed of three columns. The left column is a very useful list of Tag building utilities. I’ll come back to these later when addressing Tags. The center column is the text edit area where you write your template code. And finally the right column is where a list of custom Pages will be made accessible as you create them.

At the bottom of the panel is a utility for copying a Page to create a new one. When you use this utility (and the same goes for Styles too in the next section), be aware that the new Page is added to the right side list but that you will still have the initial Page open in the text edit box. Don’t start editing the wrong Page by mistake.

With regard to naming Pages, this requires a bit of forward thinking. Remember I said that it’s always good to keep your architecture as refined as possible? Well one of the ways to do that is to create as few Page templates as needed, which means reusing Page templates as much as possible across different Sections — a one-to-many relationship from Pages to Sections.

This is also a good time to realize the value of good site blueprints, because they would tell you how different your templating needs would be from one to the other, and therefore give you a good idea about whether or not the one-to-many relationship will work for you. If your template layouts are different, you’ll have to go with a one-to-one relationship instead, which means a unique Page template for each Section.

One-to-one relationships mean more page maintenance, but they can be more intuitive and, in fact, are not a bad way to go if your site uses few Sections to begin with. If you do go with a one-to-one Page to Section association, give your Pages the same name as your Sections so it’s crystal clear what Page and Section belong to each other. This is the strategy I use, with the only difference being that I capitalize the first letter of the Page. For example, for all Section / Page associations it looks like…

• about / About
• journal / Journal
• contact / Contact
• etc.

Obviously this is not a good strategy if you use a one-to-many approach. In that case you want to choose Page names that are less specific, and that’s just going to depend on the needs of your site.

Styles (Revisited)

Styles are created and managed in the Style panel. The Style panel is much like the Page panel; three columns, with a text edit box in the middle, and a right column for custom Style files that you might create. The left column provides a couple of options for editing the CSS and uploading external style sheet files. Myself, I prefer to use the “raw” view for editing presentation rules (or use a different editing application entirely like Crimson Editor, and then paste in the modifications afterwards).

When discussing Sections earlier, I mentioned that I prefer to create Sections first, then my Pages and Styles, and then go back to Sections again and assign the latter two. For me, this usually just means assigning a Page only, because I almost always reuse the “default” Style (albeit customized), and since the default Style is automatically assigned to all newly created Sections, I don’t have to worry about it.

Categories

Categories are created and managed in the Categories panel, and can be created for four different Category classifications: articles, images, links, and files (or what I like to collectively call the four types of user consumable content).

An important thing to realize is that you can only assign any given consumable content type a maximum of two Categories. However, depending on the nature of your site blueprints (remember those important things?), you may be able to use article flow to your advantage to fake a kind of third (non-declared) Category function. The concept is a bit abstract, but the logic is there. You use the default page and article flow for an article list output of some type (e.g., like a news list), then you free up both of your actual allotment of two Categories for use elsewhere in the site.

In my first article on building blocks I talked about how you might use Categories for grouping articles by topic. That was the conceptual side of things. As far as mechanics go, there’s not much more than can be said about Categories without providing a code example of their use. Providing such an example is only as good as the context of the example to a real need, which might be better for a future article. Hence, I won’t be giving a code example now. However, reflect on the Tag building utilities when I talk about them after Forms, particularly the Tab builders for the Pages panel. You’ll see how easy it is to build the code for your various topic lists.

Forms

Forms are created and managed in the Forms panel under the primary “presentation” tab. The Forms panel is almost exactly like the Pages panel noted earlier: three columns, with the left being a list of Tag building utilities, the center being the text edit area, and the right being where the existing Forms are presented in an alphabetical list. The main difference is that to create a new Form you use the “Create new form” utility at the top of the right column, as opposed to the “Copy page” approach for making new Pages. There’s also a key difference in the way the Tag utilities look and function (between the Pages and Forms admin panels), but I’ll come back to that soon.

Forms Explained

Forms are very important for one main reason: they allow global editing to your site, which in turn substantially reduces site maintenance and upkeep. If you happen to know what server-side script includes are, then you should easily understand Forms, they serve the same function.

If the notion of script includes leaves you scratching your head, not to worry. Think of Forms as little containers holding discrete chunks of code, which in turn define different pieces of Web page content. Each Form has its own name (single words are best), which, for cognitive reasons, should reflect the nature—or purpose—of the code they contain.

For example, consider a static Web page and think about how it’s all put together; a header, a logo, a primary navigation list, and so forth. Each of these pieces of content are defined by specific sets of code, which includes XHTML (tags, selectors, classes, etc.), text (e.g., alt="" descriptions, link labels, etc.), and very often Textpattern Tags too. Mileage will vary from project-to-project, but if you package these sets of code into separate, custom Forms and give them clear names (e.g., Navigation, Footer, Logo, etc), instead of hard coding the content pieces directly into a Page template (never do this), then you have a series of content containers that can be reused at any time to dynamically assemble different Web page views across different Page templates.

Form Type and Function

Textpattern Forms exist in four types: article, comment, link, miscellaneous, and file. It is important that you designate the appropriate Form type to any new Forms you create because the type is logically tied to the Tag builders, which will only work if the Form associations are correct.

Basically, if you are creating a Form to be used for outputting articles or article lists, you’ll designate the Form as type article and then all of the article-related Tags can be used in these types of Forms. Similarly, if it’s a Form having to do with links you’ve managed in the Links panel, then designate type links. If it’s a Form having to do with uploaded files, designate type file. You would do the same for comments, but it’s unlikely you will ever need to create another comment-related Form (but who knows), just use the defaults and customize them if needed. Finally, the miscellaneous type is used when the Form outputs content that’s not classified by the other Form types; this might include navigation, logos, footers, metadata, and so forth.

To get a better picture of Forms, as well as understand the default Form options, it might be useful to look at the default Forms more closely. Details of Textpattern’s default Forms are presented in Table 1 below (in alphabetical order):

Table 1: Classification of Textpattern’s default Forms.

Name	Type	Intended Use
comments	comment	Defines the output of a user comment after it’s been written and posted.
comments_display	article	The name is a bit misleading. If comments are selected to be active for a given article, this Form indicates where the actual “comments_form” Form will be output and usable.
comment_form	comment	Defines the actual XHTML form that users will use to enter their comments to your articles.
default	article	Defines the default full-article output to the index page. Can be customized to your liking, but still only works for the index Page.
files	file	Defines output widgets that enable a user to download whole files from your site. You must have already uploaded files in the Files panel before using this Form.
links	link	Defines link output (such as your favorite Web sites). You must have already started a link collection in the Links panel before using this Form.
lofi°	article	I’m guessing “lofi” stands for low-fidelity, but this Form serves no role other than to confuse people. You can either change the dorky name and customize it to your liking, or, like me, just delete it altogether.
Noted°	link	Exactly the same as the “links” Form, and therefore dead weight. Delete it if you like.
plainlinks°	link	Defines the title of link descriptions (notice the special Tag used in this Form). I haven’t used this (or any of the link-related Forms, actually) so I’m not sure how to explain it. Let me know if you do.
popup_comments°	comment	Defines a popup window and output of your XHTML comment form. Textpattern uses this if you have configured your global comments to be revealed as popups instead of attached directly to articles. Not very popular based on what I see around.
search-results°	article	Defines search results output. You will certainly want to customize it.
Single°	article	Likely intended for full-article output or perhaps pseudo-static article output, certainly not article lists. Change the name and/or customize as you see fit.
° Indicates default Forms that can be deleted. (Don’t be hasty.)

Customizing Forms

As you become comfortable with Forms, you’ll begin to see how to create very powerful Forms having advanced combinations of Textpattern Tags like conditional Tags. The output of these Forms can do some really cool things for you in your content presentation. Learning how to create such advanced Forms requires a little patience, a reasonable understanding of Textpattern Tags, and a bit of time hanging out in the helpful Textpattern community for help.

Tags

At long last, here we are at Tags, the golden nuggets of Textpattern. As I have already touched upon, Tags are the one building block that do not have an admin panel of their own, but rather exist as Tag building utilities in the left columns of the Pages and Forms panels. These are the two locations where you need to work with Tags so it makes sense to have the admin panels structured this way.

You might be thinking, ‘but what about the Write panel, can I add Tags in articles when writing them?’ According to the Textpattern FAQ, Can I use txp tags in articles?, you can add “some” Tags directly into an article, but specifically not the <txp:article /> or <txp:article_custom /> Tags. As for what Tags you can add, you apparently have to explore that on your own, assuming you had reason to. In any case, Tags are generally added to only Pages and Forms, which is why the Tag utilities are available in those two panels.

There is a slight difference in the way the Tag utilities function between the Page and Form panels.

Tag Builders in the Pages Admin Panel

Figure 1 shows an example of the appearance and function of the Tag utilities for the Pages admin panel.

The center of Figure 1 is the list of “Useful tags” as it actually appears in the panel (the panel’s left column). One thing to note about the structure of the list, the _links are subsectioned by the purpose or function that a given Tag serves. As indicated in the Figure 1, when links in this list are clicked, Tag builder pop-ups appear having a number of controls specific to the Tag you select. In this case, Figure 1 shows the popup builders for the two “articles” links.

As you can see from Figure 1, there are a lot more options for creating custom article list outputs than there are for just stock article outputs. In all cases, it should be easy to understand what the controls are for; however, it’s worth pointing out one thing about the “Form” and “List form” dropdowns in the Tag building controls (note the exclamation mark signs in Figure 1). Each of these dropdowns are identical and basically reflect a complete list of all existing Forms you have.

The “Form” and “List form” dropdowns do not distinguish between Form types, you have to pay attention and make sure you are selecting the proper Forms when building your Tags. This requires attention at two levels. To understand, consider Figure 1 again, specifically the two different Tag building popups. First, you want to make sure you are only selecting Forms of type article (remember you set a Form’s type in the Forms panel). Second, you want to make sure the article Forms you are selecting are the right ones for either full article output or article list output. As you can see from the Tag builder popups in Figure 1, there is a difference, and it will influence how a given Tag will be built.

Tag Builders in the Forms Admin Panel

The Tag building utilities in the Forms admin panel are presented a bit differently than in the Pages panel, and for the most part they function a bit more simply. Figure 2 below shows the top portion of the “Useful Tags” list as it appears in the Forms panel, as well as the three representative popup Tag builders that function for this list.

The three Tags shown in the image are arbitrary, they were only selected to show the associated Tag builder. In the case of the “Article image” link, the Tag builder is nothing more than a text box that provides the Tag syntax for you to copy. The idea being you would then past the copied syntax into a given Form that you were working on. If you spent a minute clicking all the links in the list, you would find that most of the associated Tag builders are this type.

The “Category 1” (and 2) link first asks you a yes or no question. Once selected in the dropdown box, you click the “Build Tag” button and the Tag is again supplied in a text box for you to copy. The yes/no function appears as an attribute in the Tag, like this: <txp:category1 link="y" /> (or link="n").

The third and final Tag builder is really the same as the first, but I thought I would add it to show that it works for container Tags as well. With this “Permanent link” example, you would simply replace the “text or tag here” part with whatever you really wanted to appear there as output. In this case the output would be a link to the given article’s location in the database.

Tag Resources: Where to Learn

Hands down, the best place for referencing Textpattern Tags are the resources available in TextBook, including the Alphabetical Tag Listing and the Attributes Cross Reference, which is a complete list of the various Textpattern Tag attributes. Each attribute on that page is associated with the specific Tags it functions with. The Tags themselves link to their own respective wiki pages where you can learn more about a given Tag and find examples of its use.

Before TextBook’s Tag references became the shizzle, there was Pedro “kusor“ Palazon’s Textpattern Tags: A Manual for Impatient Users. However, I would caution that this manual has not been updated since March 2004, and there has been a number of new Tags, and Tag changes, since then. Your best bet is TextBook. Nevertheless, Pedro’s manual is still useful for thinking about Tags in context of use.

Wrapping Up

And there it is, the whirlwind tour of Textpattern building block mechanics (well, maybe not so whirlwind). Between this article and the first in the series, Understanding Textpattern Building Blocks, you now have more insight to getting started with Textpattern than most newcomers prior to 29 May 2006. The only thing you need to do now is get your site blueprints in order, assemble the main components of your site, and follow up with the many resources I have sprinkled throughout both articles. With a little time and fiddling, you’ll be experiencing the joys of Textpattern like so many others do.

1. Maniquí :: 30 May 06 :: #

   Destry, thanks for sharing your knowledge!

   A bit long, but plenty of useful information, tips, tricks and links. I will have to re-read (re-read is always better than read) it to grasp all the ideas, specially those about blueprints… I usually find myself trying to develope without a plan, or a mock-up… i’m a disaster!

   I haven’t develope too many sites yet (with or without TXP) but I find that the reuse of chunks (Forms) in TXP makes the work easier and faster.
   TXP is a framework itself:
   Even if I have to develope a totally static and low-quantity-content site, I will do it with TXP, if possible.

   And regarding to reuse, the use of conditional tags makes TXP chunks even more reusable.
   But my experience says that there is no need to abuse of reuse and conditionals tags.
   I have also dreamed about one default form to rule them all, but with the time, I have found that in some cases is better to have, for example, two different article forms than one form and doing conditional-acrobatics…

   That speaks about TXP flexibility. If you want, you can use conditionals; if not, you can have more hard-coded stuff.
   Even you can have a totally HTML hard-coded site running in TXP without even a built-in TXP tag at all!

   Also, I have found that each one developes inside this TXP in the way they feel more comfortable. This is not a one-way, nor a two-way street, there are multiple paths to reach the same or different places.
   There are people that like minimal use of plug-ins and tags, there are others that love plug-ins and conditionals and who experiment with very complex forms.

   I have changed my txp-ninja-way several times, just to learn more and more about it.
   Also, trial and error is hard and frustrating, but it gives the better tips, and a nice zensation of learning. I’m trying to reach an equilibrium of performance, maintenance, flexibility, etc.

   Going back to reuse and conditionals tags, another aspect to have in mind is the performance.
   I have no patience for doing benchmarking, but as we can read at this FAQs about performance, very complex forms and page templates can lead to performance problem.
   It would be cool to have someone doing some benchmarking with TXP.
   I wanted to open a thread about improving performance in TXP, but havent done it yet.

   BTW, you were the one with some difficult to make your head around condtional tags, weren’t you? ;)

2. Destry :: 30 May 06 :: #

   Sorry for my small comments box, Maniqui. ;)

   Seriously though, you are right all all counts. This particulur article should have been two, and all those other considerations you bring up are certainly relevant.

   This series was meant for folks new to Textpattern, and it was meant only to put people on a solid path to further explore on their own, however they want. Any other Textpattern articles that come out of me at this point will be more focused, and yes, shorter.

   Difficulty with getting my head around conditional Tags? Oh yeah, that was—and in some respects still is—me.

3. David Knowles :: 16 June 06 :: #

   I wanted to thank you for taking the time to write this article. It really helped to give me the helicopter of view of how things happen in TXP.

   Someone commented that is was too long. I totally disagree. It was very thorough, and i found necessary, covering things others have left out.

   One small but VERY important thing you mentioned because of your thoroughness was your comments on textbook, i.e. It’s not finished and contains pages and pages of topic that have yet to be written. This was very helpful to me. I am also just starting and couldn’t understand what i was doing wrong. Everyone was raving about textbook, but couldn’t locate the promised articles. Very frustrating. The getting started pages of Textbook are of course some of the most important for beginners and these are exactly the one’s that have in many cases yet to be written.

   Well anyway thanks again you really helped me. I look forward to more of you very complete articles

4. Destry :: 16 June 06 :: #

   Thanks David,

   You hit it right on the head. Back nearly two years ago when I first came to Txp, I found the available material often assuming a certain level of knowledge on the reader before they even began. That’s just not good writing, not good technical writing, anyway. I go back and forth with the length of my writing, but in these two articles I really felt is was prudent to cover the bases thoroughly, establish a foundation. Future articles can now be more focused on individual topics. The whole idea for my writing here is that concepts build upon one another, not come across as pot-shots at this random topic or that one. Not that random topics are bad, but learning is more established if topics are introduced in a progressive order of importance. And yes, don’t leave out the small details. ;)

Latest Ten Articles

• Finally Pro-MacBooked 6 April 07

  Six months later than expected, and on the eve of the new Apple Leopards, I am nevertheless a happy owner of the MacBook Pro, and it feels good.

• What Makes a Good Web Accessibility Guide for the Business? 2 April 07

  With pressure mounting on web developers and companies alike to provide quality eAccessibility products and services, it makes good business sense for companies to have their own eAccessibility guidelines to help ensure development objectives are being met in efficient and cost-effective ways. However, just knowing guidelines are needed is one thing, producing and integrating them into a development workflow is something else. What breadth and depth of information should they cover? How should they be written and structured for maximum understanding? What format provides the best utility? Seemingly, the preparation of eAccessibility guidelines is not a fundamental task, the considerations are many.

• Main Points Delivered at the First European eAccessibility Forum14 March 07

  I’m not exactly punctual on this one, but making a long story short, here are the main points as I took them from the eAccessibility Forum held in Paris nearly 6 weeks ago…already.

• In Paris for the First European eAccessibility Forum27 January 07

  It’s going to be a whirlwind trip on the train, but should be interesting nonetheless.

• Lose Readers by Moving Themes?14 January 07

  We hear about free Weblog themes all the time, and see the same ones all over the Web, but it’s not often you read about someone moving a personal theme from one self-owned domain to another, or the implications of doing so.

• Book Reviews Coming to Wion18 November 06

  Reading and writing is my kind of chocolate, and when it comes to book reviews, everybody wins. I hope you’ll find them helpful. Stay tuned.

• A Core Textpattern Technique Addressing Internationalization Interests14 November 06

  This article presents a core Txp technique for managing internationalization efforts, and three methods of use are described: 1) multilingual publishing within site, 2) collaborative international publishing between individuals, and 3) an alternate approach to #2 that essentially takes a community slant.

• Textpattern Building Block Mechanics30 May 06

  Here is the second article in a two-article series about Textpattern building blocks. If you missed the first article, Understanding Textpattern Building Blocks, you might check it out too.

• Heatmap Presentation of Eye-tracking Data17 May 06

  Isotopic heatmaps of eye-tracking sessions are easier too see and understand; hence, great slide material for stakeholder presentations (management, clients, and so forth).

• IE Conditional Comments: Where Have They Been?19 April 06

  Conditional comments have been with us for years and largely unknown, but with the coming of IE 7 they may be the swan song that’s about to go platinum.