Easier TypoScript Editing

Posted on January 22, 2007

(I do a lot of work building and maintaining sites using the very fine open source content management system TYPO3 these days. Unfortunately, the documentation for TYPO3 can be a little daunting for beginners. So I’ve decided to start writing up some of my favorite tips and tricks in the hopes that they help newbies get up to speed more easily.) 

One of the things that makes the TYPO3 content management system unique is its TypoScript template system.  TypoScript templates are a powerful way to define the behavior of dynamic parts of your site.

On even a small site, though, you can quickly find your TS templates growing to 100+ lines of TypoScript — enough to make it a gigantic pain to work with through a tiny HTML textarea in the administrative backend, which is the default way you interact with your templates.

And as your templates grow, you will find yourself wishing for some of the nice things you can get in a good external editor — things like syntax highlighting and bracket-matching.

Thankfully, there is a way to work with your TypoScript in an external editor, rather than a textarea. In fact, there are two ways. Let’s dive in and learn how it’s done.

The first step is to get a text editor that understands TypoScript. While you can work in any editor, it’s much nicer to have one that can give you those nice touches I mentioned above. There are several editors that offer TypoScript modes — JEdit and UltraEdit both have TypoScript plugins available, and PSPad can do TypoScript with the SweeTS extension. (Know of any others? Sound off in the comments.)

Once you’ve got your weapon of choice, you’re ready to pick the approach you want to use.

The first way is to move your TypoScript into external files. By default, TYPO3 stores your TypoScript templates in its database — that’s why you work with them via the back-end admin interface. But your TypoScript doesn’t have to be stored in the database; you can store it in external files as well. And once it’s in a file, you can work with it in an editor like you would any other file — open a secure connection (using a tool like WinSCP if necessary), and then use that connection to make your edits.

Every TypoScript template has two main parts: the constants (where you store, um, constants) and the setup (where you put processing logic). In the TYPO3 back-end, each of these has its own field in the template record. To move either of these into a file, just put the following in the back-end field for that part:

<INCLUDE_TYPOSCRIPT: source="FILE:fileadmin/path/to/the/file.t3">

… replacing the path with the path to your file with the TypoScript in it. (You can call that file anything you want; I give mine the extension .t3 so that my editor knows it’s TypoScript.)

In most cases, the setup is where the real complexity of a TypoScript template lies, so that’s what you’d move to a file first; but you can have files for both setup and constants, or either one alone, if you wish.

The other way is to use MozEx to pipe the contents of the textarea to your editor.  MozEx is a Firefox extension that can send the contents of any textarea to any external editor you specify.  With that, you don’t even need to move your TypoScript out to a file; just go into the template in the back-end, invoke MozEx on the appropriate textarea, and you’re good to go. Personally I prefer the external-files method, so I don’t have much practical experience with MozEx. I’m told it works pretty well, though.

Either one of these methods will let you work with TypoScript using all the nice features of your favorite editor. There is one way you shouldn’t try to do this, though. JEdit’s TypoScript plugin advertises that it can connect up to your site using a special Typo3 extension which allows JEdit to retrieve your templates from your site over XML-RPC, and then save the updated templates back. This may sound convenient, but it’s much less secure, because (as of this writing) the JEdit plugin sends your TYPO3 back-end login back and forth in plain text.  Either of the two methods above provides a more secure way to solve this problem.

Happy TypoScripting!