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.
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).
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:
- Douglas Edmunds’ tutorial on the Textpattern presentation model
- 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.
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.
- When I learn more of the basics, I need to go back and read his notes on how to use the new tags introduced in Textpattern 4.0.2
- Textpattern Tags Manual – pretty well done, although it is about a year old so some thing are out of date
- Textpattern Semantics explains Textpattern terms like “category” and “section”
- Textile Reference – more complete than the documentation at the Textism site. For example the former documents how to do
inline codemarkup using the @ symbol.
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.
- 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
- 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.
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
widthentries from the ”#container” id
- Changed the ”#content” entry quite a bit.
- Changed the left/right margins from
- Added tags for
- Set background to
- Changed the left/right margins from
- Removed the
aelement, changed link color to dark blue.
- Presentation > Sections
- Deleted the old sections and created: about, articles, links, and trip journals.
- Made all sections use the new
pf-default-pgpage and the
- 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-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
- Upload the images and thumbnails for the page into Textpattern
- Run PHP script to convert HTML to Textile
- Manually fix up the references to images to match how Textpattern stored the images (change filename paths to image identifiers).
- 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.
- 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.
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_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.
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.
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.