Go to content
pfactor site logo Picture of Mooney in flight (top logo)

RSS Feed


Porting To Textpattern

posted Dec 27, 2005

It’s time to take the plunge and start using a real content mangement system. It’s not an easy decision to make. The website is working well, and I know how it’s put together. The CSS is set, and the layout is nice with no tables even. My homegrown PHP navigation system does a nice job of showing the hierarchial organization, and I’ve done a pretty good job of separating content from presentation using PHP.

But the bottom line is that I’ve been hand-editing my HTML and manually managing my website content for too long now. I don’t update the site as much as I’d like to, partly because it’s a hassle to add new content. From what I’ve read and seen about Textpattern, I think it’s just what I’m looking for.

Exploring Content Management Systems

A good place to explore the open source CMS options is OpenSourceCMS which has live demos of all the major open source CMS packages. This allows you to try them out (including administration) before actually installing. Although all the packages are free, your time in actually installing and configuring a system is not free. OpenSourceCMS provides a great service by letting you explore some options by just dipping your toe in the water a little bit.

I have not done an exhaustive survey of all the CMS options out there, but textpattern has several things going for it that I like:

  • Open-source, with an active user community
  • Simple enough to be secure
  • Apache, PHP and MySql is all that’s needed
  • Functional yet simple markup language: textile.
  • Enough flexibility to let me keep my existing site layout if I want to (but I’m probably going to use this porting as a chance to spruce some things up).

Installing Textpattern

Clearly the first step is to get this thing installed and start playing with it. The installation instructions and wizard-like installation screens were great!

I first installed it on my home Linux machine since I already had Apache and PHP running, and it was quite easy to get MySql server installed and working (thanks to the excellent MySql Documentation). I had my first “Hello World” posting running on my local machine in less than an hour.

Installing Textpattern on my external web hosting service was even easier than at home. At home, I had to tweak a few Apache config settings and do some MySql housekeeping before really getting running. On my hosting service, all this was already done and Textpattern is currently installed in a subdirectory at pfactor.com.

Ok it’s installed. Now what?

The reference materials for learning Textpattern are pretty good, but somewhat intimidating for a newbie. After the nice detailed installation instructions in the online manual for Textpattern, I was expecting an equally well-written tutorial on where to go after installing. There’s a nicely titled link that says How Do I… Starters, which is pretty much what I was hoping for. As I’m writing this on 27 Dec 2005, that page of the wiki is blank.

I did some googling and found two tutorials:

  1. Douglas Edmunds’ tutorial on the Textpattern presentation model
  2. Mark Norton’s Textpattern 101 which sounded very promising. Unfortunately, it looks like Mark’s site went down recently, but there’s a note promising that it will be back up soon.

Fortunately I was able to learn a lot between the Douglas Edmunds tutorial, the Textpattern online manual, and the Textpattern forum which has several helpful posters who respond.

I also stumbled across a few other sites that either had useful information about Textpattern, or were simply interesting examples of what could be done with it.

The First Pass

After a few hours of reading and experimenting, I’ve got a very basic understanding of Textpattern. Time to start learning by doing. I’ll work on getting the basic look-and-feel of my existing site running in Textpattern. Initially I’m trying to minimize changes to the defaults so I can easily undo whatever I break.

Here’s a summary of what I did during this first pass, and if you really want to see the details, you can download copies of the modified page file pf-default-pg.txp and stylesheet pf-default.css.

  • Admin > Preferences
    • Set timezone, although I had to make it GMT -7, daylight savings “no” to get the right time. I would have expected that yes/no to mean whether my area observes daylight savings time, not whether it is currently in effect.
    • Changed date format to Day Mon DD,HH:MM am
    • Changed permanent link mode to /section/title
  • Presentation > Pages
    • Copied original “default” template to “pf-default-pg” and modified as follows:
    • Changes from original “default” template
      • Created new “topbar” div. Added my site logo, section navigation and search there.
      • Removed div id="head" which had the site name and slogan
      • Removed left and right sidebars
      • Added copyright notice to footer, with PHP-generated ending year
      • Did some minor indenting to make it easier to read
  • Presentation > Styles
    • Added entries to style the new ”#topbar” div that I created.
    • Removed all the width entries from the ”#container” id
    • Changed the ”#content” entry quite a bit.
      • Changed the left/right margins from 155px to 15px
      • Added tags for 10px of padding-top, padding-bottom, padding-left, and padding-right.
      • Set background to #fff
    • Removed the border-bottom from the a element, changed link color to dark blue.
    • Changed h1 size from 3em to 2em
  • Presentation > Sections
    • Deleted the old sections and created: about, articles, links, and trip journals.
    • Made all sections use the new pf-default-pg page and the pf-default style.
  • Content > Images
    • Uploaded my site logo. I could only access it as /images/2.png from within a textpattern page. I was expecting to be able to use the name I uploaded it with (pfactor-logo.png).

Starting the Porting

After the first pass of doing that basic site setup, I decided to bring my About page over. That seemed like the easiest place to start since it’s just one static page, and there’s an FAQ entry on static pages that clearly states how to do this.

I created a new page called “PF-about-page” with this very simple content:

<txp:output_form form="pf-header" />

<div id="content"> <txp:article limit="1" status="sticky" form="static-article" /> </div> <!-- content --> <txp:output_form form="pf-footer" />

Oh, and part of the reason the content is so small is that I pulled out all the boilerplate code at the top and bottom into two new forms I created called pf-header and pf-footer. These forms just contain the boilerplate Texpattern and HTML code I use at the top and bottom of each page.

Since there wasn’t much on the original About page, it was pretty easy to just convert the existing HTML to Textile. I actually could have just left it as HTML, but that wouldn’t make it as easy to edit this page in the future. Part of why I’m switching to Textpattern is to get away from doing so much raw HTML editing.

I found this thread on converting HTML to Textile which included links to some PHP code to do it. I ran that code against my original About page’s HTML version and it worked pretty well. After that, I began the process of walking through all the content and converting the HTML to Textile.

The basic process I used was

  1. Upload the images and thumbnails for the page into Textpattern
  2. Run PHP script to convert HTML to Textile
  3. Manually fix up the references to images to match how Textpattern stored the images (change filename paths to image identifiers).
  4. Manually fix up any hardcoded internal links that would no longer work with Textpattern (e.g. when one internal page linked to another internal page) because all the URLs have changed.
  5. For simple tables, I manually converted the tedious HTML table code into the much simpler Textile table format. For complex tables, I generally left them alone and the HTML table code worked as-is.

Step #3 above (fixing up the image references) was getting pretty tedious. On my original website, I was using a handy PHP script I wrote to deal with images for me. My script would handle making links between thumbnails and larger images, do proportional scaling if needed and a few other useful things. Textpattern allows you to make PHP calls directly from your article content if needed, but that seemed to go against the reason for me moving to Textpattern in the first place. I wanted to use Textpattern-like tags to show the images, not a bunch of ugly PHP code. Also, I didn’t want to hardcode any URL paths in my PHP (so that I can easily prototype new content on my home server before deploying to the public internet) and getting the correct URL dynamically meant dealing with some global PHP data which was ugly.

So that lead me to writing my first Textpattern plugin. There’s no turning back now, I’m about to actually cut some code.

My First Plugin

One of the cool features of Textpattern is that you can easily extend it by writing plugin code in PHP. My goal was to make a plugin that let me insert a Textpattern tag right in my article to show images, thumbnails, etc. just like my original PHP script would do.

In just a few hours my first plugin was up and running. I had to go back and rework the first few pages that I had converted to Textile, but after that the rest of the porting went much quicker.

Making It (almost) Public

Although I had done a Textpattern install on my public hosting site, I didn’t actually put any real content there. All my initial experimentation with Textpattern was done on my home Linux machine. Before I began the large task of importing all my existing content into Textpattern, I wanted to export from my home Linux machine to my public hosting service. When I did this, my Textpattern stuff was still in a subdirectory of my main site, so unless someone happens to type in http://www.pfactor.com/txp, they won’t see any textpattern stuff.

The Textpattern documentation wiki has an article called moving an installation from one host to another which looked great, but there were a few sections that had the content of ”(details needed)” which made me uncomfortable since I’m still a Textpattern newbie. A different article on the wiki had a link to Destry Wion’s instructions on how to move a live Textpattern site to a local server. Of course, I wanted to go the other way (local to public server), but I was able to follow basically the same steps he documented.

I don’t have phpMyAdmin installed on my home Linux machine, so I couldn’t use that to do the exporting step. But all I had to do was run mysqldump --add-drop-table -Q -u myDbUserName -p -Q my_database_name > my_database_name.sql My web hosting service does have phpMyAdmin, so I was able to do the importing using that tool.

After doing the import, I just had a little bit of minor cleanup to do.

  • In the Textpattern config screen Admin > Preferences > Advanced Preferences
    • Reset the temp folder path (it was /tmp on my Linux machine, but /home/virtual/.../tmp on my hosting service)
    • Make a similar change to the file upload folder
  • scp all the images from my Linux installation’s txp/images directory to my hosting server

Then I just ran the Textpattern diagnostics and everything passed. Nice! At this point I’m getting pretty comfortable with Textpattern, and I think I made a good choice. See my posting on Going Live with Textpattern to read about the last few things I cleaned up before fully converting this site over.

What’s Next?

Now that the basic site is working, here’s my list of things left to do as time allows. I addressed the first two of these before actually going live with this site (see Going Live with Textpattern).

Improved 404 error page

By googling “textpattern custom 404” I stumbled upon Lee Stewart’s hit tracking plugin which happens to also do a nice job of letting you set up a nice 404 error page from within Textpattern. There’s a good thread on this plugin on the Textpattern forum.

Create a Contact Me Page

My original site used a simple, and pretty secure PHP contact form called SCForm. I certainly could continue to use this with Textpattern, but I’d rather use a plugin that’s all ready to integrate into Textpattern.


I’d like to add a search function to the site, and Textpattern makes it easy. Unfortunately the default search doesn’t work the way I’d like for two reasons. The main reason is the default search treats multiple words like a phrase, meaning only the same consecutive sequence of words will be found. The second reason is cosmetic: I’d like to just use one line of screen real-estate by having an input box with the word “search” inside it. The Textpattern Resources site has several mods and plugins to address the first problem, so I’m not the only one bothered by this. My initial searching didn’t turn up anything to fix the second problem.

Create an if_previous and if_next plugin

I like how Textpattern’s <txp:link_to_previous> and <txp:link_to_next> tags show nothing when there is no previous/next article. However I want the ability to hide any other markup I’m doing in relation to those next/previous tags.

Make it easier to navigate between multi-part articles.

Textpattern has a <txp:related_artcles> tag which almost does what I want, since my multi-part articles (such as most of the Trip Journals) are in the same category.

However there are two things I don’t like about the related_articles tag. First it doesn’t let you specify the sort order, so the related articles are always shown newest first. That means part 3 shows up above part 2. The second thing I don’t like is that it shows the full title of the related articles. For multi-part articles it would be nice to show a custom field that said something short like “part 2”, instead of spelling out the whole title again.

Someone else requested a change to this tag on the textpattern forum.

User Comments

Eventually I’d like to turn on user comments. I need to spend some time digging into the new Textpattern 4.0.3 features that help with these, and most importantly help to filter out “comment spam” which will be required for me before I enable comments.

RSS Feed

Textpattern does have built-in support for an RSS feed, but there’s some weirdness with the implementation that makes it not work right with Firefox (and many other RSS readers from what I can tell). I want to look into this further and set up an RSS feed that actually works the way I expect it to as a Firefox user.

Display Textpattern Page and Form Source

One of the best ways to learn Textpattern is by example. When I first started looking at Textpattern, I was quite pleased with the variety of different looking sites people were able to create using Textpattern. However what I really wanted was the ability to see the Textpattern source for the pages and forms they used to create their site. It’s easy to see the CSS and HTML source, but it would be quite interesting to see the Textpattern pages, forms, and maybe even plugins that were being used.

I’d like to figure out a way to make it easy for Textpattern page authors to choose to show the source code of their pages to make it easier for others to learn about Textpattern by example. I have no idea of how to do this, but perhaps I’ll start a thread on the Textpattern Forum looking for ideas.

    Comments: 4

I read your article about porting your site to Textpattern. I plan to use Textpattern for a re-design of an existing site, and wondered if you had any further comments about it.

Are you using the 4.04 release?

#1 Deborah - 03/20/2007 11:53 AM

After just over a year of Textpattern use under my belt now, I can still strongly recommend it. Once you’ve got your basic site designed with forms and pages, adding new content is a breeze.

The level of customization is great, which allows you to make your web site look and work however you’d like to. It’s pretty rare that you’ll run into something that Textpattern cannot support either natively, or through a plugin.

The only additional comment I’d make is to recommend the series of introductory Textpattern materials that I posted about here

Yes, this site is running the 4.0.4 version of Textpattern. Upgrading from 4.0.3 was piece of cake.

#2 Phil Verghese - 03/20/2007 03:30 PM

You said "At home, I had to tweak a few Apache config settings and do some MySql housekeeping before really getting running."

I'm struggling to find any sites that go into detail about setting up TextPattern on a server that is under your control ... any clues, tips?

#3 Derek - 07/09/2010 05:13 AM

Have you looked at the textpattern documentation which is quite good? Also there’s a lot of good help on the textpattern forum if you’re stuck on a particular point.

#4 Phil Verghese - 07/17/2010 03:54 PM

Commenting is closed for this article.

If you wish to comment on this page, you may send a message to the authors.

© 2000-2017 Phil Verghese, all rights reserved.
XHTML | CSS | RSS | Powered by Textpattern | Hosting by Dreamhost