Understanding Textpattern Building Blocks

6 January 06

A contextual introduction to Textpattern components as they are used in Web site structure and organization.

Overview

After following Textpattern for over a year, using it for my own sites as well as clients, and being an active participant in the Textpattern community, I’ve given a lot of thought to describing its basic components in such a way to help newcomers to this system get started a little easier. Others have approached this topic under the heading of semantics or presentational model, but what it really comes down to is using a core set of Textpattern building blocks to build a site.

Audience Note: By no means is Textpattern perfect for everyone. If you don’t know at least a little about running a Web site (server and databases), HTML markup, CSS styling, or have a Web designer lined up to take care of it all for you, then this article will likely not make things immediately easier. On the other hand, by reading this article you might understand a bit better as to whether or not you want to tackle Textpattern to begin with.

Other articles, with varying success, will first describe and classify these building blocks as they are presented in the interface of the system itself, and then try and tell you how to use them. That might be the most direct approach, but arguably not the best. What these other articles lack is a focused storyline that provides a conceptual foundation by which readers can associate the building blocks as they are used in a real world context.

Hence, I’m going to approach the topic from a different direction (albeit more elaborative), and do so by writing two companion articles. The first article, this article, provides the conceptual foundation I think is generally missing when people write about Textpattern components. The second article will essentially be my version of the building block mechanics, which I’ll largely parallel with the Admin-side pages in TextBook. I believe by going this direction I’ll equip readers with a fuller set of Textpattern blue prints rather than a jigsaw puzzle to piece together on their own.

The Textpattern building blocks I’m talking about, and will be covering more in the course of both articles are:

  • Sections
  • Pages
  • Forms
  • Tags
  • Styles
  • Categories

Note: From hereon, when a building block is introduced in this article for the first time, I will use the convention of making the label capitalized, italic, and bold (e.g., Sections), and thereafter simply capitalized and italic (e.g., Sections). This will help to distinguish when conversation is about a given building block or about a similar term typically used in general Web site design discussion.

The Big Picture (The Missing Link)

One thing that writers about Textpattern seem to take for granted is that readers fully understand the concept of dynamic publishing. I’ve found from spending time in the Textpattern Forum this is not always the case, and could be one reason why some people find Textpattern difficult at first. Hence, here is what I specifically aim to do in this article: First I want to bring a few points to light about dynamic publishing in general, then blend that with notions of Web site structure and organization as Web users have generally come to understand them. At the same time, for clear association, I’ll begin peppering dialogue with reference to the building blocks as they will apply in each case.

By the end, a reader new to Textpattern should have an understanding of how the building blocks are associated with particular facets of site structure and content organization (as the case may be). In turn, this should make it easier to create and utilize these building blocks when working in Textpattern’s site administration interface, which will be the focus of the forthcoming companion article, Textpattern Building Block Mechanics.

Update: The second article of this series, Textpattern Building Block Mechanics, is now available.

Static Versus Dynamic Web Sites: A Primer

Most people understand Web sites, particularly the structure and organization of Web sites, as reflected by a static Web site: a site that is constructed of hard-coded HTML (HTML, XHTML, etc.) files that are organized into folders and stored on a Web server. Such sites are referred to as “static” because the text and image content a site visitor consumes is embedded in the HTML page, which itself is fixed in place on the Web server. Nothing moves. When a site visitor navigates a static Web site, the content is not coming to them, they are, in essence, physically moving from file to file on the Web server by way of hyperlinks. This is a traditional model of Web site design, but it has one major drawback from a site owners’ point of view: updating content is enormously time-intensive and far more complicated than it could otherwise be.

By contrast, a dynamic site is considerably easier to maintain. A “dynamic” Web site refers to one that involves a database backend, and where all content — whether text, images, or otherwise — is stored in the database and called upon when needed. This calling, as it were, is the act of a site visitor clicking through links, and as each link is clicked, a dynamic process instantaneously takes place whereby various pieces of content are pulled from the database and assembled on the fly in the visitor’s Web browser, giving the visitor the impression that she is physically moving from one page to another, when in fact she is not.

Making content available in this manner is known as dynamic content publishing, and the core set of scripting files that handle most of the dynamic processes are packaged up and distributed (whether free or at cost) as content publishing systems (like Textpattern). Some of these systems are even quite robust and are classified as full-on content management systems.

Although there are a lot of similarities from one system to another, no two are exactly the same (which is nice). The objectives of a particular Web site (among other things) will likely dictate what system a designer opts to use. Textpattern stands out from most publishing systems for many reasons that are out of scope here, but the bottom line is it’s a very lightweight yet powerful and flexible system that provides designers with the ability to create custom Web publishing solutions by way of a core set of system building blocks — the focus of this article.

Note: There are many in the Textpattern community that are quick to call Textpattern a content management system (CMS). Although I think Textpattern is much more than just a Weblog system, and offers a considerably more elegant and flexible means of managing a site (hence why I say content publishing system), I wouldn’t go so far as to call it a CMS. A CMS is traditionally more robust, providing more control over the depth of site construction and content rights management, as would be necessary for a large company site having many departments and contributors. However, Textpattern is no slouch; its lean and powerful, and can produce some amazing Web products with the right skills and imagination.

Textpattern and General Site Structure

The two most elemental aspects of basic site structure as it could apply to any Web site (whether static or dynamic) are:

  1. organization of site content
  2. links between content locations

The link part is simple to grasp, so we’ll just focus on organization. Content organization implies how your content is organized physically and topically. It should be easy to see where the folder and file system of a static site is inherently physical.

With a dynamic system like Textpattern, the concept of physical organization is a bit more abstract. In this case, content is stored in a database rather than a fixed folder tree, so what a designer must do is assemble Textpattern’s building blocks in such a way as to give the site visitor a sense that a physical structure really exists; a kind of pseudo-structure, if you will. This sense of structure is what is reflected in a site’s primary navigation, in a given URL, and so forth.

The topical organization is less complicated because one is simply grouping information by context of subject matter, and as you will see later, this is largely achieved by the two functional building blocks, Sections and Categories. Hence, if a designer creates the pseudo-structure with respect to subject matter, he or she will go a long way to establishing a semantically strong information architecture in a Textpattern site.

The Home Page

Fundamentally speaking, we recognize Web sites to first consist of a starting point, the home page, which from a URL standpoint is typically the domain root. Behind the scenes of a static site, a visitor would be looking at a single HTML file (index.html), and all the content the visitor sees is hard-coded in the file. When following a link, the visitor physically leaves the index.html file and lands upon another elsewhere in the server file tree.

When a visitor arrives to a Textpattern site, they would also alight upon a single file, but unlike in a static site, this file is the only file the visitor will ever move to; i.e., they won’t ever move at all. Instead of an HTML file, Textpattern uses a PHP file (index.php), in which no content is hard coded but rather dynamically inserted after being called from the database by way of PHP scripts and special Textpattern markup called Tags. Tags are one of our building blocks, and a kind of content to be managed in Textpattern. I’ll address them more closely later.

As noted earlier, when a visitor clicks links in the interface of a Textpattern site, the content dynamically changes in the index.php file to reflect what the visitor should see at the link’s assumed destination. The result of this from the visitor’s standpoint is the impression of physically moving through the site, when what’s really happening is content shuffling in and out of one place as links are clicked. Only the content that differs from one link view to another is what changes in the view.

Note: It is typical that people generally think of content to refer to the text on a given page; this is correct, but it’s not the full scope. In addition to text, content includes images, pieces of code (such as a PHP script, a block of HTML markup, or a Textpattern tag), or in some cases even entire pages themselves. This broader notion of content is necessary with Textpattern, because it is these various sorts of content that are dynamically managed (even the CSS styling), and which subsequently provides all the pieces of a Web page that a visitor will see and interact with.

First-Level Structure (Pseudo-Structure)

Users know that from the home page they will be offered options for exploration, and these options are generally reflected in the site’s primary navigation links. Conceptually speaking, primary links go to top-level locations in a site, which for all intended purposes provides lateral site structure; in essence, the division of a site into different regions, or sections. Web users have come to understand the sections of a Web site to include such things as About, Services, Products, Gallery, Journal (Weblog), Contact, and so forth.

Again, in a static site, each of these site sections (subject sections, really) would be represented as a folder on the server in which more hard-coded HTML files would be stored, and one of the files within each folder would be the one pointed to from the primary navigation by default.

With Textpattern, these top-level locations are not folders at all (no folders really exist), but rather appear to be folders by use of another building block called Sections. A URL in Textpattern that reflects an “about” section would look like this when viewed in the address bar of a Web browser: http://www.domain.tld/about. In actuality, there would be an article appearing at this link destination that provides the About text, but whether the article’s title shows in the link path or not is up to how the designer chooses to reveal URLs in a given primary navigation scheme; i.e., one may want the article title to show, another may not. In the case of primary navigation, it is usually best to not reveal the default article title, which gives a stronger impression that lateral site structure really exists.

Note: The notion of how URL links appear in a Textpattern site starts getting into the topic of messy versus clean URLs, which is a larger topic in itself that this article does not pursue. I recommend you review the Preferences pages in TextBook, beginning with Basic Preferences, to begin your exploration of understanding URL options with Textpattern.

A Given Web Page

I’ve already described the underlying index.php file as the main view at which all the dynamic action takes place, and that content pieces of all types, which are stored in the database, are shuffled in and out of the main view as a visitor clicks available links. I’ve also pointed out that Textpattern uses Sections to establish the impression of there being other locations to visit besides the home page. What we need to do now (and in the next section of this article) is bridge the two concepts together a bit better by going over the assembly process of a given page view, the relevant content components involved, and where the components come from.

On the surface of a normal HTML page, we generally expect to see some common elements: header, navigation bar, left and/or right column, main content area, footer, and so forth. Within these various layout elements, we can expect to see discrete content pieces like lists, articles, images, links, etc. Again, in a static site all of these things are hard-coded in a given HTML file; but in a Textpattern site, all of these things are dynamically managed, and since this is the Web after all, it starts with an HTML framework.

This framework is another Textpattern building block called a Page, and as you would expect, the Page is a properly structured HTML file. But since we’re talking about Textpattern, there are two main differences to understand: First, the Page is not a file on the server, it’s stored in the database and dynamically called just like any other piece of content. Second, the Page is only a template — a shell — it’s devoid of content itself, but rather simply provides the nesecessary HTML structure in which other content pieces will be included. The designer needs to give instructions to Textpattern about how to add content to it, and of what type.

Note: The label, Page, at first seems like the right name to give this component, but in actuality it seems to trip newcomers up; they tend to think of a “page” as it would suggest a static Web page (full of content) from the viewpoint of a visitor looking at it in a Web browser; but what we are really talking about here is a template stored in a database (and thus a piece of content like anything else). “Template” is probably a better label for Textpattern Pages, because it more successfully suggests an HTML shell; hence, it might be less confusing for you to think of them in that way. If you spend any time in the Textpattern Support Forum, you’ll see people referring to Pages as “templates” quite frequently.

In the very beginning of this article I mentioned that out of our six building blocks, Sections (together with Categories) serve more of a functional role, while Pages are one of the four serving as content. Sections and Pages work together to achieve the overall effect of perceived lateral structure; you define the Section for establishing the location itself, while the Page is the content framework you assign to the Section, which in turn provides the necessary hooks, if you will, to hang other pieces of content (headers, lists, articles, images, etc.) on. I’ll get to the mechanics of this association in the second article.

Content Components

I have intentially been overlapping concepts in this article so they are reaffirmed as you follow along. By now you should really understand what is meant by discrete content pieces; however, we need to poke at these content pieces a little closer so you see where they come from, and that brings us back to Textpattern Tags, as well as introducing Forms. As indicated before, Tags and Forms are types of content to be included in a Page template, and they are very powerful.

Note: Forms are another building block having a name that can be confusing. Web users, even designers, generally think of the term “form” to mean those Web page elements composed of various controls (text boxes, radio buttons, dropdown lists, etc.) where users type or select information and then submit it somewhere for processing. A Textpattern Form is not the same thing at all; it’s more of a code recipe — a discrete block or snippet of code — that a designer creates. Hence, while it is possible to create a Textpattern Form that outputs a typical Web form as described, a Textpattern Form and a Web form are not synonymous.

If you think of it in terms of hierarchy or size, Forms are one level above Tags, that is to say you can put Tags into a Form. Forms are essentially blocks or snippets of code that you create as discrete packages and give a name to. The code itself defines other types of content to be included in a Page (e.g., navigation list, footer, Web form, etc.). Forms are composed of standard XHTML and Textpattern Tags, and may define anything that can be rendered in a Web browser.

Tags are the most fundamental building block in Textpattern, and fall into three different groups: Page Tags, Form Tags, and Conditional Tags. There are many tags in each classification group, with each Tag having an unique use. In general, Textpattern Tags serve two primary functions. The most basic function is to designate what kinds of content should be pulled from the database and where is should be added to a Page template; Page Tags and Form Tags largely fall into this area, and as the group labels should suggest, Page Tags are used in Page templates themselves, while Form Tags are used in Forms. Another function of Tags is to tell Textpattern how to process content output under varying conditions, and this is the role of Conditional Tags, which can be used in both Pages and Forms.

Sometimes, but not always, there will be different ways to achieve how content is processed or displayed with Forms and Tags, but in most cases there is a good way and a not-so-good way to go about it. The manner in which these building blocks will be used should be dictated by the best approach for achieving a particular effect, which itself is a factor of how well the utilization of these building blocks, especially Tags, is forward compatible with future Textpattern releases. The main thing to keep in mind, particularly with Tags, is to use them as they are intended by the developers; if you do, you’ll be in good shape.

Tags are powerful, some more than others (like the Conditional Tags), but getting to know them and the full range of their capabilities will take time and experimentation on the designer’s behalf. Even world-renowned Web designers (which I’m not) discover new ways of using Tags to achieve various effects; hence, I certainly won’t be giving more than a cursory introduction to Tags in this article.

Note: There are three primary channels you should follow to keep abreast of how Textpattern works, whether about Tags or anything else: the Textpattern Support Forum, the Textpattern FAQ, and TextBook. More than anywhere else, these are the authorities on how Textpattern functions.

The Esthetic Layer

The esthetic layer is of course the pretty face for yor Web view, and most people should realize that what we are talking about here is the CSS rules that define color, element positioning, content behaviors, font appearance, and a whole lot more. In Textpattern, CSS files are logically called Styles, and are another one of our building block components. As with most everything else, Styles are stored in the database, and therefore managed just like any other piece of site content.

It’s not a stretch to realize that Styles will be applied to Pages and all their incorporated content from Forms and Tags so there’s not much more that needs said about Styles at this point, but I’ll come back to them again in the second article, and provide some additional considerations.

Topical Organization

I’ve alluded to the fact that content organization is both physical and topical, and and I’ve been addressing the sense of physical organization most of the way, namely our pseudo-structure and how it comes about from a combination of Sections and Pages. Furthermore, I’ve detailed how a given Web page view is composed of dynamcially assembled content components that are largely constructed of Forms and Tags, but which are made pretty with our esthetic content item, Styles. I also mentioned very early on that in addition to Sections there is another building block, Categories, that serves more of a functional role rather than being a type of content, and that (like Sections) helps establish how your other content is organized. Categories are significant so I’ll talk about them in a bit of detail.

A big difference between Sections and Categories is that Sections deal more with the pseudo-structure I have mentioned while Categories are more concerned with grouping links, text articles, and images that you manually write or upload. In this section I’ll address Categories with respect to articles, but keep in mind the principles and practice are exactly the same for the other formal content types you might publish.

Categories are nothing more than a very convenient way of keeping articles (etc.) of a similar subject matter together in one place; that’s really all there is to it. For example, if in a three-month time period you write and publish 15 articles in your Web site, and 7 have to do with gardening while the remaining 8 deal with books, you would logically create two Categories (one for gardening and one for books). Furthermore, it would be sensible to give the two Categories labels that were strongly relevant to the subject matter; hence, the labels “gardening” and “books” would be good candidates.

In actuality, you might write about a greater variety of topics, and therefore would need a greater number of Categories to group the articles you write accordingly. You can even assign an article to more than one Category (up to two), which gives you the ability to display a given article in different page views, or in hierarchical fashion by topic.

The question to pose for understanding is, why would you need to group articles? The answer is quite clear once you consider the pseudo-structure you will come to create, which in turn is reflective of the kind of Web site you need to construct (a personal Weblog, a business site, a photo gallery, etc.). Following is one possible scenario.

Let’s say a designer needs to create a site for a catering company, and the site owner wants a Menus section to include articles for several menu types, which might include the following three: brunch menus, dinner menus, and banquet menus. The first Category the designer might create is easy to see, and it logically comes from the Section itself, namely, “Menus”. The Menus section is the common section that all menu articles will be assigned to; however, to give the Category some semantical distinction, the designer could label it as “catMenu”. It would now be possible, by appropriate use of Forms and Tags, for the designer to arrange it so that when an author drafts such an article and assigns it to the “catMenus” Category, it automatically gets displayed in the Menus section when published.

However, although we have grouped all menu-related articles together with the “catMenu” Category, there is still a subtopical division that the designer may want to control, namely the three different menu types themselves; hence, the designer might also create three additional Categories: “catBrunch”, “catDinner”, and “catBanquet”. The designer could then use this second level of categorization (again with the help of Forms and Tags) to create different displays of all menu types in the Menus section of the Web site; perhaps as vertical lists, or as different visible displays as a visitor clicks particular links to call one topic or another.

The example above is just one scenario out of a great many a designer might have need for, but no matter what the scenario may be, the principles of using Textpattern Categories is the same.

Note: This is jumping ahead a bit, but there’s another very important thing to keep in mind as you come to understand relationships between the articles you publish in a site and the Sections and Categories you associate them with. Any article you write must be associated to one and only one Section in Textpattern, this association is largely tied to the body element of the article. In contrast, you can display the title and/or excerpt (the other two elements of an article) in other Sections of your site by way of lists that are in turn associated to topic Categories. Hence, you can display the title and/or excerpt of a given article in multiple places throughout your site, but when any link of such a displayed article title is clicked, the full article (the article body) will be displayed in the Section it is associated with. It’s all about making your articles accessible from multiple locations, and a good example is a typical “Archive” section having many article lists, each being displayed by way of a unique Category.

That wraps up this first article, which is essentially my take on introducing you to Textpattern’s basic components and how they come into play with site design.

Let me know if you find this article helpful.

Update: The second article of this series is now available, see Textpattern Building Block Mechanics

  1. Destry  ·   8 January 06

    I have made a few edits to the article, largely based on Andreas’ very helpful feedback.

  2. Dan  ·  15 January 06

    Helpful article. Thanks! I am totally new to textpattern and while I understand the concepts it would be enormously helpful to see a step by step example of creating a “typical” 4-5 page site.

    I’ve had the same struggles with Drupal, which seems like a powerful system too.

  3. Destry  ·  15 January 06

    Hi Dan. I hear you, and you’re not alone. This article is really for that percentage of users who are coming to TxP for the first time and perhaps are even new to the idea of dynamic publishing. The main intention here is to step back a few paces and put down the carpet, as it were, on which to arrange the furniture. As I write more, things will get a little deeper; a little more particular.

    However, I don’t know if you’re ever going to see a single article on building a Textpattern Web site; I’m not sure that’s very practical, even for a “typical” one. If you really think about it, that’s a very complex writing activity to tackle, and frankly, most people just aren’t that good of writers, and the people that are just don’t have the time.

    In any case, I think the documentation is coming, slowly, but what newcomers to TxP should expect to do is find the various pieces of writing that cover a particular facet of site construction, and put those articles together on their own. A lot of these such articles are out there, and hopefully will get captured more and more in TextBook. That’s the direction I’m trying to support, anyway.