This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
Posted on
The MTEntryDate tag holds the date an entry was written. This date can be displayed in hundreds of ways by using the format attribute with a set of format specifiers. The preceding example produces the following output:
Posted on July 02, 2004 04:39 PM
The format specifiers indicate the placement and style of each part of a date and time. In the example, %B stands for the full month name, %e for the day of the month, %Y for the four-digit year, and so on. The syntax is borrowed from strftime, a popular utility for displaying dates. A template can make use of more than 130 tags in a standard installation of Movable Type. If you download and install any plug-ins that enhance the functionality of the software, even more tags become available to you. Listing 1-1 contains a Web page template that displays the last three entries from a weblog on a plain Web page with no graphics and no frills. This kind of
Chapter 1 ✦ Publishing with Movable Type
11
template can be used to offer a version of your weblog that’s tailored toward people using a cell phone or personal digital assistant.
Listing 1-1: A Web Page Template Continue reading “”
In Listing 1-1, the Movable Type tags have names that begin with MT. All other tags are ordinary HTML tags. When the template is used to create a Web page, the Movable Type tags are replaced with the output they produce. Everything else will appear exactly as it does in the listing. A Web page produced with this template is shown in Listing 1-2.
Listing 1-2: A Web Page Produced from a Template Orlando Vacationer Orlando Vacationer Disney takes on Muppets, Bear Disney has purchased the Muppets and Bear in the Big Blue House Continued
12 Movable Type 3 Bible, Desktop Edition Listing 1-2 (continued) from Jim Henson Productions after years of effort to acquire them, according to E! Online. February 20, 2004 11:21 AM Killer whale born at SeaWorld Orlando Kalina, an 18-year-old killer whale at SeaWorld Orlando, gave birth to her fourth calf Monday at the park’s research and breeding facility, Shamu Stadium. February 11, 2004 09:39 AM Disney cuts pass program for disabled Disney World, along with other Disney theme parks, has curtailed a “special needs pass” program that allowed guests with disabilities to skip to the head of lines at each ride. February 7, 2004 08:04 AM
Comparing the two listings provides a taste of how templates and static text come together to form a Web page, which brings us to Figure 1-4, a view of the example page in a Web browser. Once you have created a page or file template in Movable Type, it will produce rendered output each time you write an entry or rebuild an entire weblog. A template-driven Web design makes the static elements of each page stand out from the material that will change — weblog entries, headlines, and data pulled from software settings and the database. You can create a template for each different way you want to present entries from your weblog. In addition to HTML, XHTML, and CSS, templates can produce output in any XML format. Movable Type supports RSS 1.0, RSS 2.0, and Atom, three syndication formats that enable a weblog to be read with client software called a newsreader.
Chapter 1 ✦ Publishing with Movable Type MTBlogName
13
MTEntryTitle
MTEntryDate
MTEntryBody
Figure 1-4: Generating a Web page from a template.
Listing 1-3 contains a template that contains the last 15 weblog entries formatted as an RSS 2.0 file.
Listing 1-3: An RSS 2.0 Template
14 Movable Type 3 Bible, Desktop Edition The template in Listing 1-3 includes some of the same Movable Type tags used earlier in the Web page template. As new presentation and data formats come into vogue, supporting them with Movable Type requires only a template for each new format. Earlier, I described the dilemma of keeping a large Web site current and errorfree when it is being maintained by hand. If Web publishers were rated on a scale from Goofus (always does wrong) to Gallant (always does right), most of us would be much closer to Goofus, producing pages that grow staler by the day. Movable Type makes it easy to be Gallant. Changing the design of an entire site requires only that a few templates be edited, whether the site contains a dozen pages or a thousand, and republishing the entire site can be accomplished with a single click of the mouse. Movable Type’s template feature supports a clear division of labor between Web designers and programmers working on the same site. Designers work with the formats they know — HTML, CSS, XHTML. Programmers deliver their work as custom Movable Type tags supported by plug-ins, and then tell designers how to use the tags.
Publishing Photos, Graphics, and Other Files Movable Type weblogs can incorporate digital photos, graphics, audio, and video files. Some users are making use of this functionality to create moblogs, multimedia weblogs that incorporate photos, video, and text prepared on cell phones and other mobile devices. Using the Upload File feature of the software’s browser-based interface, files on your computer can be uploaded to the Web server hosting the weblog and then stored in the weblog’s root directory, archives directory, or any of their subdirectories. Once a file has been uploaded, Movable Type can route it to a weblog entry by providing the HTML formatting necessary to present the file. This makes the most sense for digital photos and other images, but will work for any file format. Images can be displayed as part of a weblog entry or in a separate pop-up window. A weblog or one of its categories can consist of text, images, or a mixture of both.
Gotcha
Although you can upload files with Movable Type’s Web browser interface, there’s no way to use it to delete files later. Instead, to get rid of files that are no longer needed, you must connect to the Web server hosting the weblog with an FTP client or a shell account using telnet or SSH, and then delete the file manually. This applies only to Movable Type; TypePad offers file deletion.
Chapter 1 ✦ Publishing with Movable Type
15
Writing for an Audience One of the best ways to build a following for a weblog is to spark conversation between author and audience. Movable Type sites are equipped to do this through the comments and trackback features. Each weblog entry can receive public comments written by visitors, a feature that turns a popular weblog into a boisterous online community. This is at your discretion: You can specify that entries take no comments or be closed to new comments when a discussion is winding down. This preference is set for each entry using the Allow Comments drop-down menu at the bottom of the editing form, as shown in Figure 1-5.
Figure 1-5: Deciding whether to allow comments for a weblog entry.
Movable Type’s popularity and the comments feature result in a particularly attractive target for net abuse. Some spammers have written software that finds open comment links in Movable Type weblogs and automatically posts links to their sites, product ads, and other unwanted junk. To address this issue, Movable Type 3.0 includes improved commentmanagement capabilities and user registration through a central service called TypeKey (http://www.typekey.com).
16 Movable Type 3 Bible, Desktop Edition TypeKey is a free user authentication service that can be used by any Movable Type 3.0 weblog. Users register for a TypeKey account and verify their e-mail address, replying to a confirmation message. When they want to make a comment on any participating weblog, they must sign in to TypeKey first. Weblogs can require TypeKey or make it optional, allowing users who want to make use of the service to sign in. They also can be configured not to use it at all, thereby accepting public comments from all visitors without restriction.
Another feature for collecting feedback to your work is trackback, a way of discovering weblog entries on different sites that link to each other. trackback, a framework for data exchange between Web sites, was pioneered by Six Apart as a means of fostering communication between weblogs. It supplements comments, providing notification when another site is referring to one of your weblog entries (and vice versa). You might be familiar with the referrer tracking capability of Web servers, which lets you know what incoming links on other Web sites are bringing people to your site. This sounds a lot like trackback, but a referrer requires two things in order for you to find out about a link: ✦ A visitor must use that link to arrive at a page of your site. ✦ The visitor’s Web browser must not be configured to keep this information private. Trackback, on the other hand, is an immediate notification when someone else links to your weblog. There are many uses for trackback. The most common is to make it easier for weblog publishers to communicate with each other. Instead of visiting someone else’s site to leave a comment, you can offer your response in your weblog for the benefit of your own audience. Your correspondents will find out about your response when they view their trackback count for that entry, which appears alongside the comment count. When a weblog entry is published, Movable Type looks at the hyperlinks in the entry and sends what is known as a trackback ping in response to each one. A ping, in network communication parlance, is a short message to determine whether another machine is online and ready to accept requests. If there’s a trackback server on the receiving end of the ping, it stores the link to the weblog entry and some (or all) of its text. There’s also a way to specify other links to ping for trackback purposes. Like comments, trackback can be enabled or disabled on a per-entry basis. The Allow Pings checkbox at the bottom of the entry editing form controls this feature.
Chapter 1 ✦ Publishing with Movable Type
17
Connecting Movable Type to Other Software Although Movable Type stands alone as a complete publishing system, it can work with external programs that either complement or replace some of its features. Weblog entries and related data can be imported from other weblog publishing software into a Movable Type weblog. The first step is to export this data in a simple plain-text format. Six Apart has documented how to create export data for the Blogger, Greymatter, and Newspro programs, and it works with other publishing tools such as Manila and Radio UserLand. The exported data must be uploaded to the server by using an FTP client or similar means and placed in the directory where Movable Type expects to find it: an import subdirectory under the software’s main directory. If the old weblog supported categories and comments, these can be imported with the text, title, and link for each of the entries. If categories were not supported by the old tool, they can be specified quickly using Movable Type’s power-editing feature, a means of working on 20 or more weblog entries using the same form (see Figure 1-6).
Figure 1-6: Working on multiple weblog entries in power-editing mode.
As shown in Figure 1-6, the title, category, author, and publication status of several weblog entries can be changed without leaving the form. The powerediting form can hold from 5 to 125 entries, or even the entire weblog.
18 Movable Type 3 Bible, Desktop Edition In addition to importing weblog entries, Movable Type can receive data from weblog entries using XML-RPC, an XML format that enables programs to call each other’s procedures over the Internet and other networks. The software supports several application programming interfaces (APIs) that make use of XML-RPC: Blogger, MetaWeblog, and Movable Type’s own API. These APIs enable client software to be used to read and write weblog entries, comments, and trackback information. The most common use for these XML-RPC interfaces is to offer weblog textediting capabilities that are more sophisticated than the software’s browserbased interface. Movable Type 3.0 adds support for the Atom API, a new application programming interface designed in concert with the Atom syndication format. The Atom API can be used in a similar manner to XML-RPC APIs, reading and writing weblog data from any software that supports the API. Find out more in Chapter 19, “Supporting the Atom Syndication Format and API.”
Installing Movable Type In order to install Movable Type on a Web server, your account must have permission to set up and run custom CGI scripts. This is a deal-killer with many Web hosting services — many server administrators prohibit this functionality to keep users from opening a security hole, either intentionally or by accident. Therefore, if you are selecting a service specifically for use with Movable Type, check it out thoroughly before joining. Installing Movable Type’s Perl scripts is straightforward, but you also might need to install several Perl modules that are used by the software, as described in the Chapter 2.
Finding a Host That’s Your Type Six Apart has drafted an e-mail message that Movable Type users can send to a Web hosting service provider: I am interested in running a weblogging content-management system called Movable Type (http://www.movabletype.org/) on my account. This system has the following requirements:
✦ The ability to run custom CGI scripts ✦ Perl, version 5.004_04 or later And either of the following: Support for the DB_File Perl module *OR* MySQL & the DBD::mysql module Does my account on your service meet these three requirements?
Chapter 1 ✦ Publishing with Movable Type
19
Summary Without fail, Web publishers who begin to use a content-management system kick themselves for not doing so sooner. Smart software takes the pain out of publishing in this dynamic medium, making it easy to produce new content and keep old content fresh. The compulsion to create Web pages by hand in a text editor becomes one of those quaint labor-intensive chores of a bygone era, like the creation of illustrated manuscripts by monks. Like the printing technique of the same name that was invented by Johann Gutenberg in the 15th century, Movable Type replaces the need for a lot of drudge work, freeing writers to spend more time communicating with their audience. The personal publishing system created by Ben and Mena — there I go again with their names — provides a solid foundation for one-person publishers and teams to collaborate on weblogs. The software is also well suited for other sites that present fast-changing information organized by date, magazine-style sites, and similar efforts. This chapter described the general reasons why and how Movable Type has become the most popular server-based software for creating weblogs. The rest of this book delves into the specifics of the software — setting it up, mastering its features, extending its functionality with plug-ins, and building your own software enhancements that make it better.
Preparing a Web Server for Movable Type
B
efore you begin installing Movable Type, you must ensure that your Web server can handle the software.
2
C H A P T E R
✦
✦
✦
In This Chapter Finding Perl on your server Telling scripts where to find Perl Selecting a database program
Movable Type consists of a set of Perl scripts that are run by a Web server, accessing a database that holds several kinds of information for each of your weblogs: entries, templates, visitor comments, trackback pings, and more. Although the software most commonly runs on Linux systems, that’s not a requirement — a Web server on Windows equipped with Perl and MySQL can be used, as can a Mac OS X box.
Creating a MySQL database for Movable Type
If this is your first experience running a Web application, you might find it challenging to set the software up on a server.
Running CGI scripts more securely
If you make the task easier by using the full installation of Movable Type and your server has the software that it requires, however, you can set up the program yourself and learn more about how it functions.
Meeting the Conditions for the Software Although Movable Type runs most commonly on Linux or UNIX systems, the software neither favors nor requires those operating systems. You can run its Perl scripts and access a database with any OS as long as it supports Perl and the database you select for storage.
✦
Installing Perl modules Using the CPAN archive
Installing the CGIWrap script
✦
✦
✦
✦
22 Movable Type 3 Bible, Desktop Edition The first requirement to use the software is the capability to use the command-line environment of your own operating system, whether a command shell on Linux, UNIX, and Mac OS X computers or an MS-DOS command prompt on Windows. Although commands vary in the subsequent sections of this chapter, their purpose remains the same regardless of your chosen OS. Windows users will encounter differences in how directories and files are specified, and do not use the same commands as a Linux shell in the Command Prompt window. Instead, Windows offers a command-line environment that mimics MS-DOS, the operating system that preceded Windows, rather than one of the Linux shells. The same tasks must be accomplished on any operating system: ✦ Make sure that Perl has been installed and that Movable Type scripts know where to find it. ✦ Choose a database program. ✦ Set up required Perl modules along with any optional modules that you want to use. ✦ Install CGIWrap so that Movable Type and other CGI scripts can be run more securely. When you have met all of these conditions (or at least the first three if you decide not to use CGIWrap), you can begin installing Movable Type.
Checking for a Perl 5 Installation All of the code that drives Movable Type has been written in the Perl language and requires version 5.004_04 or later of the Perl interpreter. To see which version has been installed on your server, type the following commands. Linux (and similar command shells): $ /usr/bin/perl -v
Windows with ActivePerl: C:\> perl -v
If the command doesn’t work, your Perl interpreter has not been installed in the /usr/bin directory. On Linux, you should be able to find it by typing the following command: $ whereis perl
Files matching the name perl will be listed, and at least one of them should be the interpreter.
Chapter 2 ✦ Preparing a Web Server for Movable Type
23
The recommended Perl distribution for Windows is ActivePerl. To determine whether it’s present on the server, open the Control Panel and click Add or Remove Programs. ActivePerl, which also can be installed on Linux and Solaris systems, can be downloaded as a trial version from the ActiveState Web site: http://www.activestate.com/Products/ActivePerl
As described in the next chapter, “Installing Movable Type,” after you have downloaded Movable Type, you’ll need to know where Perl can be found on your system.
Setting Up a Database for Your Weblog Movable Type requires a database to hold the contents of your weblogs and the files required to publish them. Four databases can be used for this purpose: the simpler, file-based programs Berkeley DB and SQLite, and the more robust relational databases MySQL and PostgreSQL. Because all four are either open source or public domain, there’s no additional financial expenditure required to use any of them as the back end for your Movable Type installation. With version 3.0 of the software, Six Apart recommends using either Berkeley DB or MySQL as your database. You might already have one or more of these programs installed on your Web server, so check before choosing your database. Movable Type works with each of these databases entirely behind the scenes, accessing the programs through Perl modules that function as drivers, providing an interface between the weblogging tool and the database program. The main factors to consider when selecting the database are ease of configuration and performance delivering data. All four can be set up to work with Movable Type in minutes. The Berkeley DB and SQLite programs install easily and require little configuration, but they do not perform as well on large, hightraffic weblogs as MySQL and PostgreSQL, database programs that require more work to install and set up correctly. Berkeley DB, arguably the simplest of the four, is the only one that does not make use of Structured Query Language (SQL), a standard for reading and writing database information. The open-source software stores weblog data in a single database file, which you will identify during configuration (as covered in the next chapter, “Installing Movable Type”). You can download Berkeley DB from Sleepycat Software at http:// www.sleepycat.com.
24 Movable Type 3 Bible, Desktop Edition The SQLite database also stores a database in a single file, but makes use of SQL. The software, which requires little to no configuration, has been released into the public domain, removing all copyright claims to the work, but continues to be actively supported. Download SQLite from its official Web site at http://www.sqlite.org.
Berkeley DB and SQLite require a directory in which the database can be stored. The directory must be outside of the directories that can be accessed by your Web server. You can use the server’s main CGI directory for this purpose, assuming that your server has been configured correctly and will not serve any files located there, or any other suitable directory. The last two database programs, PostgreSQL and MySQL, are robust relational databases with more extensive requirements to install and maintain. PostgreSQL and MySQL are highly sophisticated open-source programs available from http://www.postgresql.org and http://www. mysql.com, respectively.
MySQL, the storage software recommended by Six Apart, uses the tables indicated in Table 2-1.
Table 2-1 Movable Type’s Database Tables in MySQL Name
Description
mt_author
User accounts for weblog editors and TypeKey users who sign in to post comments
mt_blog
Information about each weblog
mt_category
Categories available on all weblogs
mt_comment
Comments posted by weblog visitors
mt_entry
Weblog entries
mt_ipbanlist
IP addresses banned from posting comments or trackback
mt_log
Activity log tracking use of the software by editors
mt_notification
Users requesting e-mail when a weblog has been updated
mt_permission
Tasks a weblog editor has permission to perform
mt_placement
Category assignments for weblog entries
mt_plugindata
Information about installed plug-ins
Chapter 2 ✦ Preparing a Web Server for Movable Type Name
Description
mt_session
User-tracking sessions
mt_tbping
Trackback pings received by weblogs (along with mt_trackback)
mt_template
Templates stored in the database
mt_templatemap
Map determining how templates are used
mt_trackback
Trackback pings received by weblogs (with mt_tbping)
25
The MySQL and PostgreSQL databases require installation and configuration that must take place before you begin setting up Movable Type. After that has taken place (or you have chosen a Web hosting service with a pre-installed database prepared for your use), a database must be prepared, along with a user account that can access it. You can make use of an existing MySQL or PostgreSQL database with Movable Type or create a new one solely for the use of the software. The latter option provides more security, preventing Movable Type data from being overwritten by another program and vice versa. The database doesn’t need to be set up with tables. Movable Type takes care of this during installation. The following commands, when entered while running MySQL in interactive mode, create a suitable user and database: create database movable; grant all on movable.* to mtuser@localhost identified by “password”; grant all on movable.* to mtuser@”%” identified by “password”;
The last two commands identify the same user, mtuser, so the password you choose in place of password should match. These commands create a database named movable and give a new user named mtuser access to it from the local server or any other server in the world.
Gotcha
Giving the world access to a MySQL database exposes the database to considerable security risk, so you can opt to omit the second command and limit access to localhost only (the machine on which the database is running). The database will be more secure, but you won’t be able to access it or transfer data to and from other Internet servers running MySQL. In addition, you might have trouble accessing the database on some versions of Red Hat Linux due to longstanding issues with the way they identify the localhost machine.
26 Movable Type 3 Bible, Desktop Edition
Setting Up Perl Modules Movable Type’s Perl scripts make use of external Perl modules that deliver different aspects of the software’s functionality. Many of these are included with the software, working immediately, but others must be downloaded and installed separately. These modules are described in Table 2-2.
Table 2-2 Perl Modules Required by Movable Type Name
Job
Status
CGI::Cookie
Read and write Web browser cookies for user personalization
Required
Crypt::DSA
Verify cryptographic signatures with the Digital Signature Algorithm (DSA)
Optional
DB_File
Access the Berkeley DB database
†Optional
DBD::mysql
Access the MySQL database
†Optional
DBD::Pg
Access the PostgreSQL database
†Optional
DBD::SQLite
Access the SQLite database
†Optional
File::Spec
Work with filenames and directory paths
Required
File::Temp
Read and write temporary files
Optional
HTML::Entities
Encode and decode HTML markup with entity codes
Optional
HTML::Template
Produce pages, syndicated feeds, and other files from templates
Required
Image::Magick
Create thumbnails of uploaded images
Optional
Image::Size
Determine the height and width of graphics files
Required
LWP::UserAgent
Send requests and responses to Internet servers over HTTP
Optional
MIME::Base64
Encode and decode strings using Base64 encoding
Optional
SOAP::Lite
Exchange weblog data with other software using the XML-RPC APIs
Optional
Storable
Store data persistently to files
Optional
XML::Atom
Exchange weblog data with other software using the Atom API
Optional
† At least one of the four database modules must be installed.
Chapter 2 ✦ Preparing a Web Server for Movable Type
27
When you install the full version of Movable Type as either a ZIP archive (.zip) or a GZIP tarball archive (.tar.gz), it should include all but five of these modules: DB_File, DBD::mysql, DBD::Pg, DBD::sqlite, and Image::Magick. During the installation of Movable Type, a system check script determines which of these modules are present on the server, organizing them into three sections: required modules that must be installed for the software to function, optional modules that support non-essential features, and database modules that support a particular database. You only need one database module: the one that supports the database program you’ll be using with Movable Type. The others can be disregarded. The system check script is shown running in a Web browser in Figure 2-1.
Figure 2-1: Determining which Perl modules are present on a server.
Most, if not all, of the absent Perl modules can be installed easily using the Comprehensive Perl Archive Network (CPAN), a tool that automates the process of finding, downloading, and setting up modules. Two of the modules employed by Movable Type have additional prerequisites before they can be installed with CPAN. The XML::Atom module requires either the XML::LibXML or XML::Parser modules to process XML data. Normally, when Movable Type’s installation script indicates that XML::Atom cannot be found (a topic discussed in the next chapter), the real source of the problem is that neither XML::LibXML nor XML::Parser has been installed on the server.
28 Movable Type 3 Bible, Desktop Edition The Image::Magick module requires something that can’t be installed as a Perl module: ImageMagick, a set of image manipulation tools available for download from http://www.imagemagick.org. The software has been offered for distribution as source code, which must be compiled, and as a Linux RPM package.
If you use the rpm tool to install and upgrade packages on a Linux system, you can install a downloaded copy of the ImageMagick RPM with the following command: rpm -Fvh ImageMagick-6.0.2-7.i386.rpm
Change the version number to match the one downloaded from the ImageMagick Web site. CPAN represents a globally distributed archive of Perl documentation and modules. This resource has been documented on the Web at http://www.cpan.org. You can access this archive in interactive mode by running Perl with the -MCPAN --e shell command-line arguments. Linux-style shells: $ /usr/bin/perl -MCPAN -e shell
Windows command prompt: C:\> perl -MCPAN -e shell
The archive opens, displaying a command line from which you can install modules and perform other tasks. Type help for a list of commands. You can attempt to install a module by typing the install command followed by its name (as identified in the first column of Table 2-2): cpan> install File::Temp
The preceding command prompts CPAN to find and download File::Temp, compile the software, and install it. When a Perl module requires another module, as in the case of XML::Atom, CPAN asks whether it should be installed first. This can set into motion a chain of prerequisite installations in which a large number of modules are being downloaded, built, and installed. As CPAN functions, a large number of messages are displayed that are likely to make little sense to you. The software displays a lot of information that is only of benefit to experienced Perl programmers and others who routinely build their own software.
Chapter 2 ✦ Preparing a Web Server for Movable Type
29
The only messages that you must pay attention to are questions and the final messages shown, which indicate whether the installation of the module was a success or a failure. CPAN can be a great boon when it works successfully — type one command, answer a question or two about other modules to install, and boom, you’re done. When it doesn’t, you might need to find other means to install the module or set up programs that were required to build it. The CPAN archive also can be accessed in non-interactive mode by specifying the package to install, as in the following example: perl -MCPAN -e ‘install Weather::Underground’
Using CGIWrap to Improve Security Like any publicly accessible service on the Internet, a Web server must be aggressively protected to deal with current and future security vulnerabilities. Computer administrators patch their systems frequently to prepare for new exploits that take advantage of software bugs to break into servers, spread viruses, and commit other forms of virtual mayhem. People who attempt to access servers without permission are called crackers. Although some crackers are motivated by curiosity rather than a desire to cause harm to a compromised server, even a non-malicious cracker can read data that should be private and cause damage unintentionally. From the moment it goes online, a Web server will be subjected to frequent break-in attempts, even if the server is newly launched and has not been publicized. My own servers attract particular interest from crackers all over the world on U.S. holidays, presumably because I’m less likely to be around to observe the attempts.
CGI scripts such as the programs that deliver Movable Type’s functionality represent one of the main points of vulnerability on a Web server. A poorly executed or misused script could be attacked, executing cracker-authored code that runs as the user running the server (or, even worse, in some cases as the root superuser). Although Movable Type’s scripts have been tested and improved for several years, there’s always a chance with any software that new vulnerabilities will be discovered and exploited. You can reduce the vulnerability of CGI scripts by running them with CGIWrap, an open-source program created by Nathan Neulinger that runs these scripts in a more secure manner.
30 Movable Type 3 Bible, Desktop Edition The software can be downloaded from the CGIWrap Web site at http:// cgiwrap.unixtools.org. This site also contains documentation for the software and a frequently asked questions list.
CGIWrap works with several Linux and UNIX Web servers — most notably, the Apache Web server. CGIWrap, which is itself a CGI script, performs several security checks on a program that it is asked to run. The script primarily ensures that each CGI script executes as the user and group that own it rather than as the Web server. By design, the CGIWrap script runs CGI scripts from each user’s public_html/ cgi-bin folder (for instance, mine run from /home/rcade/public_html/ cgi_bin). If a script does not belong to the right user and group, it won’t run. The CGIWrap program can be downloaded as an archive file prepared with the tar and gzip utilities (in other words, a .tar.gz file). The following commands expand the archive: $ gzip -d cgiwrap-3.9.tar.gz $ tar xf cgiwrap-3.9.tar
A directory is created that’s named for the file (for instance, the preceding commands for CGIWrap 3.9 produced a directory called cgiwrap-3.9). The script includes documentation in the README file in its main directory and in several Web pages in the htdocs directory. You must configure and build the software using command-line options that customize it to work on your server. To see the configuration commands that can be used, type the following command in the program’s main directory: $ ./configure --help
At a minimum, you should specify the following arguments: ✦ --with-httpd-user=username: The user account that runs the Web server ✦ --with-install-dir=path: The directory in which CGIWrap should be installed You also might want to consider using these arguments: ✦ --with-multiuser-cgi-dir=path: The directory in which common CGI scripts are located ✦ --with-perl=path: The directory and filename of the Perl executable (such as /usr/bin/perl) ✦ --with-php=path: The directory and filename of PHP (often /usr/bin/php)
Chapter 2 ✦ Preparing a Web Server for Movable Type
31
After configuring the software, build and deploy it using the make and make install commands. Here’s a complete example from my installation: $ ./configure --with-php=/usr/bin/php --with-perl=/usr/bin/perl \ --with-httpd-user=apache --with-multiuser-cgi-dir=/var/www/cgi-bin \ --with-install-dir=/var/www/cgiwrap $ make $ make install
To use the script with Movable Type, all scripts and files associated with the software must be installed in the public_html/cgi-bin subdirectory of the user who should run them. On my server, Movable Type runs as user account rcade and has been installed in /home/rcade/public_html/cgi_bin. I ensured that the account was the owner and group for the scripts with the following commands: $ chown rcade mt*cgi $ chgrp rcade mt*cgi
Once CGIWrap has been installed, CGI scripts always should be run through this program, rather than being directly executed. On a Web server where the cgiwrap script is stored in the server’s main cgi-bin directory, a CGI script can be run using the URL /cgi-bin/cgiwrap/ username/scriptname, as in this example: http://orlandovacationer.com/cgi-bin/cgiwrap/rcade/mt-check.cgi
Double-Checking the Installation The cgiwrap script must be owned only by root. Other groups and users should only be able to read and execute the script. Also, three symbolic links should be created to cgiwrap in the same directory: cgiwrapd, nph-cgiwrap, and nph-cgiwrapd. According to the documentation for CGIWrap, running make install sets the cgiwrap script to the proper permissions and creates links to several other versions of the program as needed. This wasn’t happening with version 3.9 of the software. The following commands, when run from the directory in which CGIWrap files have been installed, ensure that the program is set up correctly: $ $ $ $ $
chown chmod ln -s ln -s ln -s
root cgiwrap 4755 cgiwrap cgiwrap cgiwrapd cgiwrap nph-cgiwrap cgiwrap nph-cgiwrapd
32 Movable Type 3 Bible, Desktop Edition The mt-check.cgi script, which is part of Movable Type, checks whether the software has been configured correctly and is ready to run. When you have installed Movable Type, the check script will attempt to detect CGIWrap, displaying the message “(Probably) Running under cgiwrap or suexec” when successful.
Summary Preparing for the installation of Movable Type can be easy or difficult, depending on whether the necessary software is present on the server where you will be running the software. The best way to simplify the installation is to choose the full version of Movable Type with its included Perl modules, reducing the number of modules you must install using CPAN or other means. If you have reached this point without setting up one or more optional Perl modules, continue to the next chapter and install Movable Type. You might find that you can get by without the features supported by the module, such as the graphics thumbnail creation capabilities of the Image::Magick module and ImageMagick software. Once a database has been chosen and you set up Movable Type to access it correctly, it will do its work behind the scenes and require no direct maintenance.
Installing Movable Type
3
C H A P T E R
✦
T
he installation of Movable Type amounts to a goodnews, bad-news scenario.
The bad news: Setting up a server-based program like Movable Type can be a difficult challenge for many Web publishers. There’s no installation wizard or helper program that makes it easy to set the program up on a Web server. The good news: By the time you’ve completed the steps necessary to download, configure, upload, and run the software, you’ll have a stronger understanding of its capabilities. Web publishers who are comfortable with the operation of a Web server should be able to set up Movable Type quickly. The software runs through the Common Gateway Interface as a set of Perl scripts.
✦
✦
✦
In This Chapter Getting a copy of Movable Type Downloading and unpacking the software Setting up the software’s Perl scripts Selecting a database Creating a database and a user Making the necessary software directories
In addition to setting up the software and a configuration file, you must prepare a database such as MySQL or PostgreSQL before running Movable Type for the first time.
Examining the configuration file
Downloading the Software
Uploading the software to a Web server
You can download Movable Type from the Six Apart Web site at http://www.movabletype.org. Three versions can be downloaded:
Making the program secure
Using setting commands
✦ A full version, with libraries
Testing the installation
✦ A full version, without libraries
✦
✦ An upgrade version A new Movable Type user must choose one of the full versions, deciding whether to include Perl module libraries that support all of the software’s functionality.
✦
✦
✦
34 Movable Type 3 Bible, Desktop Edition If you’re comfortable with Perl module installation or know that your server offers all the modules required by Movable Type, you can save yourself a longer download and some disk space by downloading the full version without libraries. Otherwise, you’re better off with the full version that includes the module libraries. They take up more disk space but make installation significantly easier. The upgrade version includes only the files necessary to bring an existing Movable Type installation up-to-date. All three versions are available in two archive formats: ZIP, the preferred archival format on Windows, and GZIP TAR, the most common format on Linux systems. Regardless of the installation version that you choose, you can complete these steps to download and install Movable Type: 1. Download a version of the software from Six Apart. 2. Extract all of the files to a directory on your computer. 3. Prepare the files for use on the server and edit the configuration file mt.cfg. 4. Upload the files and directories to the proper places on the server. 5. Set the proper file permissions and create any directories required by the software. 6. Run Movable Type’s check script, mt-check.cgi, which determines whether the software has been configured correctly and is ready to run. 7. Run the system loader script, mt-load.cgi, which initializes the software’s database. 8. Delete mt-load.cgi. These steps are described fully in the following sections of this chapter. If you have full access to the Web server on which Movable Type will be run, you can download the software directly to that server and work with it there. Six Apart puts no restrictions on the functionality of the software; it isn’t a trial download that only works for a short time. Personal and non-commercial users can use the program for three weblogs with only one author under a free license. Personal users who require more authors and weblogs can purchase a fiveauthor, unlimited-weblog $69.95 license or a $99.95 license with unlimited authors and weblogs. Commercial users can buy licenses ranging from $199.95 to $1,299.95. More details on personal and commercial licenses can be found on the Web at http://www.movabletype.org on the Get Movable Type link. License purchasers for any personal or commercial edition receive tech support and weblog promotion in the “Recently updated” site list on the Movable Type Web site, as well as other perks.
Chapter 3 ✦ Installing Movable Type
35
Setting Up Movable Type to Use Perl 5 The Movable Type application consists of a set of Perl scripts, Perl module libraries, and Web pages delivered by a Web browser. After you download the software and extract its files to a temporary directory, you might need to make a minor change to the first line of the scripts. All of Movable Type’s scripts are located in the main installation directory and have names that end with the file extension .cgi. These 12 Perl scripts are run by a Web server using the Common Gateway Interface (CGI), a standard protocol governing how Web servers and software exchange information. Perl scripts are text files that can be opened and edited with any editor that can handle simple text with no formatting or fonts. The first line of each Movable Type script identifies where the Perl interpreter can be found on the server: #!/usr/bin/perl –w
If Perl exists in the /usr/bin directory on the server, you don’t need to edit any of the scripts. If your interpreter has not been stored at /usr/bin/perl or you are running on Windows, you must edit Movable Type’s Perl scripts to indicate the proper location of the interpreter. If necessary, open each of the scripts and replace /usr/bin/ with the correct directory containing the perl interpreter. On a Linux system, you can search for the interpreter with the whereis command: $ whereis perl
For example, if the interpreter was found in /usr/local/bin/perl, the first line of each Movable Type script should become the following: #!/usr/local/bin/perl –w Although it is named like a script, the file mt-db-pass.cgi is not one of Movable Type’s scripts and does not need to be edited to indicate the location of the Perl interpreter. Don’t edit this file — you’ll find out what to do with it later in this chapter.
Verify that each script has the proper location of the Perl interpreter in its first line, but don’t attempt to run any of them yet.
36 Movable Type 3 Bible, Desktop Edition
Preparing a Database Movable Type works with four database programs. Two of them, PostgreSQL and MySQL, require some minor preparation to work with the software: 1. Create a new database that can be used by Movable Type. 2. Create a new user account that Movable Type will use to access the database. 3. Grant that account the privileges to read, write, and delete tables and records in the database. Although an existing database and database user can be employed by Movable Type, this practice should be avoided so that you don’t allow other users to make changes to your weblog data. The converse also is true: Movable Type shouldn’t have access to other databases. In MySQL, a database can be created by following the create database command with the desired name: create database movable;
Like all MySQL shell commands, create database should be followed by a semicolon. The preceding command creates a new database named movable. You can use the grant all command to create a user account and give it access to the new database: grant all on movable.* to dbuser5@localhost identified by “swordfish”;
This MySQL command creates a new account named dbuser5 with the password swordfish, giving the account full privileges to do anything in the movable database. The reference to localhost in the username limits dbuser5 to access only from the same machine hosting Movable Type and the database. This can be replaced with any host name or % to allow access from any Internet-connected machine: grant all on movable.* to dbuser5@”%” identified by “swordfish”;
Because of the security implications of allowing MySQL access from anywhere on the net, choose a good password, preferably one that includes letters, numbers, and punctuation, and isn’t a dictionary word like swordfish.
Gotcha
On some versions of Red Hat Linux and perhaps other Linux distributions, you might have trouble accessing a MySQL database from Movable Type if you limit connections to localhost. Use both of the preceding commands to ensure that a successful database connection can take place.
Chapter 3 ✦ Installing Movable Type
37
Editing the Configuration File Before you can run any of the Perl scripts that comprise the functionality of Movable Type, you must edit the software’s configuration file, a text file named mt.cfg found in the main installation directory. You can open this file using almost any simple text editor, as long as it can handle Linux-style line separators without running all of the lines together. One editor that has problems with the file is Windows Notepad; use Wordpad instead on Windows operating systems. The configuration file contains settings that apply to all weblogs administered by your installation of Movable Type. The file consists of more than a dozen single-line setting commands, preceded by documentation that explains the aspect of the program they control. Here’s an excerpt from the file: # # # # # # #
Movable Type uses the CGIPath setting to construct links back to CGI scripts; for example, the MT tag is substituted with the value of the CGIPath setting. You will need to change this value when you first install MT; instructions for doing so are in the Installation Instructions, in INSTALLING THE MOVABLE TYPE APPLICATION CODE, Step 3.
CGIPath http://WWW.YOUR-SITE.COM/PATH/TO/MT/
In the file, blank lines and lines preceded with a pound sign (#) are ignored. They’re in the file for your benefit, showing how to work with Movable Type’s settings. Setting commands consist of the setting’s name followed by a space and its value, as in the CGIPath line in the example, which assigns that setting the value http://WWW.YOUR-SITE.COM/PATH/TO/MT/. Some setting commands are preceded by a pound sign (#), which causes them to be recognized as comments and ignored by the software, as shown in the following line: # EmailAddressMain [email protected]
The purpose of ignoring a setting command like this is to use the default value. When you decide not to use the default, you delete the # character and edit the value as desired. Movable Type’s configuration settings specify where to find files, how to access a database, and many other aspects of its performance. The configuration file contains more than 60 setting commands, but you don’t need to work with all of them as you begin using Movable Type. Many have default values that should be acceptable on most installations of the software; others are described in subsequent chapters when they become useful.
38 Movable Type 3 Bible, Desktop Edition The next four sections cover seven settings that you must edit and 10 others that you might need to change as you begin using the software.
Choosing the Software’s Directories Movable Type’s browser-based user interface makes use of two Web addresses: ✦ The CGI path, which is the address of the directory that contains the configuration file and all of the software’s Perl scripts ✦ The static Web path, which is the address of the directory that holds the software’s online manual and the user interface’s graphics and files These addresses, which can be full URLs such as http://example.com/ or relative URLs such as /weblog/resources/, are established by the CGIPath and StaticWebPath settings in the configuration file. Set CGIPath to the address of the directory from which Movable Type’s Perl scripts are run. The directory must be one that can be used for CGI scripts — for security reasons, the Apache Web server and other servers can be configured to run CGI programs only from certain directories. Using Apache, one place to put Movable Type scripts is the Web server’s main CGI directory, which on many Linux systems is located in the directory /etc/httpd/cgi-bin and has the URL /cgi-bin/. Here’s a command that sets this up in the configuration file: CGIPath http://example.com/cgi-bin/
If you have installed CGIWrap to run scripts more securely, the CGIPath setting should refer to the user directory, as in this example from my own Web server: CGIPath http://www.prefect.com/cgi-bin/cgiwrap/rcade/
The StaticWebPath setting must correspond to the directory in which the browser interface’s support files and the images and docs subdirectories are stored. Here’s an example that uses a relative URL: StaticWebPath /movable/static/
On prefect.com, this path corresponds to the URL http://prefect.com/ movable/static/. When you begin editing the configuration file, the StaticWebPath setting command is a comment, which causes the default to be used: the same directory as the CGI path. This does not work when the CGI path is a Web server’s main /cgi-bin directory, because that directory cannot serve graphics and other non-executable files.
Chapter 3 ✦ Installing Movable Type
39
If they don’t exist yet, create directories on the Web server for the CGI path and static Web path. You’ll be uploading files to these directories after the configuration file has been edited.
Setting Up Database Access Seven configuration settings determine how Movable Type accesses the database that holds weblog entries, templates, and other data. You can use four programs — Berkeley DB, MySQL, PostgreSQL, and SQLite — and several are configured in different ways. If you are using either Berkeley DB or SQLite, you must create a directory on the server for the storage of database files. The DataSource setting chooses this directory. The following command places it in the CGI path directory in a subdirectory named db: DataSource ./db
On a Windows system, the same setting uses a different separator character: DataSource .\db On some Windows servers, you might have better luck using a full directory and filename reference as the DataSource setting, including the drive letter. Here’s an example: DataSource E:\weblog\db
If your CGI path is a server’s main /cgi-bin directory, this default setting puts the directory in a place where it can be used by Movable Type but can’t be accessed over the Web. This fulfills an important security consideration for the database files — visitors to your Web site should be prevented from viewing these files with their browsers. The directory chosen as DataSource must not be one that contains Web-accessible files. Once you have set up the data source directory, that’s all you need to do if Berkeley DB is your database. A Movable Type installation that uses anything else must set up several additional configuration settings, which can include a database driver (ObjectDriver), a database name (Database), a user (DBUser), and a server (DBHost). The ObjectDriver setting should be DBI::mysql (for MySQL), DBI::postgres (for PostgreSQL), or DBI::sqlite (for SQLite). These names correspond to Perl modules that serve as an interface between Movable Type and the chosen database.
40 Movable Type 3 Bible, Desktop Edition The Database setting provides the name of the database in which Movable Type will create its tables and records. When using MySQL or PostgreSQL, this database must already exist, because Movable Type cannot create it. For an SQLite database, the name refers to a file and should be preceded by the name of the directory chosen as the DataSource setting. For example, if you’re storing the database on a Linux system in ./db, a suitable Database setting would be db/mvdata or db/blog-database. The DBHost setting provides the host name of the database’s server, which can be localhost if it’s on the same machine as Movable Type. On a MySQL or PostgreSQL database, a user must be specified with the DBUser setting. This user should already exist and have the privileges to read and write tables in the database. These databases also require a password, which is specified in a file outside of the Movable Type configuration. Here’s where that mt-db-pass.cgi file becomes important. Open the file and replace the existing line with the password associated with the database user. The last two database settings in the configuration file, DBSocket and DBPort, become necessary only on a database that requires a nonstandard socket file or port number. The following settings set up Movable Type to work with a MySQL database named movable accessed by the user dbuser5: ObjectDriver DBI::mysql Database movable DBUser dbuser5 DBHost localhost
Configuring E-Mail Servers Several features offered by Movable Type make use of e-mail. The default configuration for the software, which often requires no modifications, sends e-mail with the Sendmail program, looking for it at /usr/lib/sendmail, /usr/sbin/sendmail, or /usr/ucblib/sendmail (which, as you probably noted, assumes the software has been installed on Linux or UNIX). The SendMailPath setting can be used to specify a different location for the program, as needed: SendMailPath /usr/bin/sendmail
To use an SMTP server instead of Sendmail, use the MailTransfer setting smtp and an SMTPServer set to the name of the server, like so: MailTransfer smtp SMTPServer smtp.example.com
Chapter 3 ✦ Installing Movable Type
41
The last tweak that can be made to e-mail is EmailAddressMain, a setting that chooses the “From” address of mail sent by Movable Type. The following command makes it [email protected]: EmailAddressMain [email protected]
Because all of these setting commands normally use default values, be sure to remove the # character that precedes each command.
Changing Script Names The last settings that can affect your ability to run Movable Type for the first time involve the Perl scripts that deliver the software’s functionality. Movable Type scripts end in the file extension .cgi, as in mt.cgi, mt-view.cgi, and mt-xmlrpc.cgi. If you have changed the names of these scripts to make them run successfully — or you want to rename them to enhance system security — six setting commands can be used. The scripts provide the correct names of the main script (AdminScript) and the scripts that support comments (CommentScript), dynamic pages (ViewScript), search (SearchScript), trackback pings (TrackbackScript), and the XML-RPC interface (XMLRPCScript). You use the following commands if all of your scripts have been renamed to use the .pl filename extension: AdminScript mt.pl CommentScript mt-comments.pl SearchScript mt-search.pl TrackbackScript mt-tb.pl ViewScript mt-view.pl XMLRPCScript mt-xmlrpc.pl
Movable Type’s configuration file includes documentation describing each of the settings, so you can read the comments and find other settings that can be modified to suit your particular installation. When you save the file, Movable Type scripts immediately make use of the newly altered configuration settings.
Uploading the Software to Your Web Server After you have set up and saved the configuration file, you’re ready to upload the Movable Type files to the proper places on your Web server. A full Movable Type installation consists of a main directory and eight subdirectories. You will be copying files and directories from this installation to two
42 Movable Type 3 Bible, Desktop Edition separate locations established in the software’s configuration — the CGI path, also referred to as the main directory, and the static Web path. The static Web path holds the Web pages and other files needed by the Movable Type user interface (in other words, the Web site you’ll use to create and manage your weblogs). Upload four things to the directory chosen as your static path: ✦ The docs directory, which contains Movable Type’s user manual ✦ The images directory, which holds user interface graphics ✦ The file styles.css, a Cascading Style Sheet used by the interface ✦ The file mt.js, JavaScript functions for the interface The docs and images directories will become subdirectories of the static path. When uploading files, make sure that your FTP client has been set to upload graphics as binary files and everything else as text. With most clients, this requires only that an auto-detect or auto mode be selected for the transfer. If you have to choose binary or text uploads yourself, transfer the images directory in binary mode and everything else as text. The remaining files and directories should be uploaded to the CGI path directory in which Movable Type’s scripts will be run. When the transfer completes, you should have 16 scripts and the subdirectories extlib, lib, plugins, schemas, search_templates, and tmpl. Finally, create a subdirectory named import — you will need it if you ever import entries and other data into a Movable Type weblog.
Setting Up Security Permissions The scripts in Movable Type’s main directory must be given the proper permissions so that a Web server can run them. Three categories of file permissions — read, write, and execute — apply to three kinds of users: the owner (the creator of the file), a group (associates of the owner), and the world (everyone else). All of the Movable Type scripts, the files included with Movable Type that end with the file extension .cgi, should have read, write, and execute permission for the owner; read and write permission for the group; and read and write permission for the world. At a command-line shell on Linux, you can accomplish this in the Movable Type directory with the following command: $ chmod 755 mt*.cgi
Chapter 3 ✦ Installing Movable Type
43
Using the chmod program, this command changes file access permissions for all of the scripts to the required settings. The argument 755 specifies three permission levels: 7 to make the owner read, write, and execute; 5 to make the group read and write; and another 5 for the world. Most graphical FTP clients also offer a way to set file access permissions. Often, you can view and change a file’s permissions with a client by using a Properties dialog box. On the Windows FTP client WS_FTP Pro, for instance, you can edit file permissions in two ways: ✦ Select the file and choose File ➪ Properties. ✦ Right-click the file and choose Properties from the context menu that appears. With either command, the Properties dialog box opens, as shown in Figure 3-1.
Figure 3-1: Setting file permissions with an FTP client.
Checkboxes turn a specific file permission on or off for each user group. WS_FTP also enables number-based permission values such as 755 to be used. After setting the proper permissions for scripts, you must do the same for the directories that will be used by Movable Type. If you are using Berkley DB or SQLite, the configuration setting DataSource designates a directory in which database files are stored. The default setting uses a db subdirectory of the main directory. This directory should have read, write, and execute permissions for all three user groups, which can be set individually with an FTP client or by using the numeric code 777. When you set up a Movable Type weblog, the first thing you must do is designate directories in which the weblog and its archive pages are stored. Each
44 Movable Type 3 Bible, Desktop Edition weblog is configured to use two directories: the local site path, which holds the home page, XML syndication feeds, and other files; and the local archive path. The same directory can be used for both purposes. The site and archive path directories should be created now on your server for use in the next chapter, “Configuring a Weblog.” They must have the same read, write, and execute permissions as the database directory. These directories can be part of the same directory tree as other Web sites on the server or they can be placed anywhere else that the Web server can access. The only thing to watch for is whether any other software creates files in the same directories. On one of my Linux servers, a Movable Type weblog is stored in two subdirectories of /usr/local/web/cadenhead/, the directory that holds the server’s home page. The local site path is /usr/local/web/cadenhead/movable/ and the local archive path is /usr/local/web/cadenhead/movable/archives/. The following commands set up the directories and the proper permissions: $ $ $ $
mkdir /usr/local/web/cadenhead/movable mkdir /usr/local/web/cadenhead/movable/archives cd /usr/local/web/cadenhead chmod 777 movable movable/archives
With the scripts and directories set up, you’re ready to run two scripts that test your installation and initialize the Movable Type database.
Checking for the Availability of Perl Modules Once Movable Type scripts are in the correct place and permissions have been set, you can check to see whether the software can find the Perl modules that it needs. The system check program mt-check.cgi determines whether the modules are present on the server and functioning properly. Like all Movable Type scripts, the program runs from the software’s CGI path address. To run it, tack the name of the program on the end of the address — my path address is http://cadenhead.org/mt-cgi/, so the following URL executes the system check script: http://cadenhead.org/mt-cgi/mt-check.cgi
The script runs on the Web server and returns its output to your browser, as shown in Figure 3-2.
Chapter 3 ✦ Installing Movable Type
45
Figure 3-2: Looking for Perl modules used by Movable Type.
The script verifies the existence of four modules that Movable Type requires in order to function: CGI::Cookie, File::Spec, HTML::Template, and Image::Size. Two required modules must be specific versions (or later): File::Spec 0.8 and HTML::Template 2.0. Next, the script looks for database modules. Only one needs to be present — the program that corresponds to the database you’re using with Movable Type. A Berkeley DB database requires DB_File, MySQL needs DBD::mysql, PostgreSQL uses DBD::Pg, and SQLite uses DBD::SQLite. More than one can be present; there’s no need to remove a module that isn’t being used. If the check script can’t find one of the required modules or the database module matching your installation, you must correct this problem by installing the missing module, as described in Chapter 2, “Preparing a Web Server for Movable Type.” Rerun the system check script afterwards to verify the module’s successful installation.
The last module check performed by the script accounts for optional modules that are useful to have around but do not impede the software from working correctly. Movable Type employs nine optional modules: Crypt::DSA, File::Temp, HTML::Entities, Image::Magick, LWP::UserAgent, MIME::Base64, SOAP::Lite, Storable, and XML::Atom. When an optional module is not present or can’t be found, some functionality of the software might not be available. For instance, the Image::Magick module creates thumbnail graphics of uploaded graphics files. If your installation of Movable Type lacks this module, you won’t be offered a chance to create thumbnails during an upload.
46 Movable Type 3 Bible, Desktop Edition The XML::Atom module, written by Movable Type developer Ben Trott, adds support for the Atom Application Programming Interface (API), enabling the software to be controlled externally by software such as weblog editors and Web services. You’ll get a chance to put this functionality under the microscope in Chapter 19, “Supporting the Atom Syndication Format and API.”
Initializing the Software Now that Movable Type is ready to go, the next script to load in the browser is the system loader program, mt-load.cgi, which initializes the software. Add the script name to your CGI path and load the URL with your browser. This script sets up the software’s database with 16 tables, creating default records, establishing an initial weblog called First Weblog, creating a sample user, and filling it with 16 Web page and file templates. The status of database initialization appears on the page as each step in the process completes, ending with a System Initialization Complete message that indicates success (see Figure 3-3).
Figure 3-3: Setting up database records for a new Movable Type installation.
If the script cannot run successfully because it cannot access the database or some other problem occurs, you’ll see an error message. Fix the error and reload the page to run the script again. After you have run the script successfully, you should immediately delete mtload.cgi. You won’t need it again, and leaving the script online poses significant security vulnerability. (An older version of Movable Type was exploited using this script and had to be patched.)
Chapter 3 ✦ Installing Movable Type
47
With the initialization complete and the database set up with your first weblog, Movable Type is fully installed and ready to go.
Summary Reaching this point in a Movable Type installation represents a significant accomplishment, especially if this is your first server-based application. Movable Type consists of Perl scripts and module libraries, Web pages, graphics, Cascading Style Sheets, and JavaScript functions — none of which can be installed in the kind of user-friendly manner most of us have come to rely on in our graphical Windows, Linux, and Mac OS computers. If you were able to run Movable Type’s system loader script in your Web browser and see a System Initialization Complete message, you’ve finished installing the software and it functions correctly. Once the software has been installed and verified, you’re ready to begin working on your first weblog, changing the default settings that were created by Movable Type during the software’s installation. Most of the fine-tuning you’ll be doing in Movable Type beyond this point will take place in a Web browser. You might occasionally make changes to the configuration file mt.cfg as you work with advanced features of the software in upcoming chapters.
Configuring a Weblog
4
C H A P T E R
✦
N
✦
✦
ow that all of the preliminary work has been completed, there’s a functioning Movable Type installation on your Web server that’s itching to be run for the first time.
In This Chapter
One of the strengths of a server-based publishing tool is that you can work on it anywhere your server can be reached. With Movable Type on a publicly available Web site, you can update your weblogs from any computer with an Internet connection and a browser, even down to the nitty-gritty work of designing templates, rebuilding pages, and changing your configuration.
Making graphics display correctly
Although this availability can be a curse as well as a blessing — a May 27, 2004, New York Times article described a zealous weblogger who offered new updates while vacationing on the beach — Movable Type follows you around. Before you run Movable Type for the first time, there’s already an author and weblog in the database. A user named Melody has a site called, imaginatively enough, First Weblog, with a default design that you can adopt as you are learning how to work with the software. This user and weblog can be customized quickly so you can begin publishing your first site. They should be customized quickly, because Melody has a password that’s known to every other Movable Type user on the planet.
Running Movable Type for the First Time Movable Type runs by loading the main script, mt.cgi, with a Web browser that has JavaScript functionality turned on.
✦
Running Movable Type’s main script
Logging in for the first time Changing your username and password Choosing a home page URL Setting up the site directories Buying a software license Sharing your content under a copyright license Creating accounts for your co-authors Tracking usage of the software
✦
✦
✦
✦
50 Movable Type 3 Bible, Desktop Edition To run mt.cgi, tack the script’s name to the end of your CGI path, as in http://cadenhead.org/cgi-bin/mt.cgi, and fire up the software. You should see a login screen with a graphical Movable Type logo (see Figure 4-1).
Figure 4-1: Logging in to Movable Type.
If you don’t see the logo graphic, your static Web path probably has not been set correctly. Edit your configuration file and make sure that the StaticWebPath setting refers to the directory that holds the docs and images subdirectories and the file mt.js. A common error when editing this file is to omit a trailing slash mark. Here’s the setting on my server: StaticWebPath /movable/static/
Who Is Melody Nelson? One of the first things a new Movable Type user wants to know: Who is Melody Nelson, and why does this woman have an account on my software? In 1971, the French pop singer Serge Gainsbourg released Histoire du Melody Nelson, an album written from the perspective of a man obsessed with a young woman named Melody Nelson. She becomes his lover and muse, and then dies tragically in the grand tradition of rock opera. Ben and Mena Trott are Gainsbourg fans who originally planned to call their software Serge. Although the name changed, they kept the muse around as their new user account and christened the company’s main Internet server serge.sixapart.com. Melody’s not the only fictional person hanging around popular weblogging software. Radio UserLand and Manila contain references to Bull Mancuso, a toughtalking private investigator who solves difficult software problems.
Chapter 4 ✦ Configuring a Weblog
51
When you change this setting and save the file, you can reload the main Movable Type script in your browser to see whether the logo appears. Fix this problem before proceeding; the software’s graphical menu icons and other parts of the interface require a proper static path. Once you see the graphics, you can log in using an account that has been set up for you: Use the username Melody and the password Nelson. A page displays First Weblog, a new weblog you can set up to your exact specifications.
Setting Up Your Account The Melody account has full access to all features of the software. You can create and delete weblogs, add users and grant them capabilities to work on your sites, and handle all other tasks required to publish. Movable Type presents newly logged in users with the Main Menu page, which contains a list of weblogs to edit, news announcements from Six Apart, and shortcuts to frequently used features. This page appears in Figure 4-2.
Figure 4-2: Browsing the software’s Main Menu.
The first thing you should do is change the username and password of your account. Until you do, anyone who runs Movable Type will be able to log in to your installation of the program. To make changes to your user account, click the Melody link, which can be found at the upper-right and is circled in Figure 4-2. This opens a form page containing your username and other settings.
52 Movable Type 3 Bible, Desktop Edition Four of these settings can be displayed on your weblog in Web pages and syndication files: the account’s username, nickname (or full name), e-mail address, and home page URL. Choose a new password, typing it in both the Password and Password Confirm text fields. Because anyone using the Internet can attempt to log in to your Movable Type installation, it’s important to choose a good password that can’t be guessed or discovered by password-cracking software. Ideally, your password should be at least eight characters and contain letters, numbers, and punctuation. You can achieve even better security by mixing uppercase and lowercase letters and avoiding dictionary words. The Remote Authentication section of the form looks for Atom and TypeKey authentication tokens. You don’t need to set these now; they’ll become important later as you work with visitor comments and Atom publishing formats (topics covered in Chapter 10, “Offering Comments,” and Chapter 19, “Supporting the Atom Syndication Format and API”).
Scroll to the bottom of the page and click Save to commit your changes to the database. The link to your username at the upper-right will change from Melody to your newly chosen name. Click that link at any time to make changes to your account. The Main Menu link atop the page returns you to that page. From now on, log in with your newly chosen username and password.
Creating Your First Weblog Movable Type can be used to publish multiple weblogs authored by yourself and other people to whom you’ve given accounts. The weblogs will be listed on the Main Menu page. You can click a weblog’s name to load its main editing page or use the accompanying list linking to common tasks. Assuming that you don’t like the name “First Weblog,” you can make immediate changes to the new site from the Main Menu: In the link list along the right edge of the First Weblog section, click the Edit Configuration link. The Core Setup page appears (see Figure 4-3). Title your site in the Weblog Name field. You can change it at any time without hassle — Movable Type’s template-based publishing system grabs the name automatically, reflecting any change immediately upon the next publication of the site.
Chapter 4 ✦ Configuring a Weblog
53
Figure 4-3: Configuring a weblog.
The next four settings, which you must configure in order for the weblog to work as desired, are some important directories and URLs: ✦ Site URL: The address of the weblog’s home page (without a filename) ✦ Archive URL: The address of the weblog’s main archive page (also without a filename) ✦ Local Site Path: The directory on the Web server where the home page and other important documents should be stored ✦ Local Archive Path: The directory on the server where archive pages should be stored A weblog can use the same address for the site and archive URL and the same directory for both local paths or different settings for each. The default settings are based on the server hosting Movable Type and how the software was configured in the mt.cfg file. You don’t have to use any of these suggestions. I used the following four settings for Orlando Vacationer, a travel and tourism weblog that appears in examples throughout the remainder of this book: ✦ Site URL: http://www.orlandovacationer.com/ ✦ Archive URL: http://www.orlandoavacationer.com/archives/ ✦ Local Site Path: /var/www/orlandovacationer.com/html ✦ Local Archive Path: /var/www/orlandovacationer.com/html/ archives
54 Movable Type 3 Bible, Desktop Edition
Setting Up Path Directories Movable Type does not create and set up the site and archive path directories; you must do this yourself through a command shell, FTP client, or some other means of connecting to your Web server. These directories can be part of the same directory tree as other Web sites on the server, but you should give Movable Type weblogs their own subdirectories to avoid overwriting files created by other software (or vice versa). The site and archive path directories should allow full read, write, and execute permissions. Using my own Orlando Vacationer site as an example, the following commands set up the directories and the proper permissions: $ mkdir /var/www/orlandovacationer.com/html $ mkdir /var/www/orlandovacationer.com/html/archives $ cd /var/www/orlandovacationer.com $ chmod 777 html html/archives
Note that both URLs end with a trailing slash character (/ ) and the local paths do not. The paths are on a Linux server; a Movable Type installation running on Windows will reference directories differently. The last setting to select on the Core Setup page is the time zone that will be used on all timestamps on the site. Select the desired zone and click Save Changes. The page reloads with a yellow message box stating that you can rebuild the site to see your changes reflected on the weblog. There’s no reason to do this yet; your weblog is empty so there’s nothing useful to publish. You can return to the Core Setup page by clicking the Weblog Config button on Movable Type’s sidebar menu. Although you don’t need to make any more changes to begin working on your weblog, there’s one more setting on another configuration page that ought to be set up at this time. In the list of links atop the Core Setup page, click the Preferences link to open that page. The Description text box provides a place for a tagline or slogan that succinctly explains the content or purpose of the weblog. This description can be displayed with the title, presented in a sidebar, and promoted in other ways. When you’ve set a suitable description, scroll to the bottom of the page and click Save Changes.
Chapter 4 ✦ Configuring a Weblog
55
Licensing Your Software Six Apart offers a variety of licenses for Movable Type, including a limited personal version that can be used at no cost. Which license you choose depends on whether you use the software for commercial or personal projects, how many weblogs you publish, and the number of co-authors who work on those sites. For a full list of licenses and pricing, visit the Six Apart Web site at http://secure.sixapart.com. Table 4-1 describes the licenses, user privileges, and current prices.
Table 4-1 Movable Type Licensing Options License Type
Maximum Authors
Maximum Weblogs
Price
Personal
1
3
Free
Personal
5
Unlimited
$69.95
Personal
Unlimited
Unlimited
$99.95
Commercial
5
Unlimited
$199.95
Commercial
10
Unlimited
$349.95
Commercial
20
Unlimited
$599.95
Commercial
35
Unlimited
$999.95
Commercial
50
Unlimited
$1,299.95
Individuals using Movable Type for noncommercial purposes qualify for a personal license. Companies, organizations, and individuals setting up Movable Type for clients require a commercial license instead. With the exception of the free version, all Movable Type licenses come with the following perks: ✦ Downloads of Movable Type versions 3.0 and 2.661 ✦ Customer support from Six Apart ✦ Promotion on the Six Apart site’s Recently Updated list of weblogs Free users can still get customer support from other Movable Type users on the support forums at the Six Apart site.
56 Movable Type 3 Bible, Desktop Edition When you buy a license for Movable Type, you are asked whether you wish to download the full version or upgrade version of the software. This isn’t necessary if you already have a functioning installation of the current version, as the download is identical to the one you’ve already set up. Otherwise, you can snag the upgrade to bring the software up to date. After you have paid for a license via an online credit card payment, you can visit your Movable Type account page at https://secure.sixapart. com/t/account. This page offers customer support, software downloads, and your Update Key, an alphanumeric code that includes your weblog on Six Apart’s list of recently updated weblogs.
The Update Key should be stored in the configuration of one weblog that you want to promote. When you’re ready to start calling attention to your site, here’s how to set up the key: 1. Copy the Update Key from your Movable Type account page. 2. On the Main Menu page, click the weblog’s Edit Configuration link. The Core Setup page appears. 3. Click the Preferences link to open that page. 4. Click the Publicity / Remote Interfaces / Trackback link. The page jumps down to that section. 5. Enter the key in the Recently Updated Key field. 6. While you’re here, two other configuration settings cause your site to appear on an update list. In the Notify the Following Sites When I Update My Blog section, enable the blo.gs and weblogs.com checkboxes. 7. Scroll to the bottom of the page and click Save Changes. Each time you publish a new entry, the weblog should show up in the Recently Updated section of the Movable Type home page at http://www.movabletype.org. Because Six Apart has thousands of paying customers, your link is likely to scroll off the list after a few minutes.
Adopting a Creative Commons License Movable Type generates weblog content in a wide variety of formats (and can easily support more). A newly created weblog publishes entries as Web pages and three other kinds of files: Atom, RSS 1.0, and RSS 2.0 newsfeeds. You can see the templates and names of these files by clicking the Templates button on the software’s sidebar menu. Newsfeeds are structured XML data in a form easily parsed by software. These feeds make it possible for your work to be read outside of a Web browser
Chapter 4 ✦ Configuring a Weblog
57
using client software called a newsreader, a highly popular way to follow weblogs, news headlines, and other regularly updated sites. This process has come to be known as site syndication because of another use for newsfeeds: sharing content from your site so that it can be republished in whole or in part elsewhere on the Web. This practice is extremely commonplace today. Because you’re making newsfeeds available, you ought to decide as soon as possible what kind of publishing and redistribution you are willing to permit. The Creative Commons organization was formed in 2001 to encourage publishers, artists, and others to share their copyrighted work under licenses that safeguard their interests while encouraging others to make use of the material. You can read about its licenses on the Web at http://creativecommons.org/ learn/licenses. To encourage sharing, the group offers several Creative Commons licenses that indicate how much, or how little, you want to share. These licenses have been adapted for use in syndication feeds and are supported in Movable Type. You can choose a license in your site configuration settings, which is then applied to your weblog’s pages and syndicated newsfeeds. Creative Commons has resulted in a lot of innovative collaboration that wouldn’t be possible otherwise, but you shouldn’t jump into it too quickly. Before adopting a license, take the time to understand the ramifications of a Creative Commons license. Once you make your work available under a license and someone begins re-using it under your terms, you cannot revoke the license for that material. The most you can do, if you experience a subsequent change of heart, is choose another license for anything you create from that point forward.
When choosing a Creative Commons license, the first thing to decide is whether to permit others to reuse your work for commercial purposes or limit it to noncommercial use. If you impose a noncommercial restriction, the following term applies to the license: “The licensor permits others to copy, distribute, display, and perform the work. In return, licensees may not use the work for commercial purposes — unless they get the licensor’s permission.” Next, you must decide whether to allow others to make their own changes to the work and redistribute them. You can allow this, disallow this, or allow it only if they make their new work available under the same terms that you did. This last term, described as a ShareAlike policy, is worded as follows: “The licensor permits others to distribute derivative works only under a license identical to the one that governs the licensor’s work.” The licensor permits others to copy, distribute, display, and perform the work. In return, licensees cannot use the work for commercial purposes — unless they get the licensor’s permission.
58 Movable Type 3 Bible, Desktop Edition If you don’t apply a license to your weblog, normal copyright law applies. In the U.S. and many other nations, you don’t even need to put a copyright statement on your site or in syndication feeds; your work is copyrighted automatically upon creation. If you want to adopt a Creative Commons license in your weblog, follow these steps: 1. Click the Edit Configuration button on the Main Menu page (or the Weblog Config button on the sidebar menu). 2. Click the Preferences link. 3. Scroll down to the Creative Commons License section and click the Create a License Now link. A pop-up window asks for the terms of the license you have chosen. 4. Answer the licensing questions, and then click the Select a License button. 5. The name of the Creative Commons license you have selected is displayed along with the address of a Web page containing the license. Click Proceed. 6. The Preferences page is redisplayed with your choice of license in the Creative Commons License section. 7. To save your configuration, scroll to the bottom of the page and click Save Changes. By returning to the Creative Commons License section of this page, you can change or remove the license. The license you have chosen will be reflected in the Web page and RSS 1.0 newsfeed. Hidden text is added to the home page, taking the following form: Orlando Vacationer Disney discounts, park perks, tourist tips -->
Chapter 4 ✦ Configuring a Weblog
59
This text is formatted as RDF, an XML dialect used to provide reference information about Internet content such as the author and copyright. The following line appears in the RSS 1.0 newsfeed, which also makes use of RDF:
You can learn how to add Creative Commons licensing to RSS 2.0 and Atom files in Chapter 18, “Publishing RSS and Atom Syndication Files,” and Chapter 19, “Supporting the Atom Syndication Format and API.”
Adding Other Authors to a Weblog Although a Movable Type installation begins as a solitary project, it doesn’t have to stay that way. As the software’s licensing indicates, a single installation of Movable Type supports multiple weblogs and authors. Any of the paid personal or commercial licenses can be used for collaboration, from the five-author personal license up to the 50-author commercial license. Each Movable Type weblog can be assigned a different author or combination of authors. A role-based permissions system dictates the specific tasks an author can perform on a per-weblog basis, making a wide range of access possible — from highly trusted users who can do everything you can do with the software, even to the point of adding new weblogs and user accounts, to more limited users who can edit only their own entries. When setting up an author’s contact information, consider the fact that the person’s e-mail address and home page will be shared with the public in the weblog’s Atom newsfeed and might appear elsewhere on the site. Sharing an e-mail address publicly on a Web site brings an increase in unsolicited junk mail as spam-harvesting software finds the site and saves all addresses that it detects. If your co-authors are concerned about this, they should set up a free e-mail account on a service such as Yahoo, Google Gmail, or Microsoft Hotmail and use that instead of their regular address. There are two permissions you can grant a user that apply to the entire installation: the capability to create new weblogs and view the activity log, a list that tracks how the software is being used. The remaining permissions are granted on a per-weblog basis. The following roles can be permitted or denied to each author: ✦ Configure Weblog: Modify any of the weblog’s settings. ✦ Edit Address Book: Add and remove e-mail addresses from the site’s notification list.
60 Movable Type 3 Bible, Desktop Edition ✦ Edit All Posts: Revise weblog entries, even if other authors wrote them. ✦ Edit Authors & Permissions: Set permissions for any author of the weblog. ✦ Edit Categories: Add and remove weblog entry categories. ✦ Edit Templates: Add, remove, and change the templates used to generate all weblog pages and other files. ✦ Post: Write entries and edit them as needed. ✦ Rebuild Files: Republish all of the files that comprise the weblog. ✦ Send Notifications: Send e-mail about a new entry to the site’s notification list. ✦ Upload File: Transfer graphics and other files to the server. As you’re starting out with Movable Type’s collaboration features, one safe approach is to enable new authors with just the Post and Rebuild Files roles. They’ll be able to contribute entries to the weblog and make changes to them as needed, but the rest of the weblog’s functionality will be your domain. The Edit roles should be granted only to authors who are comfortable with Movable Type and can be trusted completely. These roles could be used to wipe out the entire weblog and the templates that create all of your content, leaving no way to restore the site unless you back up the data regularly (as described in Chapter 12, “Backing Up a Weblog”). When you’re ready to add an author, perform these steps: 1. If you aren’t there already, click the Main Menu link atop any page. 2. In the Shortcuts section, click the Add/Edit Weblog Authors link. The Authors & Permissions page opens in the browser. 3. Choose a username, password, and e-mail address for the user. Although you can provide a URL, your co-author can just as easily set that up later (or decide to omit it). 4. Click Save. The user’s permissions page opens, as shown in Figure 4-4. 5. The General Permissions section applies to all weblogs. Enable the checkboxes of the roles the author can perform. 6. The rest of the permissions are organized by weblog. Enable the checkboxes for the desired roles on that site. 7. To add an author to a weblog, select it in the Add User to an Additional Weblog drop-down menu at the bottom of the form and click the Add button (not shown in Figure 4-4). 8. Make these changes permanent: Click Save.
Chapter 4 ✦ Configuring a Weblog
61
Figure 4-4: Setting an author’s permissions.
Keeping an Eye on the Software’s Activity Logs Movable Type Web sites are published as static Web pages and other files, so the use of your weblogs can be tracked with the same log analysis programs you use on other sites. If you have a program such as Urchin, Webalizer, or WebTrends, you can continue to use it to find out how your weblogs are being accessed. There’s also an activity log in Movable Type that tracks how the software is being used, as you can see in Figure 4-5.
Figure 4-5: Monitoring Movable Type usage.
62 Movable Type 3 Bible, Desktop Edition To check the software’s log, on the Main Menu page, click the View Activity Log link in the Shortcuts section. The log tracks five kinds of information: ✦ Users logging in and logging out ✦ The publication of new entries ✦ Comments rejected because users post too quickly ✦ Errors sending messages to other sites ✦ Site searches Movable Type has a message-throttle feature that prevents someone from flooding your weblog with comments, either intentionally or accidentally. The ThrottleSeconds setting in the software’s configuration file, mt.cfg, controls how often a comment can be submitted from the same IP address. The default is to reject a comment if fewer than 20 seconds have elapsed since the last comment was posted from that address. This shows up as a “Throttled comment attempt” in the activity log. Ping messages in the log relate to failed efforts to contact weblogs.com, blo.gs, or some other site that tracks recently updated weblogs. You can notify these sites each time you publish an entry. The ping errors require no corrective action on your part. The most common cause is a “read timeout” when one of the servers can’t be contacted, which happens from time to time because they are extremely popular. Web servers collect a lot more information on site usage than the small amount of data presented in Movable Type’s activity log. You can find out which pages are requested most often, what sites send the most visitors through hyperlinks, what browsers are most popular, and what errors have taken place (such as missing pages, broken links, and the like). Server analysis software must be run independently of Movable Type and might require special configuration in your Web server. Use the following links to find out more about some of the leading Web server analysis programs: Analog: http://www.analog.cx Urchin: http://www.urchin.com Webalizer: http://www.mrunix.net/webalizer WebTrends: http://www.netiq.com/webtrends
Chapter 4 ✦ Configuring a Weblog
63
Summary The introduction to this chapter mentioned an extremely dedicated weblogger who composed new entries from the beach. That sunbathing blogger is Richard Wiggins, who writes Wigblog on technical topics such as search engines and weblogging software at http://wigblog.blogspot.com. The New York Times photographed him working wirelessly from a beach chair in Key West, Florida, alongside a line of swimsuit-clad vacationers. “It seems as if his laptop is glued to his legs 24/7,” his wife, Judy Matthews, told a reporter. Although Wiggins uses another server-based publishing tool, Movable Type could just as easily be a source of curiosity and exasperation to your loved ones. If you can get an Internet connection and your installation of the software runs on a public server, you can take your personal or professional weblog anywhere you go. In the next chapter, “Writing a Weblog Entry,” you’ll begin creating content for your new site. Whether it becomes as habit-forming as Wigblog and hundreds of other zealously updated weblogs is up to you. Or, as I tell myself when I spend an extra hour at the computer updating my own weblog, I can quit at any time.
Writing a Weblog Entry
5
C H A P T E R
✦
D
✦
✦
✦
epending on who you ask, weblogs are either a full-fledged revolution in how people get information on the Internet or the latest in a long line of dreadfully overhyped dot-com fads.
In This Chapter
As the author of several books on weblog software and an active weblogger, my vote leans heavily toward revolution, which can’t be much of a shock.
Composing a new entry
The format of weblogs was not novel when Michael Sippey, Harold Check, Dave Winer, and other pioneers began publishing these sites in the late ’90s and a new term was coined to describe their work. Since the beginning of the Web, many sites have presented lists of links, online journals, and other chronologically ordered content, with the newest material presented first. However, as this style of heavily linked, spontaneous communication became popular and was supported by software like Movable Type, a community of webloggers that originally numbered in the dozens became a horde of thousands, publishing frequently, linking to each other, collecting information on the Web, and sharing their findings. The resulting network of webloggers, perhaps as large as a million today, dramatically changed the dissemination of news and other timely information. In the July 3, 2002, Wall Street Journal, Peggy Noonan called weblogs the “most thoughtful, most strange” form of free speech. “Thousands of independent information entrepreneurs are informing, arguing, adding information. . . Blogs may one day become clearinghouses for civil support and information when other lines, under new pressure, break down.” You become a part of that strange network when you pen your first weblog entry in Movable Type.
Simplifying the weblog editing form
Using excerpts and keywords Publishing the site Writing article-length weblog entries Adding fields to the editing form Choosing default settings for new entries Receiving comments and trackback pings Creating a QuickPost link
✦
✦
✦
✦
66 Movable Type 3 Bible, Desktop Edition
Using the Weblog Entry Form All weblog content that you create with Movable Type can be written in a JavaScript-enabled Web browser over any Internet connection. Run Movable Type’s main script by loading its URL, log in with your username and password, and publish your site from anywhere in the world. Movable Type collects 11 kinds of information for each weblog entry on the entry-editing form, most of which relates to the text of the entry in some manner. As you begin using the software, you might find it easier to switch to a simpler form that contains the most important fields: 1. Click the New Entry button in the sidebar menu. The entry-editing form appears. 2. At the bottom of the form, click the Customize the Display of This Page link. A Field Configuration page opens in a separate browser window. 3. Choose the Basic configuration option, and then click Save. The editing form reopens with only four fields (see Figure 5-1).
Formatting buttons Title
Entry Body
Post Status
Save
Figure 5-1: Using a simplified entry-editing form.
Chapter 5 ✦ Writing a Weblog Entry
67
In Movable Type, a weblog entry at its simplest consists of a title and entry body. The title, succinct text with no links or other HTML formatting, appears as the heading for the entry on the weblog’s home page and in the page title for the entry’s individual archive. You can change how and where the title appears by editing the weblog’s templates. The entry body can be one or more paragraphs of text separated by blank lines. Buttons along the top edge of the Entry Body text box insert hyperlinks into the text and apply three formatting styles to selected text: boldface, italics, and underlining. When you’re composing an entry, you see the HTML markup used to present the text. If you are comfortable writing your own HTML tags, you don’t have to use the formatting buttons found on the top edge of the Entry Body text area (indicated in Figure 5.1). As you compose an entry, you don’t need to mark up paragraphs with p tags, the HTML markup tag functioning as paragraph separators. Movable Type’s text formatter adds these tags automatically, using blank lines to determine where paragraphs begin and end. When you have finished composing an entry and are ready to publish it on your weblog, change the Post Status drop-down menu from Draft to Publish and click the Save button. Movable Type publishes the weblog entry in several places: ✦ The weblog home page (index.html) ✦ Three XML syndication files in Atom (atom.xml), RSS 1.0 (index.rdf), and RSS 2.0 (index.xml) formats ✦ An individual archive page containing the entry ✦ A monthly archive page containing all entries from the current month The weblog entry composed in Figure 5-1 can be seen in published form in Figure 5-2. The default weblog templates determine the actual appearance of the page.
68 Movable Type 3 Bible, Desktop Edition Title
Entry Body Figure 5-2: Presenting a weblog entry on a Web page.
Listing 5-1 shows how the entry appears in the weblog’s RSS 2.0 feed, a file structured as XML so that it can be read easily by software.
Listing 5-1: A Weblog Entry in RSS 2.0 Mission: Space Hard to Stomach http://orlandovacationer.com/archives/2004/06/mission_space. html Airsick bags have been added to Mission: Space at Epcot, solidifying its reputation as the Disney World attraction most likely to make people lose their lunch. As Theme Park Insider writes: Many within the company felt the thrill ride was... http://orlandovacationer.com/archives/2004/06/mission_space. html Wed, 09 Jun 2004 07:57:39 -0500
Chapter 5 ✦ Writing a Weblog Entry
69
Movable Type can represent a weblog entry in an unlimited number of formats, making it possible to offer different versions of your Web site for different audiences. You can offer a graphically rich site for viewing by Web users on desktop computers with fast Internet connections, a simpler text site for mobile phones and other wireless devices, and syndicated Atom and RSS feeds for people who use news aggregators to check their favorite sites for updates. The weblog home page and syndication files are produced from index templates, a set of templates that produce content in the weblog’s main directory. You learn how to make changes to these files in Chapter 8, “Producing Web Pages with Template Tags.”
After an entry has been published, you can make changes or delete it as needed: 1. Click the Entries button in the sidebar menu. The List & Edit Entries page opens. 2. Click the title of the entry to edit. The entry-editing form opens, filled out with the text entered previously. 3. To pull the entry off the weblog for more editing, change the Post Status drop-down menu to Draft. 4. Click Save to finalize your changes. Movable Type produces Web content by rendering static Web pages and other files from an external database. The software calls this rendering process rebuilding the site, and it happens automatically when a new entry is written or an entry is edited. Some changes require that the weblog be explicitly rebuilt: 1. Click the Rebuild Site button in the sidebar menu. A pop-up window asks which pages should be rebuilt, as shown in Figure 5-3.
Figure 5-3: Publishing a site by rebuilding files from templates.
70 Movable Type 3 Bible, Desktop Edition 2. To republish the entire site, a process that can take 5–15 minutes or longer on a large weblog, choose Rebuild All Files from the drop-down menu. 3. To republish index templates, choose Rebuild Indexes Only. 4. To republish the weblog’s archive pages, choose Rebuild Individual Archives Only or Rebuild Monthly Archives Only. 5. Click Rebuild. Movable Type provides progress messages as a weblog is being rebuilt. Every aspect of the editorial process in Movable Type can be customized. You can change the fields that appear on an entry-editing form, making the form simpler or more complex based on the kinds of information you want to collect, and alter the presentation of the entry by editing the index and archive templates. The net result is a content-management tool that goes beyond simple weblog editing, enabling other kinds of Web sites to be produced. Movable Type 3.0 adds a new feature for plug-in developers that makes the software even more extensible. With object callbacks, you can create Perl scripts that are notified when something is loaded, stored, or deleted from the database. Chapter 21, “Hooking into Movable Type with Callbacks,” provides the full details.
Writing an Entry The entry-editing form’s basic configuration serves a useful purpose, enabling new and technically inexperienced weblog authors to begin creating their own entries quickly. As you become comfortable with the software, you can accomplish a lot more with an editing form that contains all of the options: 1. Click the New Entry sidebar menu button to open the entry-editing form. 2. Scroll to the bottom and click the Customize the Display of This Page link. A Field Configuration page opens in a separate browser window. 3. Choose the Custom configuration option. This section includes a checkbox for each field that can be added to the editing form. 4. Enable all of the checkboxes in the Custom section, and then click Save.
Chapter 5 ✦ Writing a Weblog Entry
71
The significantly larger editing form reopens. (Figure 5-4 shows the options on the bottom half of the form.) This entry-editing form includes three additional fields that can be used to customize the content of a weblog entry: Excerpt, Extended Entry, and Keywords. The Excerpt field defines a summary or excerpt, which can be as long or as short as necessary. When left blank, the excerpt becomes the first 40 words of the entry body followed by an ellipsis (...).
Figure 5-4: Using the full entry-editing form.
The Keywords field provides a place where you can define a comma-separated list of terms that apply to the entry or use any other means to describe the content of the entry. This text isn’t presented in any files produced by Movable Type’s default templates. Instead, it helps people using the site’s search feature — keywords will be searched along with the other text of the entry. The weblog entry composed in Figure 5-4 does not contain the words “thrill rides.” Because they appear in the list of keywords, a search query for that term will produce a link to the entry. The Authored On field, one of the advanced editing settings shown at the bottom of the form in Figure 5-4, contains a timestamp representing the time the entry was first published. By editing this value, you can create entries for the past or the future.
72 Movable Type 3 Bible, Desktop Edition To set up an entry that won’t be published until a set date and time, change the Authored On date to that future timestamp. The first time the site is rebuilt after that time, the entry will be published. Change Authored On to a past date and time to store it in the weblog at that timestamp. Movable Type organizes entries in reverse chronological order, so after you save the changed entry, it will move from the top of the Edit Entries list to the position established by the new timestamp. The Authored On date must have the format YYYY-MM-DD HH:MM:SS. In order, the letters represent a four-digit year and a two-digit month, day of the month, hour, minute, and second. For example: 2004-07-10 12:20:00. The Primary Category field is covered during the next chapter, “Organizing a Weblog.”
Gotcha
Movable Type doesn’t provide an entry field for an external link, which is a hyperlink leading off the weblog to another Web site. There’s an entry called a permalink that can be presented in templates, but it’s associated with individual archive pages for each entry. You can work around this situation by using the Keywords field for this purpose, as long as you’re willing to forego the use of search keywords.
Dividing Entries into Two Fields The Extended Entry field makes it possible to split an entry over two fields instead of putting it in the Entry Body field, thus creating weblog entries that consist of two parts: a body and an extended body. An entry can be split over two fields at your discretion. You could designate the first paragraph of an entry as the body and the rest as the extended body, put up to 500 words in the body and the rest in the extended body, or any other technique that suits your needs. When an entry has been divided in this manner, the entry body appears on the home page and most archive pages, followed by a “Continue reading...” link that can be used to read the rest, as shown in Figure 5-5. The “Continue reading...” link opens the individual archive page for the entry, which contains the entry body followed by the extended entry, presented as a seamless whole. All other archive pages divide entries in the same manner as the home page. Because there’s no limit on the size of the Entry Body field, you might view it as needless work to split an entry over two fields.
Chapter 5 ✦ Writing a Weblog Entry
73
Figure 5-5: Reading a divided weblog entry.
For a weblog with entries that never run more than a few paragraphs, this division probably is more work than necessary. If you’re comfortable with running the full text of all weblog entries on a site’s home page and archive pages, you can use the Entry Body field and remove the Extended Entry field from the editor: 1. On any entry-editing form, click the Customize the Display of This Page link below the form. The Field Configuration page pops up in its own window. 2. With the Custom option selected, remove the check next to the Extended Entry field and click Save. Removing a field from the entry-editing form does not delete any existing weblog content that appears in that field — it just takes away the capability to view or change that part of an entry. On existing entries that contain extended entries, the text still appears on the entry’s individual archive page when the site is republished. Movable Type’s separation of entries into two fields comes into its own when you want to break out of the weblog mold and create other kinds of articles, essays, and pages with the software. Although Movable Type is accurately described as a weblog editing tool, you can employ the software to publish any Web content that makes sense to organize chronologically, such as newspapers, online magazines, family photo albums, and sites for teams collaborating on a project.
74 Movable Type 3 Bible, Desktop Edition When you are using the software to create articles and other work longer than a few paragraphs, the entry-editing form can be used in the following manner (see Figure 5-6): ✦ Title defines the headline. ✦ Entry Body holds the lead paragraph (or paragraphs). ✦ Extended Entry contains the rest of the body text. ✦ Excerpt holds a summary, which can be the lead or something even more succinct. ✦ Keywords lists search terms that apply to the piece. With support for multiple authors and the organization of a weblog into categories, Movable Type can be an effective content-management system for sites that aren’t weblogs by any stretch of the definition.
Keywords Title
Excerpt
Extended Entry Figure 5-6: Publishing articles and other longer text.
Entry Body
Chapter 5 ✦ Writing a Weblog Entry
75
Setting Default Values for the Editing Form The remaining fields on a full entry-editing form specify how an entry is published, whether it accepts feedback, and sites that should be notified to publicize your work. These fields, shown earlier in Figure 5-4, are all part of the weblog configuration, which you can edit with the software’s browser interface. When one of these fields is removed from the editing form, the configuration setting is used by default. For example, the post status of a newly written entry can be either Draft, which stores the entry in the database without publishing it, or Publish, which stores and publishes it at the same time. If you set the configuration to a default status of Publish and remove the Post Status field from the editing form, all new entries are published automatically when they are saved. The Comments and Accept Trackback Pings fields determine whether feedback is accepted for an entry. A Movable Type weblog can accept visitor comments and trackback pings in response to each entry, publishing them after the entry on its individual archive page. You can decide whether to offer these features for an entire weblog or set them on an entry-by-entry basis. An entry’s Comments field can be set to Open (accept comments), None (do not accept them), or Closed (stop accepting comments). The third setting is used to conclude discussion of an entry at some point. Trackback pings are a form of feedback between different weblogs, a novel technique developed by Six Apart that’s explored fully in Chapter 11, “Sharing Trackback Links.”
When another weblog contains a reference to an entry on your site, Movable Type can be notified about this event through the use of a trackback ping — a message transmitted from one weblogging software tool to another. Movable Type can accept trackback pings for each entry. The Accept Trackback Pings checkbox can be either enabled to take pings or disabled to ignore them. The URLs to Ping text box makes use of trackback pings in the opposite direction. If you know the Web address (URL) of a server that should receive a ping related to your entry, you can place it in the box. For more than one ping, put each URL on its own line.
76 Movable Type 3 Bible, Desktop Edition When the entry is published, trackback pings are sent to each URL. As you learn in Chapter 11, pings also can be sent automatically to any weblog that you link to in an entry.
Formatting Text for Publication A weblog entry’s Text Formatting setting determines whether a text formatter converts the entry text. A text formatter is a Movable Type module that transforms text for presentation on the Web. Earlier in this chapter, you learned that it isn’t necessary to put HTML p tags around each paragraph when you’re writing an entry. You can omit these because the software’s default text formatter, Convert Line Breaks, adds paragraph tags and line breaks. In a Movable Type entry, text separated by blank lines is converted into paragraphs with opening p and closing p tags. Other blocks of text have br tags as line breaks. To see the Convert Line Breaks formatter in action, compare the text composed in the Entry Body field of Figure 5-7 to the XHTML output in Listing 5-2.
Figure 5-7: Creating a new weblog entry.
Listing 5-2: Formatted Entry Text
JetBlue is offering $69 one-way flights from Boston to Orlando and other Florida cities.
Tickets must be purchased by Feb. 10 for trips ending no later than May 25.
Restrictions: Seats are limited and may not be available on all flights. Sale fares are most often found on midweek travel dates. All fares are one-way and nonrefundable.
Your last login was at $connectedDate. END;
The remaining global attributes perform more general text conversions. The upper_case and lower_case attributes perform as you would expect, changing letters to the desired case. The space_pad and zero_pad attributes use space characters and zeroes, respectively, to make text the desired length. The padding character appears at the start of the text — for example, if a tag produces the output “1970” and zero_pad is used with a value of 7, the resulting text is “0001970.” Use “1970” with a zero_pad of 4 and “1970” is the output. The trim_to attribute limits tag output to a maximum number of characters, set by the attribute’s value, omitting the rest. The filters attribute applies one or more text-processing filters to tag output. Specify the name of the filters to use in a list separated with commas. The last global attribute, sprintf, applies formatting rules to output that make use of sprintf, a popular syntax for displaying numbers that takes its name from an indispensable function in C, PHP, and other languages. The sprintf attribute formats integer and decimal-point numbers with the desired width, decimal places, and padding characters. A short code specifies the output format. The full syntax of sprintf duplicates some of the functionality you can achieve with the space_pad and zero_pad attributes. For situations where it’s most useful in a Movable Type template, here are some handy sprintf format codes:
Chapter 8 ✦ Producing Web Pages with Template Tags
119
✦ %02d: A two-digit integer padded with a 0 if necessary (examples: 02, 10) ✦ %04d: A four-digit integer padded with 0s (such as 0001, 0025, and 0305) ✦ %01.2f: A floating-point number with two decimal places (4.13, 14.56) ✦ %08.3f: A floating-point number with three decimal places that will be eight digits long, including the decimal point (9025.750) ✦ %x: A hexadecimal number with lowercase letters (64, fa0) ✦ %X: A hexadecimal number with uppercase letters (32, FAC)
Formatting Date and Time Tags Movable Type includes eight template tags that represent timestamps, including MTEntryDate to present the date and time an entry was first saved, and MTEntryModifiedDate for its most recent revision. When used without an attribute, date tags produce dates that are structured as follows: April 28, 2004 02:04 PM April 26, 2004 09:39 AM February 7, 2004 08:04 AM
Each of these timestamps consists of a month name, day of month, four-digit year, two-digit hour, two-digit minute, and AM or PM. All of these elements can be rearranged, omitted, or formatted differently using an strftime formatting string. An strftime string specifies the order and structure of timestamp elements using a series of short codes that begin with the % character. The name comes from a popular command-line tool and programming language function that serves the same purpose. A date tag’s format attribute transforms the output by the rules of strftime, as shown in the following example:
Date formatting changes the appearance of a timestamp without changing any of its values. Following are the same three dates with the new formatting applied to them: Wed, 28 Apr 2004 14:04:04 Mon, 26 Apr 2004 09:39:51 Sat, 07 Feb 2004 08:04:48
120 Movable Type 3 Bible, Desktop Edition Table 8-2 contains the strftime codes supported by Movable Type (other software might offer different codes — implementations of strftime vary).
Table 8-2 Date Format Attribute Strftime Codes Code
Description
Example Output for April 30, 2004 04:03 PM
%a
An abbreviated weekday name
Fri
%A
A weekday name
Friday
%b
An abbreviated month name
Apr
%B
A month name
April
%d
A two-digit, zero-padded day of the month from 01 to 31
30
%e
A two-digit, space-padded day of the month
30
%H
A two-digit, military-time hour time from 01 to 23
16
%I
A two-digit, zero-padded hour from 01 to 12
04
%j
A three-digit day of the year from 001 to 366
121
%k
A two-digit, military-time, space-padded hour from 1 to 23
16
%l
A two-digit space-padded hour from 1 to 12
%m
A two-digit, zero-padded month from 01 to 12
04
%M
A two-digit, zero padded minute from 00 to 59
03
%p
The time period (AM or PM for English-language weblogs)
PM
%S
A two-digit, zero-padded second from 00 to 59
03
%x
A complete date
April 30, 2004
%X
A complete time
04:03 PM
%y
A two-digit, zero-padded year from 00 to 99
04
%Y
A four-digit, zero-padded year
2004
4
Movable Type’s default format for timestamps is %B %e, %Y %I:%M %p. Some strftime codes that you might recall from other environments are not supported; most notably, the %Z code, which displays a time zone code or numeric offset.
Chapter 8 ✦ Producing Web Pages with Template Tags
121
A time zone offset can be included in a date with the MTBlogTimezone tag, which displays the numeric offset from UTC time as a value from -12:00 to +13:00. The names of months, days, and time periods AM and PM are dependent on a weblog’s Date Display language setting. As a reader of this book, you’re presumably using English, but you can change to another language easily: Click the Weblog Config sidebar menu button to open the Configuration page, click the Preferences link atop the page, and then scroll to the Language for Date Display drop-down menu. There’s also a language attribute on date tags that overrides a weblog’s chosen language. Codes that can be used as values are shown in Table 8-3.
Table 8-3 Date Language Attribute Values Value
Language
cz
Czech
de
German
dk
Danish
en
English
es
Spanish
fi
Suomi
fr
French
is
Icelandic
it
Italian
jp
Japanese
nl
Dutch
no
Norwegian
pl
Polish
pt
Portuguese
se
Swedish
si
Slovenian
sk
Slovak
The dates produced by the %x and %X codes also are based on the designated language.
122 Movable Type 3 Bible, Desktop Edition
Using Global Tags As you work with simple template tags, the most important thing to note is where they can be used. Some tags work inside a specific container tag, and others work in a container and on individual archive pages. The easiest to use are global tags, which can be used on any template at any position in the file. More than a dozen useful global tags are listed in Table 8-4.
Table 8-4 Global Template Tags Tag
Description
MTBlogArchiveURL
The address (URL) of the weblog’s archives section
MTBlogCCLicenseRDF
RDF data describing the weblog’s Creative Commons license
MTBlogCCLicenseURL
The address (URL) of a Web page describing the site’s Creative Commons license
MTBlogCommentCount
The number of comments the weblog has received
MTBlogDescription
The weblog’s description
MTBlogEntryCount
The number of entries in the weblog
MTBlogHost
The host name (and possibly port number) of the server hosting the weblog
MTBlogID
The username of the entry author
MTBlogName
The e-mail address of the author, which can be disguised by setting spam_protect equal to 1
MTBlogRelativeURL
The relative address (URL) of the weblog (the portion of its home page address that does not include the host name)
MTBlogSitePath
The folder on the Web server where the site’s home page is stored
MTBlogURL
The address (URL) of the weblog’s home page
MTCGIPath
The relative address (URL) of the folder where Movable Type’s CGI scripts are stored
MTCommentScript
The name of Movable Type’s comment script
MTPublishCharset
The character set used by Movable Type
MTStaticWebPath
The server folder in which Movable Type’s static files are stored
MTTrackbackScript
The name of Movable Type’s trackback script
MTVersion
A hyperlink associated with the author, which can be associated with a home page or e-mail link
Chapter 8 ✦ Producing Web Pages with Template Tags
123
The global tags in Table 8-4 deliver information about the weblog and Movable Type installation on which it runs. The MTBlogID, MTBlogName, and MTBlogDescription tags provide the basics. You can change the name and description by editing your weblog configuration. Several tags offer Web addresses for the site. The MTBlogURL and MTBlogArchiveURL tags identify the weblog’s home page and the base URL of all archive pages, respectively. These addresses are called the Site URL and Archive URL in the weblog’s configuration settings. When set up correctly, they are full Web addresses that end with a trailing slash and do not include filenames (such as index.html). Keep this in mind as you use them to create URLs in a template, as shown in the following example: Biography
On a weblog with the Site URL http://orlandovacationer.com/, this example links to http://orlandovacationer.com/bio.html. The following template code would not work correctly because of the slash after the tag: Biography
The MTBlogHost and MTBlogRelativeURL tags break up a Site URL into its two constituent parts: the server hosting the site and the directory (or directories) in the rest of the URL. The Site URL http://orlandovacationer.com/ has the host orlandovacationer.com and the relative URL / (a single slash character). A weblog at http://example.com/weblog would have an example.com host and /weblog relative address. Seven global tags provide information about your Movable Type installation. The MTVersion tag displays the version number and the MTPublishCharset tag identifies the character set used by Movable Type on Web pages and other text files. The character set is ISO-8859-1 on weblogs for which English has been designated as the preferred language. This set, also called the Latin-1 character set, defines 191 characters from the Latin alphabet. These characters can be used to communicate in English, Dutch, German, Portuguese, Spanish, and a dozen other languages. The MTBlogSitePath tag indicates the directory on the Web server where a weblog’s home page and other index template-produced pages are stored, a setting called the Local Site Path in the weblog configuration. The location of the files used by Movable Type’s browser interface can be incorporated into a template with the MTStaticWebPath tag. This tag, which is defined in the mt.cfg configuration file, can be a relative URL (such as /static) or a complete Web address (such as http://example.com/static).
124 Movable Type 3 Bible, Desktop Edition The MTCGIPath tag provides a full or relative URL that indicates where Movable Type’s CGI scripts can be accessed from a Web browser. By combining this with the MTCommentScript and MTTrackbackScript tags that produce the names of these scripts, you can refer to Movable Type’s comment and trackback scripts in a flexible way. This becomes important if you need to move Movable Type’s scripts or decide to rename the scripts, which can help reduce the amount of abuse they receive from spammers and others who flood a site with ads and other undesired responses. Like many of the other global tags, these tags take their values from the mt.cfg configuration file in Movable Type’s installation directory. By default, these scripts are named mt-comments.cgi and mt.tb-cgi, respectively.
The following HTML code creates a form that is processed by Movable Type’s comment script:
Three tags provide template support for Creative Commons licenses, the system of copyright sharing described in Chapter 4, “Configuring a Weblog.” The MTBlogCCLicenseRDF tag contains RDF data specifying the Creative Commons license that applies to a weblog. This data, which uses the same XML format employed for trackback pings, can be hidden in the source code of the weblog home page and individual entry pages. Some weblog publishing tools read this data to determine whether weblog content can be republished elsewhere. This tag should be used within the header section of an HTML or XHTML page (between the opening and closing head tags). An MTBlogCCLicenseRDF tag also can be used in the template for individual weblog entries, where it will contain information about the reuse of each particular entry. For a public means of indicating a site’s licensing, employ the MTBlogCCLicenseURL tag, which contains the URL of a page on the Creative Commons Web site that describes your weblog’s particular license. By design, a new weblog created with Movable Type does not offer a Creative Commons license — a publisher shouldn’t enter into an expansive licensing agreement without understanding the copyright implications. The MTBlogIfCCLicense container tag makes it possible to present Creative Commons RDF data only when one of the licenses has been applied to a weblog:
Chapter 8 ✦ Producing Web Pages with Template Tags
125
Another container that can be used with global tags is MTBlogs, a container that holds all weblogs offered on your Movable Type server. One use for the tag is to present a list of links to each site:
All weblogs on a Movable Type installation are included in this container, even if the person editing the template has no access to some of them.
Using Entry Tags Weblog entries can be presented on a template inside an MTEntries tag, a container that represents entries retrieved from the database in a variety of ways. You also can work with entry tags on an individual entry template, which requires no MTEntries container. MTEntries holds entries retrieved by date, category, author, and recently published visitor comments. Table 8-5 presents the attributes.
Table 8-5 MTEntries Tag Attributes Attribute
Value
Description
Author
Text
Limit retrieved entries to the specified author
Category
Text
Limit retrieved entries to the specified category or categories
Days
Integer
Retrieve entries published within the specified number of days
Lastn
Integer
Retrieve the specified number of entries, beginning with the most recent and going backward
Offset
Integer
Start a lastn retrieval with earlier entries, counting backward the specified number of entries first
recently_ commented_on
Integer
Retrieve the specified number of entries that have received recent comments, organized by date and time of the last comment
sort_by
Text
Sort entries by the specified entry field, which can be author_id, excerpt, modified_on, status, or title
sort_order
Text
Set the sort order of retrieved entries, which can be either ascend or descend (the default)
126 Movable Type 3 Bible, Desktop Edition The MTEntries container often requires more than one attribute — an attribute that dictates the way to retrieve entries and one or more attributes that narrow the chosen entries or sort them in a new order. Three MTEntries tag attributes specify the manner in which entries should be retrieved: ✦ lastn collects X number of recent entries ✦ days grabs all entries from the last X days ✦ recently_commented_on collects X number of entries with recent comments The value X refers to the attribute’s value. You can use lastn=”5” to retrieve the last five weblog entries, days=”7” for entries published the preceding week, and recently_commented_on=”10” for the last 10 entries that received visitor comments. You can use the offset attribute to make lastn look further in the past. The offset value moves the starting place X entries backward. Therefore, on a weblog with 100 entries, an attribute of lastn=”3” pulls entries 100, 99, and 98; attributes of lastn=”3” offset=”3” pull entries 97, 96, and 95; and attributes of lastn=”3” offset=”6” pull entries 94, 93, and 92. Although you can place all the MTEntries attributes in a tag, in many cases some attributes will be ignored because they don’t work together. For instance, the days attribute cannot be used with lastn, category, or author. In addition, you can use offset to modify the performance of the lastn attribute only. It doesn’t work with recently_commented_on.
The following HTML code displays the title of all weblog entries published during the last three days:
Recent Entries:
Recent Entries:
If there are no entries in that category, nothing contained within the opening and closing MTEntries tags is displayed. The sort_by and sort_order attributes can be used to change the sorting order of entries and the key used to sort them. The sort_by attribute identifies the element of a weblog entry that is sorted. You can sort by entry author (using the value author_id), excerpt (excerpt), the date the entry was last edited (modified_on), the entry status (status), or the title (title). The sort_order attribute, which takes the value of ascend or descend, determines whether entries are listed from first-to-last or last-to-first order.
128 Movable Type 3 Bible, Desktop Edition The default sort order for entries is set by the Order of Entries Displayed setting in the weblog configuration. (To see or change it, click the Weblog Config sidebar menu button and click the Preferences link atop the Configuration page.) This setting determines the sort order unless the sort_order attribute appears in the MTEntries tag. In entries organized by date, ascending order goes forward in time. For entries organized by other keys, ascending order is alphabetical from A to Z. Here’s an example that sorts the 25 most recent entries alphabetically by title:
and
tags around paragraphs and replacing line breaks with tags. If the attribute is absent or equal to 0, the entry’s chosen text filter is applied instead. MTEntryBody tag output can be shortened with its words attribute, which takes as a value the number of words to display. Therefore, if words=”12”, the first 12 words in the main body of the weblog entry are displayed.Kalina, an 18-year-old killer whale at SeaWorld Orlando, gave birth to her fourth calf Monday at Shamu Stadium, the park’s research and breeding facility.
Posted by rcade |link
Categories:
In pages produced from this template code, each category is presented as a link to that category’s archive page. The link tags available for a category can be used only on weblogs that support those features. If you use the MTCategoryArchiveLink tag in a template and category archiving has not been enabled in your configuration, Movable Type will not rebuild pages with the template. The MTCategoryTrackbackLink tag works on categories that have been configured to accept incoming pings in a trackback content aggregator, a feature described in Chapter 11, “Sharing Trackback Links.” This tag displays the URL that should be used to send trackback pings to the category.
Normally, this tag is used on the archive pages for a category that serves as a trackback aggregator. If used in an MTCategories container, the tag displays only a trackback link for categories set up to accept pings. The MTEntryCategories container includes a glue attribute to present several categories together on the same line or in a similar grouping. Set the value of the attribute to text that should appear between each category — such as a comma to present a comma-separated list, as shown in the following example:
( )
This code produces the following HTML:
FantasyLand to add 3-D movie attraction (Disney News, Disney World)
JetBlue offers $69 fare to Orlando (Travel and Hotels)
OrlandoHotelsEye offers hotel discounts (Travel and Hotels)
Each time a new entry is published, Movable Type creates archive pages automatically for each of the archive types that has an archive template.
138 Movable Type 3 Bible, Desktop Edition A master index of archived pages can be created for each archive type using the MTArchiveList container tag. An MTArchiveList container holds several archive tags and can make use of entry tags. Two attributes affect its contents: lastn, which retrieves the specified number of archive pages starting with the most recent, and archive_type, which specifies the kind of archive being presented. The lastn attribute can be omitted, causing the list to contain all archive pages. When the archive_type attribute is omitted, MTArchiveList uses the preferred archive type designated in your configuration. The attribute can have the value Category, Daily, Weekly, Monthly, or Individual, and it determines the pages that are included in the list. Table 8-8 describes the archive tags that you can use for each archive page in the MTArchiveList container.
Table 8-8 Weblog Archive Tags Tag
Attributes
Description
MTArchiveCategory
The address (URL) of the category’s main archive page
MTArchiveCount
The number of entries in the archive list container
MTArchiveDate
format
The first date in an archive list that represents a daily, weekly, or monthly archive
MTArchiveDateEnd
format
The last date in an archive list for a daily, weekly, or monthly archive
MTArchiveLink
archive_type
The full address (URL) to this archive’s main page on the weblog
MTArchiveTitle
The title of this archive, which takes different forms depending on the archive type
The MTArchiveTitle tag provides a title that can be used in links to each archive page. The title depends on the archive type represented by the archive list — it will be a category name for category archives, an entry title for individual archives, and dates for calendar-based archives. Here’s some HTML template code to use this tag:
Chapter 8 ✦ Producing Web Pages with Template Tags
139
| Sun | Mon | Tue | Wed | Thu | Fri | Sat |
Keywords:
This code displays a weblog entry’s keywords, if they have been defined, and shows nothing if they haven’t. The MTInclude template tag enables a template to include another file or template, making it easier to share common content such as a row of menu buttons or weblog links on several templates. The tag’s module attribute specifies the template name, which should match its name in the Template Name column of the Templates page (accessible from the Templates sidebar menu button). The following template code adds the Ad Tower template to another template:
On the Orlando Vacationer weblog, the preceding line appears on the index template and all archive page templates, adding the site’s Google AdSense HTML code to display text ads. The MTInclude tag’s file attribute indicates a file that should be included in the page, which can be a Web page, a text file, or any other file that makes sense to incorporate into the template’s output. Here’s an example:
The file can be specified with a full directory and filename or simply as a filename. In the latter case, the file must be in either the Local Site Path or Local Archive Path directories. If you’re familiar with the server-side include feature of the Apache Web server or another server, you’ll find that the MTInclude tag doesn’t offer the same functionality. A server-side include will pull the included content into an enclosing Web page again with each request, so a change to the included page will be reflected automatically. The MTInclude tag only pulls content from the included page or template when the enclosing page is rebuilt. If you edit an included module, you won’t see the change on your weblog until you rebuild all templates that include it.
156 Movable Type 3 Bible, Desktop Edition The MTLink tag generates hyperlinks to weblog pages generated by templates, using the template attribute to identify the source of the page. The following XHTML example contains several link tags that identify a weblog’s syndicated Atom and RSS feeds: :
Here’s the resulting XHTML markup:
The MTLink also has an entry_id attribute that provides archive links to weblog entries: ” (a space followed by a forward slash and the > character) with the > character. You’ll catch most, or perhaps all, of the differences between XHTML and HTML in the template. After looking for anything you might have missed, change the first line of the file from an XHTML tag to an HTML tag.
Forms on a Web page collect input through a variety of fields such as buttons, single-line text fields, multiple-line text boxes, and drop-down menus. Although a full accounting of XHTML and HTML form design is beyond the scope of this book, here’s a quick rundown of how the form fields are employed in Listing 13-2: ✦ The form element contains the form. It has an action attribute that identifies the program that will be called to receive form input and do something in response. The method attribute indicates how the form transmits information — it can have the values get or post. Everything on a form must be placed within the form element’s opening and closing tags. ✦ Each input element represents a form field whose appearance is dictated by the type attribute. The submit attribute represents a click button and the hidden attribute creates a nonvisible field that holds pre-defined information. An input element with no type attribute is a text field. ✦ The label element identifies the purpose of another field. The label’s for attribute matches the id attribute of the field it labels. In Listing 13-2, the label is associated with a text field named search.
Chapter 13 ✦ Adding Search Capabilities to a Weblog
217
Movable Type’s search script collects user input using the name assigned to each form element. These names are significant; if an element’s name is changed, the search script can’t collect user input from it. The hidden element IncludeBlogs identifies the weblog that will be searched, using the MTBlogID tag to specify its ID. This demonstrates an important aspect of search template design: The template applies to all weblogs, but tags can be used such that when the template produces a file, tag output can be linked to a specific weblog. A form can include text and HTML and XHTML markup that make it more attractive. The form in Listing 13-2 includes the text Search this site: and a few BR tags to insert line breaks between form elements.
Offering an Enhanced Search Form The simple search form might be sufficient for most Movable Type weblogs, especially ones that cater to a general, nontechnical audience. Typing something in a box and pressing a search button passes the grandma test — always a good metric when deciding whether a user interface has become so complex it scares off normal people who don’t dream in pixels and binary numbers. Because some of us do go to bed counting pixelated sheep (0, 1, 10, 11, 100, 101, zzz ...), there’s a lot more you can do on a search form. Listing 13-3 contains the HTML code for a form with all of the available options supported by Movable Type’s search script.
Listing 13-3: A Full Search Form Look for: Options: Match case Regex search Search: Entries Comments Both Sort By: Date Authored Title Sort Order: last to first first to last Continued
218 Movable Type 3 Bible, Desktop Edition Listing 13-3 (continued) Exclude Weblogs: Dates to search: last week last two weeks last 30 days last 60 days last 90 days last year all Results to display on a page: 5 10 25 50 100 all
This form is shown in Figure 13-3.
Figure 13-3: Conducting an extended search.
The enhanced form contains three search-specific MT tags that weren’t used in the simpler interface: MTSearchStrings, the MTBlogs container tag, and the MTBlogName tag.
Chapter 13 ✦ Adding Search Capabilities to a Weblog
219
The MTSearchString tag contains the text of the visitor’s search query, which can be used to put a search form on a results page. When no search has been conducted, this tag is empty. In Listing 13-3, the search field has been assigned MTSearchString as a value. This makes it possible for a visitor to modify the last search and keep hunting around your site. As you learned in Chapter 9, “Designing a Weblog with Templates,” the MTBlogs tag contains information about all of your weblogs. Here’s how the form puts this tag to work: Exclude Weblogs:
Container tags cause their contents to be repeated for each item in a group. The MTBlogs tag holds a checkbox form field named ExcludeBlogs with a value of MTBlogID, a weblog’s ID number. The input element’s type attribute makes it a checkbox, a square box that can be checked or unchecked. ExcludeBlogs serves the opposite purpose of IncludeBlogs, identifying a
specific weblog that should be excluded from search results. Placing this form field inside MTBlogs causes one checkbox to appear for each weblog, enabling users to ignore one or more sites. The enhanced form contains checkboxes to indicate whether the search should be case-sensitive (the CaseSearch element) and use regular expressions (the RegEx element). Also available is a form field that consists of three related radio buttons, a group of circular on-off buttons from which only one button can be selected at any time (just like their namesake — buttons on a car radio). The SearchElement field determines whether entries, comments, or both will be part of a search. The select and option form elements work together to define a pull-down menu. The field’s name is set by the name attribute of the select element. Each of its possible values comes from the value attribute of an option tag. An option element’s value attribute holds the value that will be collected by the search script. A more user-friendly answer can be provided between the opening and closing option tags, like so: Sort Order: last to first first to last
220 Movable Type 3 Bible, Desktop Edition This HTML code presents a pull-down menu that asks a user to determine the order in which results will be presented. The search script requires the ResultDisplay field to be either ascend or descend. Visitors are presented with easily understood options: “first to last” to see results in chronological order and “last to first” for the opposite. Of course, you’re not required to offer an enhanced search form with every possible field the search script supports. In fact, you might want to take some of them away as a means of preventing visitors from seeing things you don’t want to offer in a search. To limit the search to the weblog on which the form appears, drop the entire MTBlogs section from its opening tag to its closing tag. Replace it with the hid-
den tag used in the simple form:
You also can limit the options offered in a checkbox, radio button, or pulldown menu by leaving some of them, or even all of them, off the form. Perhaps you don’t want visitors to conduct regular expression–based searches (a feature that I love as a programmer that miserably fails the grandma test). You can accomplish this by taking its input element and accompanying text off the form: Regex search
Creating a Search Template Like all other forms of Web content in Movable Type, search results are template-driven and can be fully customized to suit your goals. One important difference is that search templates apply to all of your Movable Type weblogs and are not created on a per-weblog basis. There’s no way to create and edit search templates using Movable Type’s browser interface. You must either edit the files directly on the server or edit them on your computer and upload the templates with an FTP client. The software includes two search templates: a weblog template named default.tmpl and the comment template called comments.tmpl. These files are stored in the search_templates subdirectory inside the directory where Movable Type scripts are installed. You can edit these templates and create your own, storing them in this directory so the script can find them.
Chapter 13 ✦ Adding Search Capabilities to a Weblog
221
Using Search Tags Search templates can use most Movable Type tags in the same manner they’re employed in other templates. The tags that make the most sense to include are general weblog tags such as MTBlogName and all of the tags that relate to an individual weblog entry. Movable Type’s installed version of default.tmpl uses four general weblog tags: MTBlogName, MTBlogURL, MTPublishCharset, and MTCGIPath. Five entry tags pull information from weblog entries found in the search: MTEntryDate, MTEntryEditLink, MTEntryExcerpt, MTEntryPermalink, and MTEntryTitle. These tags are placed within the MTSearchResults container tag, which serves the same purpose as MTEntries on a non-search template. Any tag related to an individual weblog entry can be used within this container. When search results come from more than one weblog, the search script groups results by weblog. The MTBlogResultHeader container tag can be used to present a weblog’s header along with the first entry from that weblog. It should be placed within a MTSearchResults container. The MTSearchResultCount tag holds the number of results returned from a search. Listing 13-4 contains HTML code that presents search results with a header atop the matching entries from each weblog.
Listing 13-4: Formatted Search Results
Results found:
entries:
Posted in on
Figure 13-4 shows how this code looks in action. The weblog name Orlando Vacationer links to the site’s home page. Each weblog entry title links to that entry’s archive page.
222 Movable Type 3 Bible, Desktop Edition
Figure 13-4: Presenting search results.
A MTNoSearchResults container tag determines what will be displayed when a search turns up no results matching a term. The MTSearchString tag, which holds the text the user was looking for, can be used in this container, as in this simple example:
Could not find anything matching “”
You must enter a word or words to search for. Use your browser’s back button to try again.
You can define six attributes for the MTGoogleSearch tag, as listed in Table 13-2. All of them are optional.
Table 13-2 MTGoogleSearch Tag Attributes Attribute
Description
Default
Query
The search query, which can be a word or words using the same syntax as a search conducted on the Google Web site (http://www.google.com)
None
Results
The number of results to receive, which has a maximum of 10
10
Excerpt
A flag that can be set to 1 to indicate that the excerpt of the current weblog entry should be used as the search query
0
Keywords
A flag set to 1 to make an entry’s keywords the search query
0
Title
A flag set to 1 to make an entry’s title the search query
0
Related
The URL to use for a related-sites search. If this equals 1 instead of a URL, sites related to the weblog’s home page are received.
None
Most of these attributes cannot be effectively used in the same MTGoogleSearch tag. Only one query can be defined for a search, so it wouldn’t make sense to put both “query=baseball” and “title=1” in the same tag. Within this container, a MTGoogleSearchResult tag presents items included in a search result. This tag has a property attribute that identifies the item to display. If the tag is used without any attributes, a search result’s title is displayed.
228 Movable Type 3 Bible, Desktop Edition Table 13-3 presents the possible values for property. Each relates to a Web page that was found during the search.
Table 13-3 MTGoogleSearchResult Property Attribute Values Property
Description
Format
DirectoryTitle
The title of the page from the Open Directory Project, if that page exists in that database
Text
Snippet
A portion of the page most relevant to the search, which might not include words in the search query
Encoded HTML
Summary
The summary of the page from the Open Directory Project database, if one exists
Text
Title
The title of the page
Encoded HTML
URL
The URL of the page
Text
Before encoded HTML can be presented on a Web page, it must be decoded, the process that converts the < and > entities to the proper less-than and greater-than signs (< and >). In the MTGoogleSearchResult tag, set the universal tag attribute decode_html to 1 to convert the HTML to publishable form. You also can remove the HTML entirely by setting the remove_html attribute to 1. Listing 13-5 contains HTML code that searches Google for results matching a weblog entry’s title. An unnumbered list is displayed with the title of each search result linking to the Web site.
Listing 13-5: Publishing Google Search Results
With all of the attention focused on Mission: Space, Mickey’s PhilharMagic has been overlooked by many. This attraction, scheduled to open on Wednesday, October 8 in the Magic Kingdom, completes the addition of 3-D movies to all of the Florida theme parks. Apparently, the storyline has Donald Duck stealing Mickey’s sorcerer hat (no word on how Mickey came into permanent possession of it from the sorcerer Yensid), and
Chapter 14 ✦ Importing Entries from Another Weblog
233
stirs up much trouble, as he usually does.
... some shoppers are paying top dollar for silk pants (costing $250), belt buckles and purses adorned with Mickey’s retro image from the 1920s and ‘30s. It was enough to make the host of NBC’s Today show, Katie Couric, ask earlier this month: “Is it true that Mickey is the new black?” while interviewing the fashion editor of People Magazine.
--------The three-decade home of the Phillies and Eagles was demolished Sunday morning. link Rockets sign Oakley
The Houston Rockets bring in Charles Oakley for 10-day contract to “toughen up team.” link Mark Cuban starts weblog
The Dallas Mavericks owner has launched an online site to talk directly to the public. link
In this code, each entry has a headline enclosed within opening and closing H3 tags. This could be designated as the entry’s title by putting in the Start Title HTML field and in the End Title HTML field. When this technique isn’t necessary or when a weblog does not have anything that can be used as a title, leave those fields blank. Movable Type will use the first five words of the entry as a makeshift title. Weblog data files you have created can be imported by following these steps: 1. With an FTP client or a command-line shell, open the directory in which Movable Type’s scripts are installed. 2. Create a new subdirectory named import if one doesn’t exist already. 3. Place all files containing data to import in this new directory. 4. In Movable Type’s browser interface, open the weblog that will be receiving the imported data. 5. Click the Import/Export button on the sidebar menu. The Import/Export page opens, as shown in Figure 14-3. 6. If you should be the author of all imported entries, check the Import Entries as Me checkbox and leave the Password field blank.
246 Movable Type 3 Bible, Desktop Edition 7. Otherwise, leave the checkbox unchecked and enter a password of your choosing in the Password field. All newly created author accounts will use this password (although they should be encouraged to change it, for obvious security reasons). 8. Use the Default Category and Default Post Status drop-down menus to select these settings, if desired. 9. When extracting titles from weblog entry text, provide the proper HTML in the Start Title HTML and End Title HTML fields. 10. Click the Import Entries button. Movable Type loads the weblog data, reporting the success or failure of each entry.
Gotcha
Avoid the following bang-your-head-against-the-keyboard mistake I’ve made several times with Movable Type: leaving the imported weblog data in the import directory after it has been brought into the weblog. Importing the same entries twice can be a huge hassle to fix; you must hunt for and delete the entries manually, one at a time. To avoid this problem, remember to delete files immediately from the import directory after you’re done using them.
Summary When Movable Type was originally released, developers Ben and Mena Trott stated that one of their motivations was to give webloggers unfettered access to their own data. This promise has been kept with the software’s export feature, the XML-RPC interface; and the subject of this chapter, the weblog import feature. Movable Type eagerly devours weblog data produced by Blogger, Radio UserLand, and other tools. If you have weblog entries, comments, and even trackback pings that were created elsewhere, you often can bring them with you. Weblog data must be imported using a simple text format devised by Six Apart that has single- and multi-line fields to define each entry. You can start a new weblog with imported entries, add them to an existing weblog, or file them in a specific category. Movable Type’s import feature supports all of the options available on the entry-editing form, including the capability to publish or draft entries and allow or disallow comments and trackback.
Connecting to Movable Type with XML-RPC
M
ovable Type adopts a Web browser–based user interface, a trade-off that makes the software easier for novices but sacrifices the power and flexibility of desktop software. Users don’t need to make that trade. The software offers an interface that can be controlled from other programs, putting Movable Type to work in the background. The interface can be used to read and write weblog entries, retrieve category and trackback information, and more. Three application programming interfaces (APIs) are supported: Blogger, MetaWeblog, and Movable Type’s own interface. A fourth, Atom, has been added in version 3 of the software. These APIs enable software to call methods of Movable Type and receive a response in return. With the exception of Atom, they employ XML-RPC, a protocol that enables programs to work together whether they are located in the same room or on opposite sides of the world. Using XML-RPC, programs can run on your desktop and offer a graphical user interface, publish data from one weblogging tool to another, exchange files, and perform other tasks.
15 C H A P T E R
✦
✦
✦
✦
In This Chapter Using XML-RPC Handling the protocol’s data types Sending an XML-RPC request Receiving an XML-RPC response Choosing a client implementation Connecting to movable type’s XML-RPC server Calling methods of the Movable Type API Calling methods of the Blogger API Calling methods of the MetaWeblog API
✦
✦
✦
✦
248 Movable Type 3 Bible, Desktop Edition Atom consists of an XML syndication format and an API that sends and receives data in that format over HTTP, the protocol used by Web servers and browsers to exchange information. For more on the effort, read Chapter 19, “Supporting the Atom Syndication Format and API.”
Using XML-RPC XML-RPC was developed in 1998 by a weblogger, Dave Winer of UserLand Software, in cooperation with Microsoft. The protocol’s simplicity struck a chord with developers looking for an easy way to call procedures remotely over networks such as the Internet. Microsoft and developers in the UserLand and Python communities embraced the new protocol. XML-RPC is a remote procedure call protocol tailor-made for programming over a network. The protocol has become one of the key elements of Web services implemented by software developers on Linux, Macintosh, UNIX, and Windows systems. One prominent adopter of XML-RPC is Red Hat, which employs it on contemporary versions of the Red Hat Linux operating system. The Red Hat Network, a remote administration service that enables computers to be maintained and updated over the Internet, uses XML-RPC heavily. Client/server implementations of XML-RPC are available for most platforms and programming languages. UserLand Software offers a directory of implementations on its XML-RPC.Com Web site at http://www.xmlrpc.com. Eighty implementations of the protocol are available for a variety of languages and platforms, including C++, Java, Perk, PHP, and Python. XML-RPC exchanges information using the tandem of HTTP, the protocol of the World Wide Web, and XML, a format for organizing data independent of the software used to produce it. The following data types are supported by XML-RPC: ✦ base64: Binary data encoded in Base 64 format ✦ boolean: True-false values that are either 1 (true) or 0 (false) ✦ dateTime.iso8601: A string containing the date and time in ISO 8601 format (such as 20040317T13:31:19 for 1:31 PM and 19 seconds on March 17, 2004) ✦ double: Eight-byte signed floating-point numbers ✦ int: Signed integers ranging in value from -2.14 billion to 2.14 billion (also called i4) ✦ string: Text
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
249
✦ struct: Name-value pairs of data for which the name is a string and the value can be any of the other data types ✦ array: A data structure that holds multiple elements of any of the other data types, including arrays Although this range of data types is slim pickings compared with most programming languages, you can represent complex data through the combination of array and struct data types. The full XML-RPC specification is available on XML-RPC.Com: http://www.xmlrpc.com/spec
After the release of XML-RPC, the specification was extended by Microsoft, IBM, Lotus, and others to create another remote protocol called SOAP, the Simple Object Access Protocol. Although SOAP shares some design objectives with XML-RPC, it has been expanded to support objects, user-defined data types, and other advanced features. Backed by Microsoft and other developers, SOAP also has become popular for Web services and other network programming. Because SOAP is appreciably more complex than XML-RPC, an argument can be made for using either one, depending on the needs of a software project. To find out more about SOAP, visit the XMethods Web site: http://www.xmethods.com
XML-RPC is a protocol transmitted using Hypertext Transfer Protocol (HTTP), the standard for data exchange between Web servers and Web browsers. The information that it transmits is not Web content, but XML data encoded in a specific way. All XML-RPC data exchanges consist of a client request followed by a server response. The client and server can be located on different machines and developed using different programming languages. As long as both sides speak XML-RPC, they can work together.
Sending an XML-RPC Request An XML-RPC request consists of XML data sent to a Web server in an HTTP post request. A post request transmits data from a Web browser to a Web server — Common Gateway Interface scripts and other software collect the data from a post request and send HTML back in response. When you fill out an e-mail form on a Web page or take an online survey, you’re using either post or a similar HTTP request called get.
250 Movable Type 3 Bible, Desktop Edition XML-RPC uses HTTP as a convenient protocol for communicating with a server and receiving a response. The request consists of HTTP headers required by the post transmission and the XML-RPC request, which is expressed as XML. Listing 15-1 contains a sample XML-RPC request.
Listing 15-1: An XML-RPC Request POST /cgi-bin/mt-xmlrpc.cgi HTTP/1.0 Host: www.cadenhead.org Connection: Close Content-Type: text/xml Content-Length: 160 User-Agent: OSE/XML-RPC mt.getTrackbackPings 61
This request asks for a list of trackback pings associated with entry number 61 on a Movable Type installation. Listing 15-1 is divided into two halves separated by a blank line. The first half consists of HTTP headers that request a Web server resource from a script, indicating the format and length of the request. The second half consists of the request formatted as XML. Looking at this request reveals the following information: ✦ The XML-RPC server is at http://www.cadenhead.org/cgibin/mt-xmlrpc.cgi. ✦ The remote method being called is mt.getTrackbackPings. ✦ The method is being called with one argument, an integer with a value of 61.
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
251
Contrary to what you might expect, method names in an XML-RPC request do not include parentheses. They consist of the name of a method, which can be preceded by a period and a group identifier. The naming convention for XML-RPC methods depends on the server offering them. The methods offered by Movable Type consist of an interface identifier (blogger, metaWeblog, or mt) followed by a period and a method name.
Receiving an XML-RPC Response An XML-RPC response is XML data sent back from a Web server like any other HTTP response. The protocol rides piggyback atop an established process — a Web server returning data via HTTP to a Web browser — and uses it differently. Like the request, the response consists of HTTP headers and a response in XML format, separated by a blank line. Listing 15-2 contains a response to the previous request for a weblog entry’s trackback pings.
Listing 15-2: An XML-RPC Response HTTP/1.0 200 OK Date: Thu, 18 Mar 2004 22:09:08 GMT Server: Apache/1.3.27 (Unix) (Red-Hat/Linux) mod_gzip/1.3.26.1a mod_ssl/2.8.12 OpenSSL/0.9.6 DAV/1.0.2 PHP/4.1.2 mod_perl/1.24_01 mod_throttle/3.1.2 SOAPServer: SOAP::Lite/Perl/0.52 Vary: * Content-Length: 788 Connection: close Content-Type: text/xml pingTitle Coaster makes you cry ‘Mummy!’ Continued
252 Movable Type 3 Bible, Desktop Edition Listing 15-2 (continued) pingURL http://example.com/000087.html pingIP 192.0.34.166
The response reveals the following details: ✦ The response is 788 bytes in size and in XML format. ✦ The entry has one trackback ping with the title “Coaster makes you cry ‘Mummy!’,” the IP address 192.0.34.166, and the URL http:// www.example.com/000087.html. Although an XML-RPC request can contain 0, 1, or many parameters, an XMLRPC response always consists of a single value, which can be any of the XMLRPC data types. Because this value can be an array, a struct, or even an array of structs, a lot of information can be packaged in that single value. The response in Listing 15-2 sends back trackback ping information in an array of structs, one per ping. The beginning and end of the array are established by the data tag. Each struct is stored within opening and closing struct tags. Although you don’t have to see raw XML-RPC requests and responses, it helps considerably when you’re testing an implementation. Dumpleton Software offers an excellent XML-RPC debugger on the Web that can be used to call remote methods and see the full XML-RPC request and response, which makes it much easier to determine whether a client or server is working correctly: http://www.dscpl.com.au/xmlrpc-debugger.php
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
253
When an XML-RPC request is unsuccessful, failure is indicated by a struct that holds faultString, a string holding an error message, and faultCode, a numeric error code.
Connecting to Movable Type with Client Software The robust application programming interfaces for Movable Type have inspired several developers to create weblog editing tools that can be used with the software. Figure 15-1 shows w.bloggar (see http://wbloggar.com), one of the better clients that has been offered for Movable Type users.
Figure 15-1: Editing a Movable Type weblog entry with desktop software.
In Figure 15-1, an entry created with Movable Type’s browser interface has been loaded for editing in w.bloggar. The software, released as freeware by Brazilian programmer Marcelo L. L. Cabral, can be used to write, edit, and delete weblog entries. With features similar to word processing software, w.bloggar offers spell-check, file upload, HTML formatting toolbars and menus, and a text import feature. Setting it up to work with an existing Movable Type installation takes under five minutes.
254 Movable Type 3 Bible, Desktop Edition Because so many weblogging tools use the same XML-RPC interfaces, the w.bloggar software works with more programs than Movable Type. You can use it as an authoring tool for Blogger, LiveJournal, Drupal, Blosjom, and more than a dozen other server-based weblogging tools. Table 15-1 contains information about software that works with Movable Type using XML-RPC.
Table 15-1 Movable Type XML-RPC Clients Software
Description
Platform
Home Page
BloGTK
Weblog editor for Movable Type and other server-based weblogging tools
Linux
http://blogtk. sourceforge.net
Ecto
Weblog editing client for Movable Type and many other tools
MacOS
http://www. kung-foo.tv/ecto
Footbridge
Tool that adds Movable Type publishing support to Radio UserLand
Windows, MacOS
http:// markpasc.org/ code/radio
Kablog
Tool to publish weblog entries from a mobile phone or PDA to Movable Type and others
J2ME, PalmOS, Symbian
http://www. rawthought.com
Slug
Simple weblog editing client for Movable Type
Windows
http://www. 3e.org/slug
w.blogger
Weblog editing client for Movable Type and others
Windows
http:// wbloggar.com
Zempt
Movable Type weblog editing client for Windows
Windows
http://www. zempt.com
Using Movable Type’s XML-RPC Server Movable Type’s XML-RPC server has been implemented as mt-xmlrpc.cgi, one of the Perl scripts in the software’s main installation folder. Any software that calls the server must know the server’s URL, which is Movable Type’s CGI path followed by the name of the script. For example, the XML-RPC server on the domain cadenhead.org is at this URL: http://cadenhead.org/cgi-bin/mt-xmlrpc.cgi
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
255
This script requires two Perl libraries that are part of the Movable Type installation: LWP::UserAgent and SOAP::Lite. The latter library includes XMLRPC::Lite, a client/server implementation of the XML-RPC protocol. The only purpose of the mt-xmlrpc.cgi script is to handle XML-RPC requests. If you decide not to offer any XML-RPC services or need to temporarily disable the functionality for some reason, you can rename or remove the script. Movable Type’s implementation of XML-RPC supports three weblog publishing APIs released in the following chronological order: Blogger, MetaWeblog, and Movable Type’s own interface. Although developed separately, these three interfaces build on each other and can be used in a complementary fashion. Each of the APIs contains methods that fill in a gap of its predecessor. MetaWeblog expanded Blogger’s support for entry text to add titles, links, and other types of information. Movable Type extended MetaWeblog with methods to support trackback pings, text filters, and other features specific to the software. You can use these APIs using one of the XML-RPC libraries described on the XML-RPC Web site: http://www.xmlrpc.com/directory/1568/implementations
Some of the implementations worth a look are SOAP::Lite, the Perl library used by Movable Type; Apache XML-RPC, an open-source Java class library; and xmlrpclib, a Python library developed by Fredrik Lundh that was the first to offer support for XML-RPC after UserLand.
Gotcha
The biggest obstacle to using XML-RPC in any language is mapping XMLRPC data types to the ways in which data is represented in the language. Learn that first when evaluating an implementation, because it’s a good indicator of whether you’ve found the right tool for the job. After developing Java applications that used Apache XML-RPC, I learned the hard way that I should’ve begun with the following page on mapping data types: http://ws.apache.org/xmlrpc/types.html
Calling Methods of the Blogger API Blogger, server-based publishing software that helped spark the weblog phenomenon, was the first weblogging tool that offered an XML-RPC interface. The Blogger API has been supported by dozens of client tools and several servers, including Movable Type. The Blogger API, which has been frozen at version 1.0, is documented on the Web at http://www.blogger.com/developers/api/1_docs.
256 Movable Type 3 Bible, Desktop Edition The API includes methods to read, write, edit, and delete weblog entries; methods to read and write site templates; and two methods to retrieve information about a user. Movable Type supports all of the Blogger API methods except for Blogger.getTemplate and Blogger.setTemplate. Blogger templates vary substantially from the template system in Movable Type, so there’s no way to use them interchangeably. A limitation of this API is its lack of support for all of the fields that can be used to author a weblog entry in Movable Type. The only field supported is the text of an entry. The other parts of Movable Type’s entry-editing form — the title, extended entry, excerpt, categories, and keywords — cannot be accessed in any manner using Blogger methods. The Blogger API was designed to work with an appkey, a string that uniquely identifies the application making the request. Pyra, the division of Google that develops Blogger, will issue free appkeys to software developers, as described later in this section. The value of an appkey is ignored by Movable Type, so you don’t need to receive an appkey to make use of the Blogger API’s methods. You can use an empty string or anything else in place of a key. The next six sections describe Blogger API methods supported by Movable Type.
blogger.newPost Create a new weblog entry that can be stored as a draft or immediately published. This method returns the ID number of the entry if successful. Its parameters are as follows: ✦ appkey (string), the Blogger application key, which is ignored by Movable Type ✦ blogid (int), the blog ID of the weblog receiving the entry ✦ username (string), the username of the author ✦ password (string), the password of the author ✦ content (string), the content of the entry ✦ publish (boolean), a flag indicating whether to publish the entry (1) or save it as a draft (0) Because the Blogger API does not support titles, the first several words of the entry are used as a title.
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
257
blogger.editPost Replace an existing weblog entry and either publish it immediately or store it as a draft. This method returns 1 (boolean true) if the entry was replaced successfully. Its parameters are as follows: ✦ appkey (string), the Blogger application key ✦ postid (int), the ID number of the weblog entry to replace ✦ username (string), the author’s username ✦ password (string), the author’s password ✦ content (string), the new content of the entry ✦ publish (boolean), a flag indicating whether to publish the entry (1) or save it as a draft (0)
blogger.deletePost Delete an entry. This method returns 1 (boolean true) if the entry was replaced successfully. Its parameters are as follows: ✦ appkey (string), the Blogger application key ✦ postid (int), the ID number of the weblog entry to delete ✦ username (string), the author’s username ✦ password (string), the author’s password ✦ publish (boolean), a flag indicating whether to rebuild the site after deletion of the entry (1) or not (0) Because this API lacks a method to rebuild the weblog, if you delete a post with a publish parameter of 0, you’ll be left without a convenient way to make the site reflect the deletion. The deleted entry won’t vanish until the site is rebuilt after an entry is added or edited (or Movable Type’s browser interface is used to rebuild it).
blogger.getRecentPosts Retrieve one or more recent entries from a weblog. This method returns an array of structs, each of which holds the following values about an individual entry: ✦ content (string), the text of the entry ✦ dateCreated (dateTime.iso8601), the date and time when the entry was first saved
258 Movable Type 3 Bible, Desktop Edition ✦ postid (string), the ID number of the entry ✦ userid (string), the author’s ID number The dateCreated value uses the same time zone as the weblog containing the entry. Its parameters are as follows: ✦ appkey (string), the Blogger application key ✦ blogid (int), the weblog’s ID number ✦ username (string), the author’s username ✦ password (string), the author’s password ✦ numberOfPosts (int), the number of entries to retrieve To retrieve all of a weblog’s entries using this method, use a numberOfPosts parameter of 0. In the course of preparing this chapter, I found a bug in Movable Type’s implementation of this method. If you try to retrieve an entry containing curly-quote characters (also called smart quotes) or curly apostrophes, the method call fails with an error of the following form: “xmllib.Error: Syntax error at line x: illegal character in content.” This occurs because Movable Type doesn’t encode the character properly in the XML-RPC response. To fix the problem, find and edit the weblog entries that contain these characters, replacing the smart quotes and curly apostrophes with straight quotes and apostrophes.
blogger.getUsersBlogs Retrieve a list of weblogs to which an author can post entries. This method returns an array of structs upon a successful call. Each struct holds three values about a particular weblog: ✦ blogid (string), the blog ID of the weblog ✦ blogName (string), the weblog’s name ✦ url (string), the home page of the weblog There’s no limit to the number of structs that can be present in the array. Its parameters are as follows: ✦ appkey (string), the Blogger application key ✦ username (string), the author’s username ✦ password (string), the author’s password
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
259
blogger.getUserInfo Retrieve a weblog author’s account information in the Movable Type database. This method returns a struct that holds six values: ✦ email (string), the user’s e-mail address ✦ firstname (string), the user’s first name ✦ lastname (string), the user’s last name ✦ nickname (string), the user’s nickname ✦ url (string), the user’s home page ✦ userid (string), the user’s ID number in your Movable Type installation The e-mail address, home page, and nickname are taken directly from your profile in Movable Type. The userid value comes from an ID number that the software uses internally to manage weblog authors. There’s nothing you can do with this information in any of the XML-RPC methods described in this chapter. Before making use of the firstname and lastname values, take note that both are rough guesses based only on the username. There’s no guarantee that either one is actually a first or last name — the firstname value contains everything up to the first space in the username, and lastname contains everything after that space. When a username has no spaces, firstname is the same as username and lastname is an empty string. Its parameters are as follows: ✦ appkey (string), the Blogger application key ✦ username (string), the author’s username ✦ password (string), the author’s password
Acquiring a Blogger Application Key Although the appkey is ignored by Movable Type, Blogger and other software that support the Blogger API aren’t so permissive. You can easily acquire one of these keys by filling out a request on the Blogger Web site: http://www.blogger.com/developers/api/1_docs/register.html
You must provide your name and e-mail address along with the name and home page of your software. An appkey will be sent immediately in response.
260 Movable Type 3 Bible, Desktop Edition
Calling Methods of the MetaWeblog API A drawback to the Blogger API becomes apparent on any weblog that makes use of entry titles. The representation of entries has became more sophisticated with the introduction of titles, links, permanent links, and other elements that are now commonplace. The MetaWeblog API, released by Dave Winer of UserLand Software, supports a more complex representation of weblog entries than the Blogger API. The original impetus for the new interface was to support the authoring capabilities of Manila and Radio UserLand, two popular weblogging tools for Microsoft Windows, Mac Classic, and Mac OS X offered by UserLand. This API is documented on the Web: http://www.xmlrpc.com/metaWeblogApi
By design, in the MetaWeblog API, each entry can hold anything that can be represented in RSS 2.0, a popular XML format for site syndication. RSS files, which are called newsfeeds or feeds, include an item element with subelements for a weblog entry’s title, link, and description, as well as many other kinds of information. You can read the RSS 2.0 specification on the Web: http://blogs.law.harvard.edu/tech/rss
Because RSS 2.0 files can be extended to support new kinds of information, the API provides a way to send and receive an entry no matter what values it contains. Two RSS formats, RSS 1.0 and RSS 2.0, are both copiously documented in Chapter 18, “Publishing RSS and Atom Syndication Files.”
Movable Type supports all of the MetaWeblog API methods except for metaWeblog.getCategories, which provides the name, URL, and RSS feed URL for all of a weblog’s categories. The Movable Type implementation extends the interface to support the information collected on the software’s entry-editing form. Several methods of this API employ a struct named content that represents a weblog entry. The struct serves as a parameter to the metaWeblog.newPost and metaWeblog.editPost methods and is returned by metaWeblog.getPost and metaWeblog.getRecentPost. In Movable Type’s implementation, the content struct holds the following values: ✦ title (string), the title of the entry ✦ description (string), the text of the entry
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
261
✦ dateCreated (dateTime.iso8601), the date and time when the entry was first saved ✦ mt_allow_comments (boolean), a flag indicating whether comments are allowed (1) or disallowed (0) ✦ mt_allow_pings (boolean), a flag indicating whether trackback pings are allowed (1) or disallowed (0) ✦ mt_convert_breaks (string), the key that identifies the text formatting filter used to format the entry ✦ mt_text_more (string), the extended entry text ✦ mt_excerpt (string), the entry’s excerpt ✦ mt_keywords (string), the keywords associated with the entry The struct does not include flNotOnHomePage, a boolean flag specified in the MetaWeblog API, or anything else that could be defined in an RSS 2.0 newsfeed. Some methods in Movable Type’s implementation add additional values to the content struct. Later in this chapter, you learn about a method of the Movable Type XMLRPC API, mt.supportedTextFilters, that provides the keys that can be used as the value for mt_convert_breaks.
The following five sections document the API methods supported by Movable Type.
metaWeblog.newPost Create a new weblog entry, storing it as a draft or publishing it immediately. This method returns an int containing the ID number of the entry, if it was saved successfully. One of the specified parameters must be the content struct, defined in the preceding section. The struct also can contain mt_tb_ping_urls, an array of URLs for trackback pings sent with the entry. Its parameters are as follows: ✦ blogid (int), the ID number of the weblog ✦ username (string), the entry author’s username ✦ password (string), the author’s password ✦ content (struct), a struct defining the entry’s content ✦ publish (boolean), a flag indicating whether to publish the entry (1) or save it as a draft (0)
262 Movable Type 3 Bible, Desktop Edition
metaWeblog.editPost Replace a weblog entry, either in published form or as a draft. This method returns 1 (boolean true) if the entry was replaced successfully. The content struct is employed in the method call. Its parameters are as follows: ✦ postid (int), the entry’s ID number ✦ username (string), the author ✦ password (string), the author’s password ✦ content (struct), the content of the entry ✦ publish (boolean), a flag indicating whether to publish the entry (1) or just store it (0)
metaWeblog.getPost Retrieve a weblog entry. When it is called successfully, this method returns a content struct with a few additional values: ✦ link (string), the URL of the weblog entry ✦ permalink (string), the permanent link of the entry (which is often the same thing as the link) ✦ postid (string), the entry’s ID number ✦ userid (string), the entry author’s username Its parameters are as follows: ✦ postid (int), the entry’s ID number ✦ username (string), the entry’s author ✦ password (string), the author’s password Although Movable Type’s user manual states that this method also returns an mt_tb_ping_urls value in the content struct, this does not appear to be the
case in the current version of the software.
metaWeblog.getRecentPosts Retrieve one or more recent entries from a weblog. Because the number of entries is configurable and has no maximum, this method can be used to export an entire weblog over XML-RPC.
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
263
This method returns an array holding a content struct for each entry. This struct contains the following additional values: ✦ link (string), the URL of the weblog entry ✦ permalink (string), the permanent link of the entry (which is often the same thing as the link) ✦ postid (string), the entry’s ID number ✦ userid (string), the entry author’s username Its parameters are as follows: ✦ blogid (int), the weblog’s ID number ✦ username (string), the author ✦ password (string), the author’s password ✦ numberOfPosts (int), the number of entries to retrieve, or 0 for all entries This method does not include an mt_tb_ping_urls value in the content struct.
metaWeblog.newMediaObject Upload a file to the Web server hosting Movable Type. Because XML-RPC delivers information over the text-based protocols XML and HTTP, file data must be converted from its binary form before it can be transferred. The file must be encoded using Base 64, a technique for transmitting binary data through text-only media such as electronic mail. This method returns a string containing the URL where the file can be viewed on the Web. One of the parameters is a struct named file that holds two values: ✦ bits (string), the Base 64–encoded text of the file ✦ name (string), the name of the file Its parameters are as follows: ✦ blogid (int), the weblog’s ID number ✦ username (string), the entry author ✦ password (string), the author’s password ✦ file (struct), the file The MetaWeblog API dictates that the file struct also should contain a string named type that identifies the MIME type of the file. Movable Type does not support this parameter, so it will be ignored if present.
264 Movable Type 3 Bible, Desktop Edition
Calling Methods of the Movable Type API Although the XML-RPC methods supported by the Blogger and MetaWeblog APIs are useful, they don’t support some popular capabilities of Movable Type. Therefore, Movable Type has created its own API to complement the functionality of the other APIs. Six methods are available for working on a weblog, storing and retrieving entry categories, reading titles and trackback pings, and rebuilding a weblog. Also available are two methods for providing information about an installation of Movable Type: mt.supportedMethods, to see which XML-RPC methods it supports; and mt.supportedTextFilters, to learn which text formatting options are available. The next eight sections describe these methods.
mt.publishPost Rebuild all of the files associated with a weblog entry. This method can be used to publish an entry that has been saved as a draft. It returns 1 (boolean true) if the files were rebuilt successfully. Its parameters are as follows: ✦ postid (int), the ID number of the entry ✦ username (string), the author’s username ✦ password (string), the author’s password This method does not send any pings to weblogs.com, blo.gs, or trackbackenabled sites linked in the entry.
mt.getCategoryList Retrieve the categories defined for a weblog. This method returns an array of structs, each of which holds the following values about an individual entry: ✦ categoryId (string), the ID number of the category, which is specific to that weblog ✦ categoryName (string), the category’s name If a weblog does not use categories, the method returns an empty array.
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
265
Its parameters are as follows: ✦ blogid (int), the weblog’s ID number ✦ username (string), the author’s username ✦ password (string), the author’s password
mt.getPostCategories Retrieve the categories assigned to a weblog entry. When an entry has at least one category, this method returns an array of structs that identify each category associated with the entry: ✦ categoryId (string), the category’s ID number, which is specific to an individual weblog ✦ categoryName (string), the category’s name ✦ isPrimary (boolean), a flag that equals 1 (boolean true) for an entry’s primary category, or 0 (boolean false) otherwise The method returns an empty array when an entry has no assigned categories. Its parameters are as follows: ✦ postid (int), the ID number of the entry ✦ username (string), the author’s username ✦ password (string), the author’s password
mt.setPostCategories Set the categories for a weblog entry or remove all categories. This method returns 1 (boolean true) if the call was successful. Its parameters are as follows: ✦ postid (string), the ID number of the entry ✦ username (string), the author’s username ✦ password (string), the author’s password ✦ categories (array), an array of structs for each category Each struct in the categories array can contain three values: ✦ categoryId (int), the category’s ID number ✦ categoryName (string), the category’s name ✦ isPrimary (boolean), a flag that equals 1 (boolean true) for an entry’s primary category, and 0 otherwise
266 Movable Type 3 Bible, Desktop Edition The isPrimary value can be omitted from each struct. When it is not present, the first category in the categories array will be designated as the primary. Call this method with an empty array as the categories parameter to remove all categories from the entry.
mt.getTrackbackPings Retrieve information about trackback pings associated with an entry. This method returns an array of structs, each of which holds the following values about a trackback ping: ✦ pingIP (string), the IP address from which the ping was received ✦ pingTitle (string), the title of the weblog entry associated with the trackback ping ✦ pingURL (string), the ping’s URL If the entry has not received any pings, the method returns an empty array. Its parameter is as follows: ✦ postid (int), the entry’s ID number
mt.getRecentPostTitles Retrieve one or more entry titles from a particular weblog. This method returns an array of structs, each holding the following values about an individual entry: ✦ dateCreated (dateTime.iso8601), the date and time when the entry was originally saved ✦ postid (string), the ID number of the entry ✦ title (string), the entry’s title ✦ userid (string), the ID number of the entry’s author The dateCreated value uses the same time zone as the weblog containing the entry. Its parameters are as follows: ✦ blogid (int), the weblog’s ID number ✦ username (string), the author’s username ✦ password (string), the author’s password ✦ numberOfPosts (int), the number of entries to retrieve
Chapter 15 ✦ Connecting to Movable Type with XML-RPC
267
To retrieve all of a weblog’s entries using this method, use a numberOfPosts parameter of 0.
mt.supportedTextFilters Find out what text filters are supported by this particular installation of Movable Type. Filters process the text of entries as they are published, making changes to the HTML formatting to support validation and other purposes. On Movable Type’s entry-editing form, the Text Formatting field selects the filter that applies to the entry. By default, the Convert Line Breaks filter places all paragraphs between opening and closing P tags and converts line breaks to BR tags. This method returns an array of structs, each holding two values about an individual entry: ✦ key (string), a unique string identifier for the text formatting plug-in ✦ label (string), the name of the plug-in This method does not require any parameters. The key can be used with the MetaWeblog.newPost and MetaWeblog.editPost methods described earlier in this chapter.
mt.supportedMethods Find out what XML-RPC methods the Movable Type installation supports. This method returns an array of strings containing the names of each supported method, including methods of the Blogger and MetaWeblog APIs. One method is omitted: mt.supportedMethods itself. No parameters are required to call this method, which can be used to ensure that a Movable Type installation has up-to-date support for XML-RPC methods as they are added to the software.
Summary Movable Type’s browser-based interface is among its most well-regarded features, praised by users and technology journalists alike. One of the company’s advantages has been the work of Six Apart co-founder Mena Trott, who worked as a Web designer for a Silicon Valley Internet company before starting her new life as weblogging mogul. For this reason, it’s a little ironic that Movable Type makes it so easy to avoid using the interface. By supporting XML-RPC interfaces, Movable Type can serve a weblog in the background for a client that takes user input.
268 Movable Type 3 Bible, Desktop Edition Movable Type supports four application programming interfaces (APIs), including the three described in this chapter and the Atom API, which is covered in Chapter 19. XML-RPC, a protocol for exchanging XML data over HTTP, makes it simple for one program to call another program’s method over the Internet, receiving a response in the same format. With 80 implementations of XML-RPC available for Perl, Python, Java, and many other languages, computers can author Movable Type content as easily as humans can.
Enhancing Movable Type with Plug-Ins
16 C H A P T E R
✦
✦
✦
✦
In This Chapter
M
ovable Type’s template-driven publishing system offers more than 100 template tags that present weblog data and other kinds of content. These tags, which are structured in a format identical to HTML, produce output that’s incorporated into files as they are rebuilt. The net result of this process is a terrific contentmanagement system that feels like HTML but delivers customized functionality. This process succeeds because the duties of Web designers and programmers become more distinct. Designers work with HTML and template tags similar to HTML, concentrating on the end result — the content produced by tags. Six Apart delivers the functionality for those tags behind the scenes, using Perl code to efficiently collect and publish information. The same relationship has been taken further with plugins, which are add-on enhancement programs that enable programmers to graft new functionality onto Movable Type. Plug-ins, which also are written in the Perl language, work so seamlessly with Six Apart’s template tags that you won’t be able to tell them apart. Once you’ve downloaded a plug-in, Movable Type treats it just like one of its own template tags.
Finding plug-ins Downloading and installing programs Using the plug-ins directory Copying modules to the proper extlib directory Placing plug-in tags in a template Using additional category tags Retrieving data from a MySQL database Working with Movable Type’s database tables Putting Perl code on a template
✦
✦
✦
✦
270 Movable Type 3 Bible, Desktop Edition
Extending the Capabilities of Movable Type Anyone who can write Perl programs can extend the functionality of Movable Type by designing a plug-in, a process that has been documented by Six Apart to encourage the growth of a development community around the software. Movable Type’s plug-in framework turns a nicely designed weblog publishing tool into a more ambitious platform for a wide range of publishing and information-gathering applications. The place to begin experiencing this aspect of the software is the Movable Type Plugins directory at http://mt-plugins.org. This Web site, compiled by users independently of Six Apart, catalogs dozens of plug-ins offered for free download on the Web, many under an Open Source license that permits modifications to the code. Plug-in programming is described in Chapter 20, “Developing New Plug-Ins with Perl,” and Chapter 21, “Hooking into Movable Type with Callbacks.”
This chapter looks at plug-ins from a user’s perspective, describing how you can install and use a collection of useful plug-ins. There are far more plug-ins available for the software than can be covered in this book, but once you have connected a few to your Movable Type installation, the process of adding more on your own should be fairly straightforward. The plug-ins covered in this chapter were developed by Brad Choate, an inventive programmer who has been publishing with Movable Type since the first public release of the software in October 2001. Brad Choate, whose site is found at http://www.bradchoate.com, has developed 16 plug-ins at the time of this writing. You’re already using one of them — Sanitize, a program that strips undesired HTML out of comments, was incorporated into Movable Type with version 2.6. He also wrote the code to support the MTElse tag.
Linking to Previous Years Often, some of the most useful Movable Type plug-ins are also the simplest. Brad Choate’s MTOnThisDay plug-in offers an easy-to-implement tag that adds an “on this day” feature to your weblog archives that looks back one, two, or more years ago for entries written on the same calendar date. You can see an example circled in Figure 16-1.
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
271
Figure 16-1: Viewing content produced with the MTOnThisDay plug-in.
This plug-in adds an MTOnThisDay container tag that can be incorporated into templates. Listing 16-1 contains the HTML code that produced the “On This Day” section of the Web page in Figure 16-1.
Listing 16-1: Adding On This Day Archive Links to a Page On This Day
Also in:
The final four tags provide category-aware containers that display content only if the value of their name attribute matches the current category (on a category archive page) or a weblog entry’s selected categories. The following template code displays an icon graphic only if a weblog entry belongs to a category named Disney:
This could appear in the category archive template, displaying the icon only for the Disney category’s archive page. It also could be placed within an MTEntries container, displaying the icon when an entry belongs to the Disney category.
276 Movable Type 3 Bible, Desktop Edition The MTIfCategory and MTIfNotCategory containers test for any category. MTIfPrimaryCategory and MTIfNotPrimaryCategory are more specific, checking only the primary category for entries.
Retrieving Weblog Data Using MySQL A Movable Type installation that uses MySQL as its database can take advantage of the SQL plug-in, a set of tags that retrieve entries, comments, and other weblog data from the database using Structured Query Language (SQL). The plug-in can be downloaded as a ZIP archive from Brad Choate’s Web site at http://bradchoate.com/weblog/2002/07/11/sql-plugin.
Use the following steps to set up this plug-in to work: 1. Place the sql.pl Perl script in Movable Type’s plugins directory. 2. In the extlib directory, create a subdirectory named bradchoate if one does not already exist. 3. Store the sql.pm Perl module in this new subdirectory. Once the plug-in has been installed, you can use the nine template tags listed in Table 16-2.
Table 16-2 MTAuthors Plug-in Tags Tag
Attributes
Description
MTSQL
default, query
A container tag that executes the specified SQL query, looping through the matching rows
MTSQLAuthors
default, query, unfiltered
A container tag that uses the query to select weblog editors
MTSQLCategories
default, query, unfiltered
A container tag that uses the query to select weblog categories
MTSQLColumn
column, default, format
Display the row column identified by the column attribute formatted according to the format attribute
MTSQLComments
default, query, unfiltered
A container tag that uses the query to select comments
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
277
Tag
Attributes
Description
MTSQLEntries
default, query, unfiltered
A container tag that uses the query to select weblog entries
MTSQLFooter
Display this tag’s contents only in the container’s last row
MTSQLHeader
Display this tag’s contents only in the container’s first row
MTSQLPings
default, query, unfiltered
A container tag that uses the query to select trackback pings
The MTSQL plug-in requires familiarity with MySQL, SQL, and the database tables adopted by Movable Type. Several tags share attributes in common: default, which assigns a value that will be returned when an SQL query finds no matching rows, and unfiltered=”1”, which suspends Movable Type’s normal filtering rules. When unfiltered is not present or has a value of 0, Movable Type may take some rows out of the result returned from an SQL query. For example, a category that doesn’t belong to the weblog will be omitted whenever MTSQLCategories is used to retrieve category data. All of the plug-in’s container tags have a query tag to define the SQL query that retrieves rows from the database. The following template code displays a weblog’s trackback pings grouped by the name of the weblog that sent the pings:
|
The default attribute contains a message, “No pings found,” which is displayed only when the database does not contain any trackback pings. trackback pings presented with this code are shown in Figure 16-2.
278 Movable Type 3 Bible, Desktop Edition
Figure 16-2: Pulling trackback pings directly from a MySQL database.
Attribute values for any container tag can include the output of Movable Type template tags. The tags should be surrounded by [ and ] brackets instead of < and > characters, as in this revised trackback ping example: From ,
The reference to [MTBlogName] will be replaced with the output of the MTBlogName template tag, displaying the title of the weblog.
Working with Existing Template Tags The easiest way to take advantage of the SQL plug-in is to work with container tags that represent specific database tables in MySQL, such as MTSQLCategories or MTSQLEntries. A query constructed for these tags must return an ID number as the first column. Often, that’s all you need from the database, because you can use Movable Type in conjunction with the plug-in. Listing 16-2 demonstrates this capability, using an MTSQLEntries tag to select entries that make use of the Extended Entry field.
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
279
Everything within the opening and closing MTSQLEntries tags is a normal Movable Type template tag, formatted in a manner similar to how the Main Index template displays entries.
Listing 16-2: Retrieving Entries from the Database
Posted by at | Comments () | Trackback ()
Author: E-mail: URL:
Comment:
Making full use of the SQL plug-in requires knowledge of MySQL and Movable Type’s database format. The next several sections document all of the table fields.
Retrieving Author Data The mt_author database table contains accounts for each editor with an account created on your Movable Type server. If you have installed the MTAuthors plug-in, you can use it to display rows retrieved from this table. The fields in this table are described in Table 16-3.
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
281
Table 16-3 mt_author Database Fields Tag
Data Type
Default
Description
author_id
Int
None
The database’s primary key
author_name
varchar(50)
“”
Username
author_type
Tinyint
0
Type: 1 (editor), 2 (commenter)
author_nickname
varchar(50)
NULL
Nickname
author_password
varchar(50)
“”
Password
author_email
varchar(75)
“”
E-mail address
author_url
varchar(255)
NULL
Home page address
author_can_ create_blog
Tinyint
NULL
Create new weblog? 1 (yes), 0 (no)
author_can_ view_log
Tinyint
NULL
View activity log? 1 (yes), 0 (no)
author_hint
varchar(75)
NULL
Password reminder
author_created_by
Int
NULL
ID of editor who created this author
author_public_key
Text
NULL
Reserved for future use
author_preferred_ language
varchar(50)
NULL
Language preference
author_remote_ auth_username
varchar(50)
NULL
TypeKey username
author_remote_ auth_token
varchar(50)
NULL
TypeKey token
Retrieving Weblog Data The mt_blog database table holds information about each weblog on the server. Many of its fields can be presented using tags that can be used within an MTBlogs container. The fields in this database table are described in Table 16-4.
282 Movable Type 3 Bible, Desktop Edition Table 16-4 mt_blog Database Fields Tag
Data Type
Default
Description
blog_id
Int
None
The database’s primary key
blog_name
varchar(255)
“”
Name
blog_description
Text
NULL
Description
blog_site_path
varchar(255)
NULL
Main directory
blog_site_url
varchar(255)
NULL
Home page URL
blog_archive_path
varchar(255)
NULL
Archive directory
blog_archive_url
varchar(255)
NULL
Archive URL
blog_archive_type
varchar(255)
NULL
List of archive types in use (example: “Individual,Monthly”)
blog_archive_ type_preferred
varchar(25)
NULL
Preferred archive type
blog_days_ on_index
smallint
NULL
Days to display on home page
blog_language
varchar(5)
NULL
Language for date and time display
blog_file_ extension
varchar(10)
NULL
Archive file extension
blog_email_ new_comments
Tinyint
NULL
E-mail new comments? 1 (yes), 0 (no)
blog_email_ new_pings
Tinyint
NULL
E-mail new trackback pings? 1 (yes), 0 (no)
blog_allow_ comment_html
Tinyint
NULL
Allow HTML in comments? 1 (yes), 0 (no)
blog_autolink_ urls
Tinyint
NULL
Add links to URLS in comments? 1 (yes), 0 (no)
blog_sort_ order_posts
varchar(8)
NULL
Entry sort order (ascend or descend)
blog_sort_ order_comments
varchar(8)
NULL
Comment sort order (ascend or descend)
blog_allow_ comments_default
Tinyint
NULL
Allow comments? 1 (yes), 0 (no)
blog_allow_ pings_default
Tinyint
NULL
Allow trackback pings? 1 (yes), 0 (no)
blog_server_ offset
Float
NULL
Server time zone offset from UTC
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
283
Tag
Data Type
Default
Description
blog_convert_ paras
varchar(30)
NULL
Entry formatting plug-in
blog_convert_ paras_comments
varchar(30)
NULL
Comment formatting plug-in
blog_status_ default
Tinyint
NULL
Publication status: 1 (draft), 2 (publish)
blog_allow_ anon_comments
Tinyint
NULL
Allow anonymous comments? 1 (yes), 0 (no)
blog_allow_ reg_comments
Tinyint
NULL
Allow TypeKey registered comments? 1 (yes), 0 (no)
blog_allow_ unreg_comments
Tinyint
NULL
Allow non-TypeKey comments? 1 (yes), 0 (no)
blog_moderate_ unreg_comments
Tinyint
NULL
Moderate unregistered comments? 1 (yes), 0 (no)
blog_require_ comment_emails
Tinyint
NULL
Require e-mail addresses in comments? 1 (yes), 0 (no)
blog_manual_ Tinyint approve_commenters
NULL
Manually approve commenters? 1 (yes), 0 (no)
blog_words_in_ excerpt
smallint
NULL
Words in entry excerpts
blog_ping_weblogs
Tinyint
NULL
Notify weblogs.com of new entries? 1 (yes), 0 (no)
blog_ping_blogs
Tinyint
NULL
Notify blo.gs of new entries? 1 (yes), 0 (no)
blog_ping_others
Text
NULL
URLs of other services to notify, one per line
blog_mt_ update_key
varchar(30)
NULL
Recently updated key
blog_ autodiscover_ links
Tinyint
NULL
Use trackback autodiscovery? 1 (yes), 0 (no)
blog_welcome_msg
Text
NULL
Welcome message
blog_old_style_ archive_links
Tinyint
NULL
Use pre-version 3 style archive links? 1 (yes), 0 (no)
blog_archive_ tmpl_monthly
varchar(255)
NULL
Monthly archive template filename
blog_archive_ tmpl_weekly
varchar(255)
NULL
Weekly archive template filename Continued
284 Movable Type 3 Bible, Desktop Edition Table 16-4 (continued) Tag
Data Type
Default
Description
blog_archive_ tmpl_daily
varchar(255)
NULL
Daily archive template filename
blog_archive_ tmpl_individual
varchar(255)
NULL
Individual archive template filename
blog_archive_ tmpl_category
varchar(255)
NULL
Category archive template filename
blog_google_ api_key
varchar(32)
NULL
Google API key
blog_sanitize_ spec
varchar(255)
NULL
HTML tags and attributes to allow in comments (separated by commas)
blog_cc_license
varchar(255)
NULL
Creative Commons license
blog_is_dynamic
Tinyint
NULL
Reserved for future use
blog_remote_ auth_token
varchar(50)
“”
TypeKey token
Retrieving Category Data Category information in Movable Type requires two database tables: mt_category, which contains categories that have been created for any weblog on the server, and mt_placement, which represents categories assigned to weblog entries. Fields from the mt_category table can be presented using tags that can be employed within an MTCategories container. Table fields are described in Table 16-5.
Table 16-5 mt_category Database Fields Tag
Data Type
Default
Description
category_id
Int
None
The database’s primary key
category_blog_id
int
0
ID of category’s weblog
category_allow_ pings
tinyint
NULL
Accept trackback pings? 1 (yes), 0 (no)
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
285
Tag
Data Type
Default
Description
category_label
varchar(100)
NULL
Name
category_ description
text
NULL
Description
category_ author_id
int
NULL
ID of editor who created this category
category_ping_ urls
text
NULL
URLs of trackback pings to send with each new entry, one per line
Fields in the mt_placement category can be displayed by using the template that would appear in an MTEntryCategories tag. Table fields for mt_placement are described in Table 16-6.
Table 16-6 mt_placement Database Fields Tag
Data Type
Default
Description
placement_id
Int
None
The database’s primary key
placement_entry_id
Int
0
ID of weblog entry
placement_blog_id
Int
0
ID of weblog
placement_category_id
Int
0
ID of weblog category
placement_is_primary
Tinyint
0
Is this an entry’s primary category? 1 (yes), 0 (no)
Retrieving Comment Data The mt_comment database table holds comments submitted by visitors to any of your weblogs, whether they have been submitted anonymously, signed with an e-mail address, or authenticated by Six Apart’s TypeKey service. Tags within an MTComments container can be used to display fields from this table. The fields in this table are listed in Table 16-7.
286 Movable Type 3 Bible, Desktop Edition Table 16-7 mt_comment Database Fields Tag
Data Type
Default
Description
comment_id
int
None
The database’s primary key
comment_blog_id
int
0
ID of comment’s weblog
comment_entry_id
int
0
ID of comment’s weblog entry
comment_ip
varchar(16)
NULL
IP address
comment_author
varchar(100)
NULL
Author’s nickname
comment_email
varchar(75)
NULL
Author’s e-mail address
comment_url
varchar(255)
NULL
Author’s home page
comment_commenter_id
int
NULL
ID of TypeKey registered comment author
comment_visible
tinyint
NULL
Display comment? 1 (yes), 0 (no)
comment_text
text
NULL
Text
comment_created_on
datetime
0000Creation date/time 00-00 00:00:00
comment_modified_on
timestamp
NULL
Last modification date/time
comment_created_by
int
NULL
Reserved for future use
comment_modified_by
int
NULL
Reserved for future use
Retrieving Weblog Entry Data The mt_entry database table holds the most important part of your Movable Type database: the entries that comprise the primary content of each weblog. Most of these table fields, which are documented in Table 16-8, can be presented using the tags that work within an MTEntries container or in the individual archive template.
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
287
Table 16-8 mt_entry Database Fields Tag
Data Type
Default
Description
entry_id
int
None
The database’s primary key
entry_blog_id
int
0
ID of entry’s weblog
entry_status
tinyint
0
Publication status: 1 (draft), 2 (publish)
entry_author_id
int
0
ID of entry’s author
entry_allow_comments
tinyint
NULL
Allow comments? 1 (yes), 0 (no)
entry_allow_pings
tinyint
NULL
Allow trackback pings? 1 (yes), 0 (no)
entry_convert_breaks
varchar(30)
NULL
Entry formatting plug-in
entry_category_id
int
NULL
ID of entry’s primary category
entry_title
varchar(255) NULL
Title
entry_excerpt
text
NULL
Excerpt
entry_text_more
text
NULL
Extended entry
entry_to_ping_urls
text
NULL
URLs of trackback pings to send, one per line
entry_pinged_urls
text
NULL
URLs of previously sent trackback pings, one per line
entry_keywords
text
NULL
Keywords
entry_tangent_cache
text
NULL
Reserved for future use
entry_created_on
datetime
0000Creation date/time 00-00 00:00:00
entry_modified_on
timestamp
NULL
Modification date/time
entry_basename
varchar(50)
NULL
Unique 15-character text identifier based on entry title
288 Movable Type 3 Bible, Desktop Edition
Retrieving Banned IP Address Data The mt_ipbanlist database table contains a list of IP addresses that are banned from sending visitor comments or trackback pings to a weblog on your Movable Type installation. An IP address is a set of four byte values (0 to 255) separated by dot characters, such as 192.0.34.166. Everything connected to the Internet must have a unique IP address — the domain-name system maps easyto-remember names like example.com to the IP address associated with that name. Banning IP addresses in Movable Type works well only when a sender keeps the same address over a period of time, which makes it more effective for blocking unwanted trackback pings than visitor comments, because most Internet users connect using accounts that assign different IP addresses each time they log on. No Movable Type template tags are associated with the fields in this table. You can display them using the MTSQL container and MTColumn tag. The fields in the mt_ipbanlist table are listed in Table 16-9.
Table 16-9 mt_ipbanlist Database Fields Tag
Data Type
Default
Description
ipbanlist_id
int
None
The database’s primary key
ipbanlist_ blog_id
int
0
ID of banned weblog
ipbanlist_ip
varchar(15)
“”
IP address
ipbanlist_ created_on
datetime
0000-00-00 00:00:00
Creation date/time
ipbanlist_ modified_on
timestamp
NULL
Last modification date/time
ipbanlist_ created_by
int
NULL
ID of banning author
ipbanlist_ modified_by
int
NULL
ID of modifying author
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
289
Retrieving Activity Log Data The mt_log database table stores entries in Movable Type’s activity log, the file that tracks usage of the server by editors and other events such as unsuccessful trackback pings. There are no template tags to present this information, so the MTSQL and MTSQLColumn tags are required to display them. Table fields in this database are delineated in Table 16-10.
Table 16-10 mt_log Database Fields Tag
Data Type
Default
Description
log_id
Int
None
The database’s primary key
log_message
varchar(255)
NULL
Message
log_ip
varchar(16)
NULL
IP address associated with the event
log_created_on
datetime
0000-00-00 00:00:00
Creation date/time
log_modified_on
timestamp
NULL
Modification date/time
log_created_by
int
NULL
Reserved for future use
log_modified_by
int
NULL
Reserved for future use
Retrieving E-Mail Notification Data The mt_notification database table serves as a mailing list for a Movable Type weblog, holding the users who have requested an e-mail when a new entry has been published. Because no Movable Type template tags are associated with this table, you can collect and present the fields in Table 16-11 with the MTSQL and MTColumn tags.
Table 16-11 mt_notification Database Fields Tag
Data Type
Default
Description
notification_id
Int
None
The database’s primary key
notification_ blog_id
int
0
ID of weblog
Continued
290 Movable Type 3 Bible, Desktop Edition Table 16-11 (continued) Tag
Data Type
Default
Description
notification_ name
varchar(50)
NULL
Name
notification_ email
varchar(75)
NULL
E-mail address
notification_ url
varchar(255) NULL
notification_ created_on
datetime
0000-00-00 Subscription creation date 00:00:00
notification_ modified_on
timestamp
NULL
Subscription last modification date
notification_ created_by
int
NULL
Reserved for future use
notification_ modified_by
int
NULL
Reserved for future use
Home page URL
Retrieving Author Permissions The mt_permission database holds the role-based permissions for editors assigned to your weblogs, which can be incorporated into templates with the MTSQL and MTColumn tags. Table fields for the mt_permission database appear in Table 16-12.
Table 16-12 mt_permission Database Fields Tag
Data Type
Default
Description
permission_id
Int
None
The database’s primary key
permission_author_id
Int
0
ID of author
permission_blog_id
Int
0
ID of weblog
permission_role_mask
smallint
NULL
Permission bitmask
permission_entry_prefs
varchar(255)
NULL
List of permissions (separated by commas)
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
291
Retrieving Plug-In Data The mt_plugin database table offers a place for plug-ins that need to store data persistently. A plugindata_plugin field serves as a unique identifier for the plug-in, such as its name, whereas the plugindata_key and plugindata_data fields can be used as storage places. Rows in this table are used for different purposes in different plug-ins, so as you might expect, there are no Movable Type template tags to present this information. Use the MTSQL and MTSQLColumn tags to collect and publish these fields in a template. Table fields are shown in Table 16-13.
Table 16-13 mt_plugin Database Fields Tag
Data Type
Default
Description
plugin_id
int
None
The database’s primary key
plugindata_plugin
varchar(50)
“”
Text identifier for the plug-in
plugindata_key
varchar(255)
“”
Plug-in text data, up to 255 characters
plugindata_data
mediumtext
NULL
Longer plug-in data
Retrieving Session Data The mt_session database, a new addition in Movable Type 3, supports session management. This information is highly transitory and there’s little reason to present its data on a static Web page built from a template. You can, however, use the SQL plug-in’s tags to publish fields from this table. They are shown in Table 16-14.
Table 16-14 mt_session Database Fields Tag
Data Type
Default
Description
session_id
int
None
The database’s primary key
session_data
text
NULL
Session data
session_email
varchar(255)
NULL
E-mail address associated with the session (if any) Continued
292 Movable Type 3 Bible, Desktop Edition Table 16-14 (continued) Tag
Data Type
Default
Description
session_name
varchar(255)
NULL
Short identifier for the session
session_start
int
0
Time the session was created as a UNIX time value
session_kind
char(2)
NULL
Two-letter code identifying the purpose of the session
Retrieving Trackback Ping Data The mt_tbping and mt_trackback database tables contain trackback pings, which are incoming messages sent to your Movable Type weblogs by other sites using the trackback protocol. Tags that would ordinarily be used inside an MTPings container can display fields from this table. The table fields are described in Tables 16-15 and 16-16.
Table 16-15 mt_tbping Database Fields Tag
Data Type
Default
Description
tbping_id
Int
None
The database’s primary key
tbping_blog_id
Int
0
ID of trackback ping’s weblog
tbping_tb_id
Int
0
ID of trackback ping’s weblog entry
tbping_title
varchar(255)
NULL
Title
tbping_excerpt
Text
NULL
Excerpt
tbping_source_url
varchar(255)
NULL
Sender’s home page URL
tbping_ip
varchar(15)
NULL
IP address
tbping_blog_name
varchar(255)
NULL
Sender’s weblog name
tbping_created_on
Datetime
000000-00 00:00:00
Creation date/time
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
293
Tag
Data Type
Default
Description
tbping_modified_on
Timestamp
NULL
Last modification date/time
tbping_created_by
Int
NULL
Reserved for future use
tbping_modified_by
Int
NULL
Reserved for future use
Table 16-16 mt_trackback Database Fields Tag
Data Type
Default
Description
trackback_id
Int
None
The database’s primary key
trackback_blog_id
Int
0
ID of weblog
trackback_title
varchar(255)
NULL
Title
trackback_ description
Text
NULL
Description
trackback_rss_file
varchar(255)
NULL
Reserved for future use
trackback_url
varchar(255)
NULL
Incoming trackback URL
trackback_entry_id
Int
0
ID of weblog entry
trackback_ category_id
Int
0
ID of weblog category
trackback_ passphrase
varchar(30)
NULL
Password required to send trackback pings
trackback_is_ disabled
Tinyint
0
Accept no more trackback pings? 1 (yes), 0 (on)
trackback_ created_on
datetime
000000-00 00:00:00
Aggregator creation date/time
trackback_ modified_on
timestamp
NULL
Aggregator modification date/time
trackback_ created_by
Int
NULL
Reserved for future use
trackback_ modified_by
Int
NULL
Reserved for future use
Retrieving Template Data The mt_template and mt_templatemap database tables manage templates and linked template files for each weblog on a Movable Type installation.
294 Movable Type 3 Bible, Desktop Edition The mt_template table provides information about each template, such as its name, output filename, and whether to rebuild it whenever index templates are generated. The mt_templatemap table associates archive templates with particular archive types. The archive type must be one of the following five values, capitalized as indicated: Category, Daily, Individual, Monthly, or Weekly. Presenting this data in a template requires SQL plug-in tags. Table fields are shown in Tables 16-17 and 16-18.
Table 16-17 mt_template Database Fields Tag
Data Type
Default
Description
template_id
int
None
The database’s primary key
template_blog_id
int
0
ID of template’s weblog
template_name
varchar(50)
“”
Name
template_type
varchar(25)
“”
Template type (a string such as index or category)
template_outfile
varchar(255)
NULL
Filename of rendered page
template_ rebuild_me
tinyint
1
Rebuild with index templates? 1 (yes), 0 (no)
template_text
text
NULL
Full text of template
template_ linked_file
varchar(255)
NULL
Linked filename
template_ linked_file_mtime
varchar(10)
NULL
Linked file’s last modification date/time
template_ linked_file_size
mediumint
NULL
Linked file’s size
Table 16-18 mt_templatemap Database Fields Tag
Data Type
Default
Description
templatemap_id
int
None
The database’s primary key
templatemap_ blog_id
int
0
ID of weblog
templatemap_ template_id
int
0
ID of template
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
295
Tag
Data Type
Default
Description
templatemap_ archive_type
varchar(25)
NULL
Template type (a string such as Daily or Category)
templatemap_ file_template
varchar(255)
NULL
Filename of rendered page
templatemap_ is_preferred
tinyint
0
Preferred template among those belonging to its archive type on this weblog? 1 (yes), 0 (no)
Retrieving Trackback Aggregator Data Weblog entries and categories in a Movable Type weblog can serve as trackback content aggregators, collecting incoming trackback pings. On an individual weblog entry, these trackback pings serve as a form of feedback comparable in some ways to visitor comments. On a category, they facilitate collaboration between different weblogs, a style of publishing that Six Apart calls a trackback content aggregator. Tags that would ordinarily be used inside an MTPings container can display fields from this table.
Programming Templates with Scripting Tags If you can’t accomplish something with any other Movable Type plug-in, you can get it done with PerlScript, a plug-in by Brad Choate that enables Perl commands to be executed in a template. The output of the script appears on the rendered page as if it were produced by template tags. Anything that the Perl programming language can handle can also be handled by an opening and closing MTPerlScript tag, making it the most powerful plug-in available for Movable Type.
Gotcha
This plug-in also has the largest security implications of any plug-in, because it enables arbitrary Perl code to be executed on your server by anyone with template-editing privileges on one of your weblogs. To pick one of many possible disasters that could happen through unintentional or malicious use of this plug-in: A typo in a Perl command recursively deletes every file in your Movable Type directory and its subdirectories. As any fan of Spiderman could tell you, with great power comes great responsibility. For this reason, PerlScript should be limited to environments where all template-editing weblog editors can be fully trusted.
296 Movable Type 3 Bible, Desktop Edition Take a look at a short example that uses the plug-in to identify the Web server on which the software runs: print “
Powered by $ENV{‘SERVER_SOFTWARE’}
”;” . ucfirst(“”);
This code displays each category name for a weblog, using the Perl ucfirst() function to display the first letter of the name as an uppercase letter. Template tags also are evaluated after the script has been run.
Chapter 16 ✦ Enhancing Movable Type with Plug-Ins
297
The preprocess=”1” attribute of the MTPerlScript tag prevents processing before the Perl script runs. The reprocess=”1” attribute does the same thing afterward. A script can define one or more subroutines by placing them within their own enclosing MTPerlScript tags and using two attributes, once and package. The package attribute designates a Perl namespace for the subroutines within a script, enabling the routines to be called from within other MTPerlScript tags in the same template. The once attribute, with a value of 1, causes the code to be evaluated one time only. Here’s an example that uses a subroutine and two MTPerlScript tags: sub day { use Time::JulianDay; my($in_time) = @_; return local_julian_day($in_time); } print “
” . julian::day(time);
These two scripts produce the numeric Julian value for the current date, such as 2453218 on July 31, 2004. When a template contains more than one Perl script, you can use a package name to refer to subroutines in that package. The once attribute can be used for only one script in each package. The cache=”1” attribute speeds up processing by caching the Perl code in a script, making it execute much more quickly within Movable Type containers that loop. Any Movable Type template tags within the script are evaluated only once, so you cannot cache Perl code that relies on tags with changing values (such as an MTEntryTitle tag within an MTEntries container). The MTPerlScript opening tag also can contain one or more user-defined attributes as name-value pairs, as in this example:
$args{greeting}!
The %args hash holds the tag arguments, so the preceding code produces the following HTML output:
Saluton, Mondo!
298 Movable Type 3 Bible, Desktop Edition Listing 16-4 contains a script that downloads stock quote data from Yahoo! Finance for a specific ticker symbol, displaying the current price, change, date, and time in the following format:
RHAT: 22.09 (+0.09)
at 6/24/2004 4:00pm
” . $symbol . “: “ . $price . “ (“ . $change . “) “; print “at “ . $s_date . “ “ . $s_time . “
”; }” . $text; print “
” . $author . “ “ . $email . “” . $ip; print “
” . $created; print “
Edit”; } $sth->finish;
The PerlScript plug-in also offers another built-in variable, %stash, which holds the Movable Type stash, a hash that holds context variables from parent tags. You’ll work with it in Chapter 20, “Developing New Plug-Ins with Perl.”
Gotcha
Plug-in author Brad Choate warns in his documentation about the security risks of installing this on a shared Movable Type server: “Anyone who can edit templates on your server can basically control your Web site with this plug-in under the hood. The Perl code contained within your PerlScript tags is not sandboxed at all: file and database operations can be performed, infinite loops can tie up your server — any number of things can go wrong.”
300 Movable Type 3 Bible, Desktop Edition Because Movable Type plug-ins are also authored in Perl, you can create plugin tags that deliver the desired functionality and are inherently more secure. This topic is explored in Chapters 20 and 21.
Summary The Movable Type plug-ins presented in this chapter are representative of the variety of programs available to enhance the software. Since plug-in support was introduced in June 2002 for version 2.2 of Movable Type, dozens of plug-ins have been released for purposes big and small. Many have found their way into the Movable Type Plug-In Directory at http://mt-plugins.org. Plug-in quality varies widely. Anyone who can write simple scripts in Perl can try their hand at Movable Type plug-in development. Some programs you might find in the plug-in directory and other Web sites will be incomplete, never fully released, or buggy. At this point, though, there are enough excellent plug-ins available that the time spent looking for them is well worth spending. A well-designed plug-in integrates fully with Movable Type, performing as if it were part of the software’s standard installation, and works in conjunction with existing template tags. Plug-ins often require no configuration other than saving a few files in the software’s plugins and extlib directories (or a subdirectory of extlib). Now that Movable Type 3 offers even stronger integration with plug-ins, there’s likely to be even more reason to exploit this feature of the software.
Presenting External Web Content with Plug-Ins
C
hapter 16, “Enhancing Movable Type with PlugIns,” demonstrated how the software’s large number of add-on programs can present information from your Web site in novel and useful ways. Plug-ins are just as effective for presenting information from other Web sites. They can retrieve data from other sites and Internet servers, storing it in Movable Type template tags and publishing it when pages are rebuilt. In this chapter, you learn about several useful datagrabbing site enhancements: ✦ The Weather Underground plug-in contacts the Web site of the same name, collecting the current weather conditions, temperature, and humidity for a city, state, or country of your choosing. ✦ The MT-QOTD plug-in connects to a quote-ofthe-day server, an old-school Internet service that offers a random quotation when contacted by a client. ✦ Another plug-in, RandomLine, provides an alternative way to offer the same feature. ✦ The MT-Amazon plug-in pulls an amazing amount of product data from the giant e-commerce site, enabling your weblog to promote and sell products. You also can participate in Amazon’s Affiliates program and get paid for referring customers.
17 C H A P T E R
✦
✦
✦
✦
In This Chapter Retrieving data from another Web site Tracking weather conditions with a plug-in Presenting plug-in data in a template Presenting random text and HTML Joining the Amazon Affiliates program Becoming a registered Amazon developer Searching Amazon’s product database Retrieving product lists prepared by Amazon Reading lists created by customers
✦
✦
✦
✦
302 Movable Type 3 Bible, Desktop Edition These plug-ins and others like them represent a one-of-a-kind opportunity for Web publishers: a chance to improve your site while someone else does most of the work.
Presenting Weather Data You can publish local weather information for more than 60,000 cities on your Movable Type weblog with the Weather Underground plug-in by Gavin Estey: http://www.estey.com/mt
This plug-in requires the Perl module Weather::Underground, which retrieves temperature, humidity, and other weather condition data from the Weather Underground Web site: http://www.wunderground.com
Chapter 2, “Preparing a Web Server for Movable Type,” describes how to download and install Perl modules using the Central Perl Archive Network (CPAN). In many cases, installing Weather::Underground can be accomplished with a single command in this manner: /usr/bin/perl -MCPAN -e ‘install Weather::Underground’
The reference to /usr/bin/perl might need to be changed, depending on where Perl is found on your server and your operating system. The Weather Underground plug-in introduces Movable Type tags that display simple weather information on a page, much like the example shown in Figure 17-1.
Figure 17-1: Displaying weather data on a page.
Chapter 17 ✦ Presenting External Web Content with Plug-Ins
303
The weather sidebar in Figure 17-1 was produced with the following HTML code: Orlando: : °F (°C) % humidity
The container tag MTWeatherUnderground holds weather data for a location identified in its place attribute, which takes the same queries as the Weather Underground Web site — specify a city and state, zip code, airport code, or country. Within the container, the MTWeatherUCelsius and MTWeatherUFahrenheit tags display the current temperature in those scales, and MTWeatherUHumidity reports the humidity. The MTWeatherConditions tag contains a short description of the present conditions, such as “Mostly cloudy,” “Scattered clouds,” “Heavy thunderstorms,” “Smoke,” and “Widespread dust.” The last tag you can use, MTWeatherUPlace, identifies the place. This can be helpful when presenting weather data by zip code, as shown in the following example: : : °F (°C) % humidity
Weather data is updated each time the page containing the tag rebuilds.
Gotcha
When you rebuild pages of a site that uses the Weather Underground plugin, you might see an error message about an “uninitialized value” in the file Underground.pm. The cause appears to be a bug in the Weather::Underground Perl module, but it doesn’t affect the performance of the plug-in, so it can safely be ignored.
Publishing Random Quotes and Other Text Since the early days of the Internet, port 17 on a server has been reserved for use by qotd (quote of the day), a service that displays a randomly selected quote whenever a client makes a connection.
304 Movable Type 3 Bible, Desktop Edition This obscure network service can be used to test network connectivity, but that high-minded purpose makes it sound more important than it really is — a quote server is just a fun thing to have around. If you know the address of a server that offers qotd, you can try it by making a telnet connection to port 17, as demonstrated by this command and the resulting output: $ telnet quote.cbk.net 17 “The secret of being miserable is to have leisure to bother about whether you are happy or not. The cure for it is occupation.” George Bernard Shaw (1856-1950)
Neil Sedley offers MT-QOTD, a Movable Type plug-in that pulls a quote from a designated qotd server, displaying it on a Web page: http://neil.sedley.org/qotd.htm
You can install this free plug-in by copying the Perl script mt-qotd.pl into Movable Type’s plugins subdirectory. After it has been installed, add the MTQotd tag to a template in which you want the quote to appear. This tag has one attribute, host, which identifies the qotd server from which to pull quotes. Sedley recommends using the standard attribute encode_html with a value of 1 (true) so that HTML formatting in quotes is displayed correctly. The following HTML code centers a randomly selected quote from the server at quote.cbk.net:
Price: ( used)
| Released by on Price: ( used) |
Last updated:
Similar searches can be produced with the “Artist” method, which looks for a musician’s work; the “Author” method, which finds books by a particular author; and the “Director” method, which finds a director’s work in DVD, VHS, or both (the video product line). All of these searches require that the line attribute identifies one of the relevant product lines for that method. Another specialized search requires the “Manufacturer” method, which discovers a company’s products. This appears to work with all of Amazon’s product lines.
Presenting Products by Number Amazon uniquely identifies each of its products with one of three numbers: ✦ An International Standard Book Number (ISBN) for books ✦ A Uniform Product Code (UPC) for music ✦ An Amazon Standard Item Number (ASIN) for every product it sells The ASIN code for a book is identical to its ISBN, so you can see them used interchangeably on Amazon and elsewhere. UPC numbers also can be used as an alternative means of identifying popular and classical music.
314 Movable Type 3 Bible, Desktop Edition The “Asin” method of an MTAmazon tag can retrieve one or more products by their ASIN (or ISBN) codes. The search attribute should be the code (for a single product) or a series of codes separated by commas (for multiple products), as shown in Listing 17-3.
Listing 17-3: A Product Information Page Weblog Books
| Java best-sellers: | Wish list:
318 Movable Type 3 Bible, Desktop Edition Listing 17-5 (continued) | Odd products: |
If you’ve heard anything about the Rainforest Cafe, it’s likely been the atmosphere,
Chapter 18 ✦ Publishing RSS Syndication Files
323
first and foremost. The entire restaurant is themed to look like a tropical rainforest--from the leafy canopy to the animatronic animals placed throughout.
]]>
328 Movable Type 3 Bible, Desktop Edition If you want to include HTML produced by a template tag, omit the remove_html attribute. You can convert HTML into an encoded form by adding an encode_html attribute of 1, which replaces &, , and other characters with entity codes. The lastBuildDate element uses several template tags and a plug-in:
When using this element in a template, be sure to leave a space at the end of the format attribute of the MTEntryDate tag. Because no template tag holds the date and time that a weblog was last updated, this information must be collected from the most recently authored weblog entry, which can be retrieved using an MTEntries tag with a lastn value of 1. Within the MTEntries container, you can use any of an entry’s template tags. Dates in an RSS 2.0 feed must be formatted according to the rules of RFC 822, an Internet standard governing the structure of an e-mail message, with one exception: a year can be two digits or four. Here’s an example of two correctly formatted RFC 822 timestamps: Sat, 17 Apr 2004 19:23:04 -0500 Mon, 12 Apr 2004 02:51:52 GMT
The MTEntryDate tag presents the date and time of an entry according to the guidelines established in its format attribute. In this attribute, the order and format of each part of a timestamp are specified by strftime codes, as described in Chapter 9, “Designing a Weblog with Templates.” MTEntryDate produces everything needed for an RFC 822 date but the last part, the name or time offset that identifies the time zone used by your weblog. The preceding examples use a numeric offset of -500 (Eastern time in the U.S. and Canada) and the name GMT, respectively.
A weblog’s time zone is determined by the Timezone configuration setting. To see the current value, in the browser interface, click the Weblog Config sidebar menu button, and then scroll to the bottom of the Core Setup page. In an RSS 2.0 template, you can specify the time zone manually by using one of the codes or offset values in Table 18-1. You also can use any other offset from -1200 to +1300 and single-letter military time zone codes (A through I and K through Z).
Chapter 18 ✦ Publishing RSS Syndication Files
329
Table 18-1 RFC 822 Time Zone Codes Code
Time Zone
Numeric Offset
CDT
Central Daylight Time
-0500
CST
Central Standard Time
-0600
EDT
Eastern Daylight Time
-0400
EST
Eastern Standard Time
-0500
GMT
Greenwich Mean Time
None
MDT
Mountain Daylight Time
-0600
MST
Mountain Standard Time
-0700
PDT
Pacific Daylight Time
-0700
PST
Pacific Standard Time
-0800
UT
Universal Time
None
The disadvantage of putting a specific time zone in a template is that it only works for your own weblog and will be incorrect if you switch time zones later. A more robust way to create RFC 822–compliant timestamps is to use the MTBlogTimezone tag with a no_colon attribute that has the value 1. The template in Listing 18-2 makes use of this new tag. An RSS 2.0 newsfeed contains one or more item elements that contain headlines, weblog entries, or some other kind of information, usually in reverse chronological order. The RSS 2.0 template uses 15 item elements to present the 15 most recent weblog entries. This tag contains six elements: ✦ title: The entry’s title ✦ link: The link to the entry’s Web page ✦ description: The body of the entry ✦ guid: A unique string that’s associated only with the entry ✦ pubDate: The date and time the entry was created ✦ category: A category to which the entry belongs Most of the tags employ the encode_xml attribute to ensure that XML data produced by the tag is formatted correctly. The title and category tags strip out HTML and the entry body includes encoded HTML.
330 Movable Type 3 Bible, Desktop Edition The pubDate element contains an RFC 822–complaint timestamp just like the one used in the channel’s lastBuildDate element. The link and guid elements contain the same thing — the URL of the entry’s Web page — used in two different ways. The link element provides a hyperlink that can be visited to read more about the entry, driving traffic from the RSS 2.0 newsfeed to your weblog. The guid element serves as a unique identifier for the entry, which newsreaders and other RSS 2.0 software can use to avoid presenting the same entry twice. The last element, category, appears once for each of the entry’s categories. The RSS 2.0 format includes more than a dozen other tags that can be placed in a channel or item element. It also can be extended with additional tags through a namespaces feature that is covered in the next section. The simplicity and popularity of RSS 2.0 make it a good starting place for syndication efforts, but it often makes sense to support more than one of the formats. As you’ll learn by reading the RSS 2.0 specification, some of its elements are defined more vaguely than the corresponding elements of an RSS 1.0 or Atom feed. For example, there’s no guidance regarding whether an item’s title element can acceptably contain HTML, leaving Web publishers and software developers to decide whether to allow or disallow it.
Creating an RSS 1.0 Newsfeed Although you might have read elsewhere about “the RSS format,” there’s no such thing as a single RSS format. Much to the chagrin of anyone who deals with the subject, two rival formats call themselves RSS: RSS 2.0, the format that claims the initials stand for “Really Simple Syndication,” and RSS 1.0, a more complex format that calls it “RDF Site Summary.” Both formats are in wide use today. The name of RSS 1.0 comes from Resource Description Framework (RDF), a specification for describing information about the information published on the Internet, a definition that tends to confuse as many people as it enlightens. To put it in more concrete terms, one popular application of RDF is the Dublin Core Metadata Initiative, a set of tags that identify authorship information such as the creator, language, copyright, and publisher of a document such as a Web page. RDF strives to make Internet content more understandable to computers so that search engines and other software can handle it more intelligently. Movable Type supports trackback through the use of RDF, embedding data in Web pages to let software know how to send and receive trackback pings related to each entry. The RSS 1.0 format was developed by the RSS-DEV Working Group, around a dozen programmers and publishers who used the rss-dev public mailing list
Chapter 18 ✦ Publishing RSS Syndication Files
331
on Yahoo! Groups to collaborate. The specification for the format can be found on http://web.resource.org/rss/1.0. Listing 18-3 contains an RSS 1.0 template suitable for use as a Movable Type index file.
Listing 18-3: RSS 1.0 Index Template (index.rdf) en-us
332 Movable Type 3 Bible, Desktop Edition An RSS 1.0 file is XML 1.0 data that begins with this processing instruction:
An rdf:RDF tag encloses the contents of the newsfeed: one channel element and one or more item elements. These elements serve the same purpose in both flavors of RSS, as do the channel tags title, link, and description; and the item tags title, link, and description. Everything else in the template makes use of RDF and a feature of XML called namespaces. Namespaces enable XML data to include elements drawn from several different specifications. The RSS 1.0 newsfeed in Listing 18-3 employs five namespaces: RDF, Dublin Core, Creative Commons, MetaVocab, and RSS 1.0 itself. They are declared as attributes of rdf:RDF, the root element of the newsfeed:
Each xmlns attribute declares a namespace using a unique identifier, which in most cases is the URL of a Web site describing the elements available in that namespace. The last xmlns attribute refers to the RSS 1.0 specification. The other five include a suffix after the attribute name: admin for MetaVocab, cc for Creative Commons, dc for Dublin Core, and rdf for RDF. These identifiers are used in element names to indicate the namespace from which the element was drawn. An element or element attribute that uses an external namespace has a twopart name: a namespace identifier followed by a colon (:) and the element name. For example, the rdf:RDF element and rdf:about attribute come from the RDF namespace. The channel element of an RSS 1.0 newsfeed includes an rdf:about attribute that contains the URL of your weblog:
An rdf:about attribute explains what an element describes — here, it shows that the channel describes a particular Web site.
Chapter 18 ✦ Publishing RSS Syndication Files
333
In the RSS 1.0 template in Listing 18-3, two channel elements come from the Dublin Core: ✦ dc:date: The date and time the site was last updated ✦ dc:language: A short code for the language used in the newsfeed The dc:date timestamp can take several forms, one of which matches these examples: 2004-04-18T14:56:04-05:00 2004-04-12T18:47:26-08:00
These timestamps contain a date; the letter T; the time in hours, minutes, and seconds; and a time zone offset value. The offset values differ slightly from the ones appearing in an RSS 2.0 newsfeed: They contain a semicolon dividing hours and minutes. The following line of the RSS 1.0 template defines this element:
The MTEntryDate tag, structured using the strftime value “%Y-%m%dT%H:%M:%S”, produces everything needed in the timestamp up to the time zone offset. That last part can be provided by the MTBlogTimeZone tag (no plug-in is needed). Do not put a blank space between these two tags — the time zone immediately follows the date and time. One channel element, admin:generatorAgent, comes from the MetaVocab namespace. The element’s rdf:resource attribute identifies the software that created the newsfeed. The cc:license element tells publishers whether they have the right to republish the contents of your newsfeed or create derivative works based on it. If you have associated a Creative Commons license with your weblog, as described in Chapter 4, “Configuring a Weblog,” the MTBlogCCLicenseURL tag contains a URL that indicates the particulars of your chosen license. This URL can be placed in the rdf:resource attribute of the cc:license element:
The MTBlogIfCCLicense container causes the Creative Common license element to appear in the newsfeed only when a license has been chosen. Weblogs that do not offer licensing will omit the cc:license tag when index templates are rebuilt.
334 Movable Type 3 Bible, Desktop Edition The last channel element, items, holds an rdf:Seq element that establishes the sequence in which newsfeed items should be presented. An rdf:li element must be present, using the rdf:resource attribute to identify the item. (To help you remember these names, Seq is short for “sequence” and li is short for “list.”) Here’s how the RSS 1.0 template sets the order of items:
The MTEntries container holds the 15 most recent weblog entries, going backward from the most current. The last element to appear in the RSS 1.0 template is item, which appears once for each weblog entry to include in the feed. Fifteen entries are presented in the example newsfeed template. Each item element must have an rdf:about attribute that matches the rdf:resource attribute of an rdf:li element. This association establishes the proper order of items; if an rdf:about value cannot be found in any rdf:li tag, the item might be ignored by software that reads RSS 1.0 data. An item has three elements — title, link, and description — that match the same elements in RSS 2.0. Three other elements come from Dublin Core: ✦ dc:creator: The author of the weblog entry ✦ dc:date: The date and time the entry was created ✦ dc:subject: A classification for the entry, which can be a category, a topic, or keywords The dc:date element uses the same MTEntryDate and MTBlogTimeZone tags as the channel’s timestamp, dc:creator takes the entry author’s username, and dc:subject uses the entry’s primary category. Although namespaces have been introduced in relation to RSS 1.0, they work with both RSS formats. Declare a namespace in the root-level rss element the same way it is declared in RSS 1.0.
Chapter 18 ✦ Publishing RSS Syndication Files
335
Summary Because most of the files produced by Movable Type templates are HTML or XHTML pages, it’s easy to get the wrong idea about the software. Movable Type doesn’t limit you to Web pages. The software will publish weblog content in any text-based format you desire, including plain text, HTML, XHTML, CSS, and the growing number of XML site syndication formats. By using index templates, you can create XML versions of your weblog entries in Atom, RSS 1.0, and RSS 2.0 formats, three popular specifications for sharing content in a form that’s ideally suited to be read by software. Files created in these formats are called newsfeeds and can be read by a newsreader, an Internet client program that methodically checks a user’s favorite newsfeeds as often as once per hour. New content discovered in these feeds is presented for easy reading, eliminating the drudgery associated with repeatedly checking browser bookmarks in the often fruitless hunt for something new. Syndicated newsfeeds also can be published on other Web sites, a promotional vehicle that you can adopt to expand your audience and drive traffic to your weblog. The growing popularity of XML-structured Web publishing formats demonstrates that we’ve managed to learn something after creating sites for more than a decade (or more than a century, for readers still running on Internet time). XML syndication formats take Internet publishing to a new level, organizing content so that it can be adapted easily to a wide range of uses. Although some graphically inspired Web designers might blanch at the prospect of their work being ignored by the audience of RSS and Atom users, many publishers are coming around to the notion that these formats bring more users of all kinds to your Web site, including visitors who arrive by browser.
Supporting the Atom Syndication Format and API
19 C H A P T E R
✦
✦
✦
✦
In This Chapter Syndicating Web content with XML Creating an Atom feed Sharing weblog entries in Atom
U
nder one definition of the term, a weblog is merely a regularly published Web site organized chronologically so that the most timely material appears first.
Creating an Atom index template
There’s nothing particularly novel about that, aside from the name, which was coined by the Internet writer Jorn Barger. Chronological lists are as old as NCSA Mosaic What’s New, a popular directory of new sites published first in 1993 (more than 77 years ago in Internet time).
Storing information in feed elements
Working with constructs
Publishing weblog entries in the feed Using the Atom API
In another respect, weblogs deserve a loftier definition: the spark for a dramatic reinvention of how Web content is created and shared with an audience. A large network of tightly-linked sites updated at a frenzied pace, weblogs bring the Web closer to an original goal of its inventor — to serve as a medium for two-way communication with no distinction between author and audience. Anyone can create content for a global audience on the Web. Part of this reinvention has been the growth of RSS syndication formats and weblog APIs, new methods of sharing information with XML that were documented earlier in this book.
Connecting Web content with link elements Calling Atom API commands Sending and receiving API requests
✦
✦
✦
✦
338 Movable Type 3 Bible, Desktop Edition This chapter covers an ambitious effort to take Web site syndication and publishing further by developing a common protocol for both: the Atom syndication format and application programming interface.
Creating an Atom Newsfeed As this book is being written, Six Apart and other developers of weblog publishing software are working on the Atom syndication format, a new XML format that addresses perceived limitations in the two RSS formats described in Chapter 18, “Publishing RSS Syndication Files.” Atom comprises a syndication format for delivering site content to an audience and a publishing interface for authoring new content. Atom’s syndication format has been released as a “pre-draft” version from a development Web site: http://atomenabled.org/developers/ syndication.
Gotcha
You might wonder why a “pre-draft” of Atom has been implemented in Movable Type, because it sounds like a specification that will change greatly upon the full release of the format. The term “pre-draft” refers to a step in the standardization process for Internet protocols — the authors of the format do not believe that the Atom format will change dramatically in future drafts.
Listing 19-1 contains a sample Atom index template for Movable Type that produces an Atom version 0.3 feed.
Listing 19-1: A Sample Atom Index Template (atom.xml) tag:orlandovacationer.com,2004-05-17:weblog Movable Type
Chapter 19 ✦ Supporting the Atom Syndication Format and API
339
tag:orlandovacationer.com,2004-05-17:weblog.
For the most part, an Atom newsfeed contains the same information as an RSS 1.0 or 2.0 file, with different element names. The major difference between Atom and the two RSS formats is that Atom is more rigid about the kinds of information that can be contained in an element. In an Atom file, a root-level feed element holds a bunch of elements that describe the newsfeed, such as title (weblog title), tagline (weblog description), and modified (date and time of publication). Each entry in the feed, which can be a weblog entry or some other kind of information delivered in sequence, has an entry container element with its own subelements to define the entry, including created (date and time of first publication), and title (entry title). Atom feeds can make use of namespaces but do not employ RDF. The strongest difference between the new format and its predecessors lies in its support for multiple content types for each entry. If you want to syndicate your weblog entries as text, HTML, and another format, each can have its own content element within an entry container.
Working with Atom Feed Elements Although the Atom syndication format works well with weblog entries, news headlines, and similar Web sites, it was developed for representing any list of items that should be syndicated from publisher to audience. An Atom newsfeed consists of XML data, which can be established with the first line of the index template in Listing 19-1:
340 Movable Type 3 Bible, Desktop Edition Although an Atom feed does not have to employ XML 1.0, that’s the only version that you can use to produce the application/x.atom+xml MIME type that Web browsers and other clients look for when handling Atom files. The MTPublishCharset template tag identifies the character set that Movable Type has been configured to use. An Atom feed can contain comments and a document type declaration that defines the validity of the file’s XML markup. An Atom feed has a single feed element that holds the rest of its data. This element must have a version attribute identifying the Atom specification used to create the feed, which at present is “0.3”. Another required attribute, xml:lang, indicates the language used in the feed (en is the two-letter code for English). The xmlns attribute describes the default XML namespace to which elements of the feed belong. Atom elements can be one of four types of information, which are described as constructs in the format specification: ✦ A content construct that holds site content as one or more child elements ✦ A date construct that holds a timestamp value as a child element ✦ A link construct that represents a Web URL and has no child elements ✦ A person construct for the author and contributors involved in producing the feed or its entries These constructs are not elements that can be placed in an Atom template under those names. Instead, they’re just a handy way to group elements that share the same attributes and serve similar purposes. For instance, all date-and-time elements in Atom are date constructs. When you learn how to work with this construct’s attributes, you’ll be able to work with any timestamp in Atom. The next four sections describe the four constructs. When specific Atom elements are described later in this chapter, the construct group to which they belong is identified.
Using Content Constructs Listing 19-2 contains an example of a content construct, the aptly named content element.
Chapter 19 ✦ Supporting the Atom Syndication Format and API
341
Listing 19-2: A Content Construct Disney World is offering a “Play 4 Days” promotion for Florida residents, as described on WDW Central: Four-day park-hopping tickets for $109 per person. The tickets cover the first half of the year (through July 4) and are blocked from use April 3-15.]]>
A content construct holds one or more child elements that taken as a whole represent the element’s data. Most of these elements contain only a single element: text defined within the element’s opening and closing tags, as shown in Listing 19-2. A content construct has two optional attributes, type and mode. The type attribute identifies the MIME type that the element holds, which is assumed to be text/plain when the attribute is not present. Common values for this attribute are text/html for HTML formatted text and application/xhtml+xml for XHTML. When present, the mode attribute takes one of three values: ✦ base64 when the element holds text encoded in base-64 format ✦ escaped when the element text has been stored using escape codes or a CDATA block ✦ xml when the element holds well-formed XML A content construct with no mode attribute is assumed to be XML. Using escape codes in XML data enables text to contain characters that have meaning in XML: , and &. They are replaced with the entity codes < for , and & for &. A CDATA block begins with the text . Everything within these markers is character data, rather than valid XML. This tag is a feature of XML itself, not specific to the Atom format, and the primary purpose is to enable the same three characters — , and & — to appear as text in XML data. In the content element in Listing 19-2, the text “WDW Central” could be escaped to “WDW Central”.
342 Movable Type 3 Bible, Desktop Edition The default templates in Movable Type use escape codes instead of CDATA blocks to place HTML markup inside an Atom or RSS element. The tag attribute encode_xml=”1” converts the three characters to their escape equivalents, as shown in this example:
The use of escaped text in syndication formats, whether defined with entity codes or a CDATA block, has become controversial among XML experts because XML parsing software can’t interpret the character data in a meaningful way. All it can do is pass the data from the source — in this case, an Atom feed — to a client such as a syndicated feed reader. To avoid this lack of clarity, the most precise way to define data in a content construct is to use mode=”xml” and ensure that the element holds only proper XML such as XHTML. Because this places more of a burden on weblog authors — writing well-formed XHTML by hand takes diligence — few Web publishers use non-escaped data in their syndication feeds.
Using Date Constructs A date construct contains a single child element, a timestamp value that expresses a date and time in the World Wide Web Consortium’s date-time format. Here’s an example defined in Atom’s modified tag: 2004-05-24T15:07:42-05:00
This timestamp represents 5/24/2004 at 3:07:42 PM in the time zone five hours behind UTC (Coordinated Universal Time). A date-time represented in UTC can use a Z in place of the numeric time zone offset: 2004-05-24T20:07:42Z
This represents the same time as the preceding example, because 8:07:42 PM in the UTC time zone is five hours ahead of 3:07:42 PM. A date-time also can omit the time or the day of month, as in the following two examples: 2004-05 2004
You can create a timestamp in this format by using one of Movable Type’s date template tags with format and utc attributes with the following values:
Chapter 19 ✦ Supporting the Atom Syndication Format and API
343
The full specification for the date-time format is described on the consortium’s Web site at http://www.w3.org/TR/NOTE-datetime.
Using Link Constructs A link construct represents a relationship between an element in an Atom feed and some other resource on the Internet. One example of such a construct is the link element contained within an Atom file’s top-level feed element, which represents the URL of the Web site providing the feed. Link constructs have no child elements and must include the following three attributes:
✦ href: The address of the linked resource, which must be specified as a Uniform Resource Identifier (URI) ✦ type: The MIME type of the linked resource ✦ rel: A short descriptor that explains the relationship between the feed element and the linked resource A link construct also can have an optional title attribute that provides a short description of the resource. Here’s an example:
This portion of an Atom feed has a link construct, link, providing the URL of the feed’s home page: http://example.com/blog. Presumably, this means that the same items in the feed can be found on a Web page at that address and loaded with a browser. Links provide alternative representations of a parent element or additional Web content associated with the feed in some manner. There can be more than one link construct within the same parent, as long as each has a different type value. A link construct with a rel value of alternate is the main alternative to the feed. On a weblog, the Atom feed and its home page are different representations of the same information, so a construct with link=”rel” is the weblog’s home page.
344 Movable Type 3 Bible, Desktop Edition The following example, taken from Six Apart founder Ben Trott’s Atom feed, has two link elements:
The first link construct indicates that the feed provides an XML representation of a Web site at http://btrott.typepad.com/typepad/ (his weblog on TypePad). The second provides a URL that can be used to publish weblog entries using the Atom API, a topic that is covered later in this chapter. A link element with the rel attribute of “service.post” always serves this purpose. Any link construct can have an xml:base attribute that provides the base URI of the resource indicated by the href attribute, transforming a relative address into a full address. For example, consider the following link:
The xml:base and href attributes are combined to form the full URI http://cadenhead.org/workbench. In Atom, the xml:base attribute is optional and is used only on specified members of the link construct group, as described subsequently. On other elements, it is ignored even when present.
Using Person Constructs The last Atom construct that represents a group of similar elements is the person construct, devoted to elements that identify a specific author associated in some manner with part (or all) of the feed. This author can be an individual person or some other entity in the case of group authorship. A person construct can have three child elements, each of which can appear only once within the same parent: ✦ name: The person’s name ✦ email: The person’s e-mail address ✦ url: A URI associated with the person, such as a home page URL The name element must be present; the other two elements are optional. When xml:base attributes are present in the url element, its parent, or higher up the hierarchy, it must be applied to transform the URL.
Chapter 19 ✦ Supporting the Atom Syndication Format and API
345
Authoring an Atom Feed Atom data consists of a single feed element that contains child elements defining the feed and a series of items:
Movable Type weblogs include an Atom index template that holds an XML representation of the 15 most recent weblog entries in Atom 0.3 format. The xmlns attribute indicates the default namespace for the feed, which applies to any element whose name is not preceded with a namespace identifier. Additional namespaces and their elements can appear in the feed as long as they are declared using additional namespace declarations, as in this example:
The feed element must include a version attribute specifying the version of the Atom specification employed by the feed. To create a feed compliant with the rules described in this chapter, use version=”0.3”. An optional xml:lang attribute can be used to identify the feed’s language, using an identifier such as the two-letter codes defined by the ISO 639 standard (en for English, ru for Russian, eo for Esperanto, and so on). The preceding example defines a feed that uses three namespaces: ✦ The xml namespace (for elements such as xml:lang and xml:base) ✦ The default namespace, identified by the xmlns attribute ✦ A namespace with the identifier dc, as established by the xmlns:dc attribute The third namespace is Dublin Core 1.1, a set of elements that provide basic information about a resource on the Internet, such as its creator, publisher, and title. In the feed, any element belonging to a namespace outside of the default will have a namespace identifier followed by a colon and the element name. Here’s one for the Dublin Core’s Language element: en
This element and the other parts of Dublin Core 1.1, defined on the Web at http://dublincore.org/documents/dces, can appear in any XML data with a top-level element that includes the namespace declaration xmlns:dc= ”http://purl.org/dc/elements/1.1/”. Table 19-1 contains child elements that might be present within a feed element. Some are optional, whereas others must be defined.
346 Movable Type 3 Bible, Desktop Edition Table 19-1 Atom Feed Elements Name
Description
Construct Type Quantity
Required
author
The author of the feed
person
One
Varies
contributor
A contributor to the feed
person
One or more
No
copyright
A copyright statement for the feed
content
One
No
generator
The name of the software generating the feed
none
One
No
id
A URI that functions as a globally unique identifier for the feed and never changes
none
One
No
info
A short description of the Atom format
content
One
No
link
A URI associated with the feed
link
One or more
Varies
modified
The date and time the feed was last edited
date
One
Yes
tagline
A short description of the feed
content
One
No
title
A short descriptive title for the feed
content
One
Yes
The construct type for each of the elements in Table 19-1 indicates the kind of content it must contain. An attribute that has no construct type is simply a string of characters. Many of the elements are optional and can be omitted from a feed, whereas a few are required. A feed element also contains one or more entry elements that define individual items from the feed. An author element must be present unless you define one inside each entry element. There must be one link element with a rel attribute of alternate (and no more than one). As with any link construct, multiple link elements can be present as long as they have different rel values.
Chapter 19 ✦ Supporting the Atom Syndication Format and API
347
The generator element, which identifies the software that produced the feed, can have two optional attributes: url, a URI that has significance to that software, and version, the software’s version number. Movable Type uses this tag in the following manner: Movable Type
The modified element follows the rules of timestamp formatting required of any date construct. The Atom specification recommends that the time be expressed as UTC, using a Z character in place of a time zone offset. The feed’s title, which is set by the title element, should be the same as the Web resource associated with the Atom feed.
Defining Globally Unique Identifiers An Atom feed’s id element holds a globally unique, never-changing identifier for a feed, which can be used by syndication readers when internally tracking the feeds that they monitor. The element must be a URI. A useful application of this identifier is to make syndication clients smarter about syndication feeds that change URLs: If a client finds a feed at a new URL with an identifier that it recognizes, the software can stop looking for the feed at the old URL. In Movable Type templates, an Atom feed’s identifier uses a new naming scheme called the Tag URI that can be adopted for any purpose by anyone who owns or controls an Internet domain name or e-mail address. This scheme, explained in detail on the Web at http://www.taguri.org, serves as a simple method for devising unique identifiers. To create one, follow the text “tag:” with the following: ✦ The domain or e-mail address you control ✦ A comma ✦ A date that you controlled the address, in YYYY-MM-DD format (such as 2004-05-24) ✦ A semicolon ✦ A short name you haven’t already used in an identifier on that date This scheme can be used on anything that benefits from unique identification. In an article about the Tag URI system, I declared that my globally unique identifier was tag:cadenhead.org,2004-05-17:Rogers. I owned the domain cadenhead.org on May 17, 2004, so no one else would be giving out identifiers based on it with the same date. Although there might be someone else named “Rogers Cadenhead” in the world, no one else will have the Tag URI tag:cadenhead.org,2004-05-17:Rogers.
348 Movable Type 3 Bible, Desktop Edition If you use Movable Type’s default Atom template, you’ll have an id element in the following form: tag:, :/
This produces identifiers of this form: tag:orlandovacationer.com,2004:///2
The implementation of this feature in Movable Type’s Atom template is incorrect because all three elements of the identifier might change (and the date changes each year). A Tag URI must not change once it has been created. For this reason, the Atom template in Listing 19-1 defines its own Tag URI without using any Movable Type template tags: tag:orlandovacationer.com,2004-05-17:weblog
When adapting this for your own weblog, change the domain, date, and identifier based on the specifics of your own site. Make sure that the same identifier is not used on more than one weblog. There’s no requirement in Atom that an id element must use the Tag URI’s naming scheme. Any arbitrarily imposed system can work, as long as there’s a means to ensure that different publishers don’t use the same identifiers for their feeds or individual entries.
Linking Web Resources Together Atom feeds establish relationships with other kinds of Internet resources through the use of link constructs. One of these is a feed’s link element, which can be used to associate an entire feed with another resource. Link constructs define the relationship with three attributes that relate to the other resource: href (its URL), type (its media type), and rel (a short descriptor). The most common relationship occurs between an Atom feed and the Web site that presents the same information. All Movable Type weblogs begin with a home page and an Atom feed, both of which present the most recent entries from the weblog. This relationship is codified into Atom with the following line in a feed:
The link element in Atom mirrors the functionality of the link element in HTML and serves the same purpose. In the template code for a weblog’s Main Index template, you can find this element:
Chapter 19 ✦ Supporting the Atom Syndication Format and API
349
Both links signify the relationship from the perspective of the document. One tells Web browsers about an Atom feed and the other tells Atom readers about a Web site. An Atom feed can contain additional link elements that present a sequence of related feeds. A rel value of start identifies the first feed in the sequence, next offers the next, and prev offers a way to go backward. Putting this into practice, consider a site that has weblog entries numbered from 1 to 60 and Atom feeds that present 15 entries at a time. The main feed for the site could present the 15 most recent entries, which are numbered from 46 to 60. This feed could contain two link elements:
The next link provides a URL that will present 15 more entries from 45 down to 31. The start link URL begins at the first entry. Table 19-2 summarizes these relationships.
Table 19-2 Atom Link Relationships Rel
Type
Parent Element
alternate
application/x.atom+xml
Feed
The Web page represented by the feed
next
application/x.atom+xml
Feed
The feed containing the next entries in a sequence
prev
application/x.atom+xml
Feed
The feed containing the previous entries in a sequence
start
application/x.atom+xml
Feed
The feed containing the first entries in a sequence
Links To
350 Movable Type 3 Bible, Desktop Edition
Publishing Feed Items The Atom elements defined up to this point describe aspects of a feed. The feed element also can contain one or more entry elements, items from the list that the feed was intended to represent, such as the latest headlines from a news site or the most recent entries on a weblog. The order in which entry elements appear in an Atom feed is not significant. Although most syndication feeds are presented in reverse chronological order, you can’t count on this in Atom. There are timestamp elements for each entry that can be used for sorting purposes. Each entry element can contain one or more child elements, many of which have the same purpose as feed elements with the same name. They’re listed in Table 19-3.
Table 19-3 Atom Entry Elements Name
Description
Construct Type
Quantity
Required
author
The author of the entry
person
One
No
content
The content of the entry
content
One or more
No
contributor
A contributor to the entry
person
One or more
No
created
The date and time the entry was created
date
One
No
id
A URI that functions as a globally unique identifier for the entry
none
One
No
issued
The date and time the entry was published
date
One
Yes
link
A URI associated with the entry
link
One or more
Varies
modified
The date and time the entry was last edited
date
One
Yes
summary
An excerpt or summary of the entry
content
One
No
title
A short descriptive title for the entry
content
One
Yes
Chapter 19 ✦ Supporting the Atom Syndication Format and API
351
An entry has three timestamp elements that represent stages in its publication: the first time it was stored (issued), the first publication (created), and the most recent revision (modified). All three should be expressed as UTC time, with no time zone offset (if possible). When the created element is not present, its value is assumed to be the same date and time as the issued element. Entries also have their own id element for a unique identifier. If you’re using a Tag URI for this purpose, you can base it on the feed’s identifier. In a Movable Type template, add a period and the entry’s ID number to the end, as in the following code: tag:orlandovacationer.com,2004-05-17:weblog.
On an entry with the ID number of 72 in the Movable Type database, this produces the following XML: tag:orlandovacationer.com,2004-05-17:weblog. 72
If an entry appears in more than one Atom feed, its id element should be the same in every feed. An entry can contain one or more content elements presenting the content of the entry. Because they are content constructs, type and mode attributes identify the kind of content that each element holds. Here’s a complete entry produced by the Atom template in Listing 19-1: Killer whale born at SeaWorld Orlando 2004-05-18T02:31:58Z 2004-02-11T14:39:51Z tag:orlandovacationer.com,2004-05-17:weblog.79 2004-02-11T14:39:51Z Kalina, an 18-year-old killer whale at SeaWorld Orlando, gave birth to her fourth calf Monday at the park's research and breeding facility,Shamu Stadium: Kalina gave birth to the 7-foot-long, 350-pound calf in Shamu Stadium's main pool following a seven-hour... rcade http://www.cadenhead.org/workbench/ [email protected] Kalina, an 18-year-old killer whale at SeaWorld Orlando, gave birth to her fourth calf Monday at the park’s research and breeding facility, Shamu Stadium.
Kalina, an 18-year-old killer whale at SeaWorld Orlando, gave birth to her fourth calf Monday at the park’s research and breeding facility, ShamuStadium.
” . $symbol . “: “ . $price . “ (“ . $change . “) “ . “at “ . $s_date . “ “ . $s_time . “
”; } } 1;Red Hat Check
Red Hat Check
RHAT: 16.15 (+1.25)
at 7/21/2004 4:00pm
| Symbol | Price | Date | Time | Change | Open | High | Low | Volume |
Three values are passed to the filter’s method: the output text to filter, the attribute value, and the context. The method returns the output after modification. Simple to develop, global filters can provide some much-desired functionality for Movable Type. Listing 20-5 contains remove_excessive_links, a filter that counts the number of hyperlinks in tag output, stripping the links if they exceed a specified maximum. The tag’s purpose: preventing link spammers from taking advantage of your weblog’s comments feature.
Listing 20-5: Filtering Excessive Links # declare a class name package MT::Plugin::RemoveExcessiveLinks; # make classes available to this script use MT::Template::Context; use MT::Blog; use MT::Sanitize; # register a global filter MT::Template::Context->add_global_filter( remove_excessive_links => \&remove); # define the remove_excessive_links filter method sub remove { my $text = shift; my $att_value = shift; my $ctx = shift; my $blog = $ctx->stash(‘blog’); my $good_html = $blog->sanitize_spec || “b,br,p,strong,em,ul,li,blockquote”; $good_html =~ s/a href,//i; my $count = 0; $count++ while $text =~ /a href/gi; if ($count >= $att_value) { $text = MT::Sanitize->sanitize($text, $good_html); } return $text; } 1;
Chapter 20 ✦ Developing New Plug-Ins with Perl
371
The remove_excessive_links attribute can be used with any simple template tag, but it makes the most sense to associate it with MTCommentBody, the comment tag that presents the text of a visitor-submitted comment. The attribute value should be the number of links to trigger the filter — to prevent a user from posting more than four links in a comment, for instance, use this tag:
When the script encounters tag text that reaches or exceeds the maximum count, it uses Movable Type’s HTML sanitize feature to strip out all hyperlinks from the text. In order to use sanitize, the script first determines whether the weblog has its own sanitize_spec configuration setting, which holds a comma-separated list of HTML tags and attributes that are permitted in comments: my $blog = $ctx->stash(‘blog’); my $good_html = $blog->sanitize_spec || “b,br,p,strong,em,ul,li,blockquote”; $good_html =~ s/a href,//i;
The default list of acceptable tags in Movable Type is a href, b, br, p, strong, em, ul, li, and blockquote. The HTML sanitizer removes all tags and attributes that aren’t in that list. The excessive links filter adopts the weblog’s custom sanitize_spec list or the default, removing a href if it appears in the list so that hyperlinks will be removed. A call to the sanitize() method of the MT::Sanitize object removes all links from the text: MT::Sanitize->sanitize($text, $good_html);
The arguments to the method are the tag output and the list of acceptable tags. This filter deters slimy Internet marketers who post fake comments in Movable Type weblogs to sites they are touting, an abuse that has become commonplace. Often, they’ll use software to post text that includes links to a dozen products or sites, hoping that it will improve their ranking in Google and other search engines. By removing all links from comments that contain a suspicious number of hyperlinks, you can reduce their perceived benefit from this activity.
372 Movable Type 3 Bible, Desktop Edition
Creating a Conditional Tag Some Movable Type container tags display their contents when a condition has been met and ignore them otherwise. These conditional tags, as they are called, can be implemented as plug-ins with the add_conditional_tag() method of the MT::Template::Context class. The method takes the same form as the other tag addition methods: a tag name (minus the starting MT) followed by a subroutine reference, as in this example: MT::Template::Context->add_conditional_tag(IfMonday => \&monday_show);
The method that implements the tag works for the most part like any other container tag’s method. You can receive the script’s context and attributes and make use of the stash. The one area in which it strays is in the method’s return value. A conditional tag method should return a Boolean value: 1 if the condition has been met and 0 otherwise. When a conditional tag returns 1, its contents are processed further and can be displayed. When the tag returns 0, all of its contents are ignored. Listing 20-6 demonstrates the creation of two conditional tags, IfBusinessDay and IfNotBusinessDay, which check whether the current day falls within the normal work week (Monday through Friday).
Listing 20-6: Displaying Output on Business Days # declare a class name package MT::Plugin::BusinessDay; # make classes available to this script use MT::Template::Context; # register a global filter MT::Template::Context->add_conditional_tag( IfBusinessDay => \&check_day); MT::Template::Context->add_conditional_tag( IfNotBusinessDay => \&check_day); # define the tag method sub check_day { my $ctx = shift; my $args = shift; my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) = localtime(time); my $tag = $ctx->stash(‘tag’); my $not_flag = $tag =~ m/Not/; my $biz_day = 0;
Chapter 20 ✦ Developing New Plug-Ins with Perl
373
if (($wday == 0) || ($wday == 6)) { $biz_day = 1; } return ($not_flag) ? $biz_day : !$biz_day; } 1;
This script demonstrates a new technique for plug-in programming — sharing the same method for more than one tag. This can be done by checking the name of the current tag, which has been stored by Movable Type’s template builder object in the stash with a key of tag. The script looks at the tag and determines whether it contains the word not in the following two statements: my $tag = $ctx->stash(‘tag’); my $not_flag = $tag =~ m/Not/;
The call to the Perl function localtime(time) returns a nine-element list representing the current time. The seventh element of the list, the day of the week, numbers from 0 on Sunday to 6 on Saturday.
Summary Movable Type’s plug-in framework has inspired the development of more than 100 scripts by developers, as you can discover by visiting the MT Plug-in Directory Web site at http://mt-plugins.org. Plug-ins integrate seamlessly into Movable Type, delivering their functionality as new template tags and tag attributes. The framework achieves a division of work responsibilities between Web designers and programmers that promotes collaboration. A programmer can extend the capabilities of Movable Type by developing a Perl script that registers a new tag or tag attribute and implements the code necessary to handle the tag when the software turns templates into output files. Web designers receive these tags and tag attributes, working with them exactly as they would with the hundreds of template tags that are included as a builtin part of the software. As you’ll discover in Chapter 21, Movable Type 3.0 extends plug-ins into the software’s browser-based interface, making it possible to collect new kinds of information to be presented on your Web sites.
Hooking into Movable Type with Plug-Ins
21 C H A P T E R
✦
✦
✦
✦
In This Chapter
I
n July 2004, Six Apart awarded $20,000 in prizes to six developers who created plug-ins for Movable Type 3.0. Jay Allen, the creator of the MT-Blacklist plug-in, turned a well-crafted tool to fight comment and trackback abuse into a grand prize that inspires considerable geek envy: an Apple G5 system with dual 2GHz, a 23-inch Apple Cinema HD Display, and Adobe Creative Suite Premium with GoLive CS. Retail value: $7,000. You can find out about Jay’s work on MT-Blacklist and many other Movable Type enhancements by visiting his weblog at http://www.jayallen.org.
Second place went to Andrew Sutherland’s KoalaRainbow, a tool for turning the software into a graphical visualization lab, publishing information visually using highly configurable template tags. Andrew Sutherland describes the product on his Only the Wind weblog at http://www.onlythe wind.org/mt, offering graphical examples that do it much better justice.
Movable Type has attracted excellent coders such as Allen and Sutherland because of the software’s extensible object-oriented design. Although the software functions primarily as a weblog publishing tool, Movable Type has been designed as an open framework for gathering and publishing Web content of much wider scope.
Adding plug-ins with the browser interface Linking scripts to editing forms Writing a Web application Using the software’s Perl classes Receiving CGI parameters Working with Perl modules Reading author information in a script Working with weblog configuration settings Reading and writing weblog entries Creating your own plug-ins Enhancing Movable Type
✦
✦
✦
✦
376 Movable Type 3 Bible, Desktop Edition In addition to the plug-in tags covered in Chapter 20, you can create Perl classes that integrate with the software in many other ways. In this final chapter of the book, you’ll learn how to turn the software you’ve come to know so well over the past 20 chapters into a program that does so many new things that it’s practically unrecognizable.
Managing Plug-Ins with a Browser Movable Type 3.0 adds support for plug-in management to the software’s browser-based interface. Prior versions of the software did not provide any information, within the browser, about which plug-ins are installed on a server or how they can be configured. The MT::Plugin class represents the information required for the software to recognize plug-in scripts. A plug-in must register with Movable Type to indicate its presence. Although plug-ins will continue to work correctly without being manageable in this manner, registering a plug-in makes things easier for the script’s users. An MT::Plugin object carries the script’s name and description along with hyperlinks to its home page and a configuration page (when one is available). In a plug-in, you create the object and call its methods to set the following pieces of information: $plugin = new MT::Plugin(); $plugin->name(“Site Map”); $plugin->description(“Presents links to all pages of a weblog”); $plugin->doc_link(“http://example.com/sitemap/”); $plugin->config_link(“config_sitemap.pl”);
After the MT::Plugin object has been created and its values have been established, a method of the MT class can be used to inform Movable Type about the script: MT->add_plugin($plugin);
Registered plug-ins appear in the software’s Main Menu page in a new Configure Active Plugins section. Figure 21-1 shows how plug-ins are presented on this part of the software’s browser interface.
Chapter 21 ✦ Hooking into Movable Type with Plug-Ins
377
Figure 21-1: Managing plug-ins with a Web browser.
Adding Plug-In Action Links to the Interface Another new feature of Movable Type 3.0 enables Perl scripts to be called from editing pages in the software’s browser interface. These action links, as they have been dubbed, can appear at the bottom of editing forms for authors, categories, comments, and templates. You can view a script link added with this technique at the bottom of a comment editing page in Figure 21-2.
378 Movable Type 3 Bible, Desktop Edition
Figure 21-2: Calling scripts from an editing page in the browser.
The script called from an action link will be executed using a GET request over the Common Gateway Interface (CGI). In this respect, it’s more like the scripts that power Movable Type (such as mt.cgi and mt-check.cgi) than a plug-in that adds a tag, filters text, or serves a similar purpose. However, you must implement a plug-in to cause the action link to appear on the desired page. To make the link appear, the add_plugin_action() method of the MT class is called with three arguments: 1. The page on which to place the link, identified by a key 2. The script to call, which can be in the plugins directory or a subdirectory 3. The text of the link The key can be one of the following values for editing pages: author, category, comment, entry, or template. Action links also can be added to pages that list weblog elements for editing: list_commenters, list_comments, and list_entries.
Chapter 21 ✦ Hooking into Movable Type with Plug-Ins
379
Listing 21-1 contains CheckSamSpade.pl, a plug-in script that adds the Check IP with Sam Spade link to comment editing pages. When you store it in Movable Type’s plugins directory, the link appears immediately on all comment editing pages like the one shown earlier in Figure 21-2.
Listing 21-1: Adding a Plug-In Action # declare a class name package MT::Plugin::CheckSamSpade; # register classes use MT; # register plug-in action MT->add_plugin_action(‘comment’, ‘check_sam_spade.cgi’, ‘Check IP with Sam Spade’);
Plug-in action links are called with several parameters. The from parameter indicates the originating page, such as edit_comment for the comment editing form and edit_category for the category editor. The id parameter contains the ID number of the weblog element being edited (author, category, comment, entry, or template), which can be used to retrieve it from the Movable Type database. Listing 21-2 contains check-sam-spade.cgi, a Perl script that redirects visitors to a Sam Spade page reporting information about the IP address.
Listing 21-2: Redirecting Visitors to Another URL #!/usr/bin/perl -w # set the script’s version number use vars qw( $VERSION ); $VERSION = ‘1.0’; # add the MT directory to @INC for this script my($MT_DIR); BEGIN { if ($0 =~ m!(.*[/\\])!) { $MT_DIR = $1; } else { $MT_DIR = ‘./’; } Continued
380 Movable Type 3 Bible, Desktop Edition Listing 21-2 (continued) unshift @INC, $MT_DIR . ‘lib’; unshift @INC, $MT_DIR . ‘extlib’; } # make classes available use CGI; use MT; use MT::Comment; my $mt = MT->new(Config => $MT_DIR . ‘mt.cfg’, Directory => $MT_DIR) || die MT->errstr; # retrieve the CGI parameter id (the comment ID) my $query = new CGI; my $comment_id = $query->param(‘id’); # load Sam Spade page my $comment = MT::Comment->load($comment_id); my $url = “http://www.samspade.org/t/lookat?a=” . $comment->ip;
print “Location: $url\n\n”; exit;
Although CGI scripts that redirect URLs can be written in a large number of programming languages, the advantage to sticking to Perl for action-related scripts is the capability to make use of Movable Type’s classes. The check-sam-spade.cgi script employs the MT::Comment class to load the comment associated with an ID number passed to the script as a parameter. The BEGIN block in the script ensures that Movable Type’s CGI path can be found by the script. This wouldn’t be necessary if the program didn’t need any of the software’s classes.
Programming with Movable Type Classes With version 3.0 of the software, Movable Type has accumulated a sizeable library of Perl classes that can be employed in your own plug-in scripts, text filters, and CGI Web applications. Each of these classes contains its own documentation, which you can view by typing the perldoc command followed by a classname, like so: # perldoc MT::Comment
Chapter 21 ✦ Hooking into Movable Type with Plug-Ins
381
The documentation for the class is displayed in a text-based interface (see Figure 21-3).
Command Line Figure 21-3: Reading Movable Type’s Perl class documentation.
Perldoc pauses when the window fills up with a screen of text, displaying a “:” command prompt at the lower-left corner of the window, as identified in Figure 21-3. When the end of the documentation has been reached, an (END) prompt is shown. Use the following keys to browse documentation with the Perldoc tool: ✦ Press the spacebar or Page Down key to continue to the next screen. ✦ Press the Page Up key to move upwards. ✦ Press the q key to quit reading. The Movable Type library has 24 classes led by MT, a top-level class that rebuilds weblogs and transmits ping messages. MT::App serves as the base class for all Web applications that take advantage
of the Movable Type framework. These programs can be executed as CGI scripts or run under Apache::Registry and mod_perl. Applications should be created as subclasses; the MT::App class is not directly instantiated. One of the advantages of creating applications under MT::App is the capability to make use of Movable Type’s user authentication system. You don’t have to write code to log in users or recognize account cookies.
382 Movable Type 3 Bible, Desktop Edition All objects saved persistently to a database or file are subclasses of MT::Object, inheriting common methods to get and set their fields. Storage has been dealt with abstractly — an object does not have any way of knowing how it is being stored in permanent form. An object can be loaded by calling the load() method of its class with an ID number as the only argument. Some objects can be retrieved using other criteria.
Working with Weblog Authors The MT::Author class represents a user with weblog authoring privileges. The set_password(string) and is_valid_password(string) methods can be used to establish a password and check whether a prospective password will pass muster with the software, respectively. The fields in this class are listed in Table 21-1.
Table 21-1 Fields of the MT::Author Class Field
Type
Template Tag
Description
can_create_blog
Boolean
none
Whether the author can (1) or cannot (0) create a new weblog
can_view_log
Boolean
none
Whether the author can (1) or cannot (0) view the software’s activity log
created_by
integer
none
Author ID number of user who created this account
email
string
MTEntry AuthorEmail
hint
string
None
Author’s birthplace, which will be requested for password recovery purposes
id
integer
None
Author’s ID number
name
string
MTEntryAuthor
Author’s username
nickname
string
MTEntryAuthor Nickname
Author’s nickname
password
string
None
Author’s password
public_key
string
None
Reserved for future use
url
string
MTEntry AuthorURL
Author’s homepage URL
Chapter 21 ✦ Hooking into Movable Type with Plug-Ins
383
The actual privileges for an author are held in MT::Permission objects.
Handling Weblog Objects The MT::Blog class contains a weblog published on the server and all of its configuration settings. This class has a filemgr() method that returns a MT::FileMgr object representing the weblog’s file manager. Class fields appear in Table 21-2.
Table 21-2 Fields of the MT::Blog Class Field
Type
Template Tag
Description
allow_anon_ comments
Boolean
none
Whether visitors can submit comments anonymously (1) or cannot (0)
allow_comments_ default
string
allow_comment_html
Boolean
none
Whether visitors can use HTML in comments (1) or cannot (0)
allow_unreg_ comments
Boolean
none
Whether visitor comments must come from TypePad users (1) or others are allowed (0)
archive_path
string
none
Weblog’s local archive path directory
archive_type
string
none
Chosen archive types (Category, Daily, Individual, Monthly, Weekly) as a comma-separated list
archive_type_ preferred
string
none
Preferred archive type (one of the five above)
archive_url
string
MTBlog ArchiveURL
Archive home page
auto_link_urls
Boolean
none
Whether links in visitor comments should be autolinked (1) or not (0)
convert_paras
string
none
Text filters to apply to entries (as a comma-separated list)
convert_paras_ comments
string
none
Text filters to apply to visitor comments (as above) Continued
384 Movable Type 3 Bible, Desktop Edition Table 21-2 (continued) Field
Type
Template Tag
Description
days_on_index
integer
none
Number of days’ entries to display on home page
Description
string
MTBlog Description
The weblog’s description
email_new_comments
Boolean
none
Whether authors receive new comment notifications in e-mail (1) or not (0)
file_extension
string
none
Filename extension to use on archive pages
Id
integer
MTBlogID
ID number
Language
string
none
Language for date and time display
mt_update_key
string
none
The registration key that qualifies a weblog for the “Recently Updated” list on the Movable Type Web site
Name
string
MTBlogName
Name
server_offset
integer
MTBlog Timezone
Weblog’s chosen time zone, represented as the offset in hours from UTC time
site_path
string
MTBlog SitePath
Weblog’s local site path directory
site_url
string
MTBlogURL
Home page
sort_order_ comments
string
None
The default sort order for visitor comments (“ascend” or “descend”)
sort_order_posts
string
None
The default sort order for entries (“ascend” or “descend”)
status_default
string
None
welcome_message
string
None
Welcome message to display on Movable Type’s editing menu
words_in_excerpt
integer
None
Number of words to include in entry excerpts
Manipulating Weblog Entries The MT::Entry class, perhaps the most useful class in MT’s hierarchy of objects, carries an individual weblog entry’s data and methods that provide
Chapter 21 ✦ Hooking into Movable Type with Plug-Ins
385
access to other useful objects, such as comments (MT::Comment) and categories (MT::Category). An entry object’s previous() and next() method return an adjacent MT::Entry object. The author() method produces the MT::Author object of the user who penned the entry, whereas the category() method does the same for its category. The categories() and comments() methods return arrays of the objects. The comment_count() and ping_count() methods tally the number of visitor comments and trackback pings that the entry has attracted. Table 21-3 describes the fields of an MT::Entry object.
Table 21-3 Fields of the MT::Entry Class Field
Type
Template Tag
Description
allow_comments
Boolean
MTEntryFlag
Whether the entry allows (1) or disallows (0) comments
author_id
integer
None
The ID number of the entry author
blog_id
integer
MTBlogID
The ID number of the weblog in which this entry appears
convert_breaks
Boolean
MTEntryFlag
Whether line and paragraph breaks should be added (1) or not (0)
created_on
timestamp
MTEntryDate
The date and time the entry was first saved
Excerpt
string
MTEntryExcerpt
A short excerpt or summary
Id
integer
MTEntryID
The entry’s ID number
modified_on
timestamp
MTEntry ModifiedDate
The date and time the entry was last edited
Status
integer
MTEntryStatus
The publication status, which is either Publish (2) or Draft (1)
Text
string
MTEntryBody
The entry text
text_more
string
MTEntryMore
Additional entry text
Title
string
MTEntryTitle
The entry title
386 Movable Type 3 Bible, Desktop Edition
Summary Movable Type has been developed using object-oriented programming, a style of software design touted as the best way to deliver reliable, reusable, and extensible code. Telling a programmer to employ objects and classes often is received as warmly as an admonition to “eat your vegetables.” Now that you’ve had the opportunity to work with the objects that work in concert to operate Movable Type, you can attest to Six Apart’s strong commitment to the methodology. Movable Type makes all of its functionality available in the form of welldesigned, well-documented Perl classes. You can create your own objects that work in cooperation with the software, adding new functionality in the form of tags and text filters, running in complement as Web applications, and extending the content-management system in countless new ways. Because Six Apart did such a good job on the underlying framework that drives the company’s flagship product, Movable Type becomes less recognizable with each new release. A technology magazine review of Movable Type 3.0 would probably summarize it as follows: a template-driven, extensible weblog publishing tool that supports comments, trackback, multiple authors and sites, image uploads, HTML, XHTML, XML, RSS, Atom, XML-RPC, Berkeley DB, MySQL, PostgreSQL, and SQLite. As impressive as that sounds, the buzzword-laden definition leaves off the software’s biggest selling point: a killer publishing framework that can be extended to deliver any kind of Web content, separating the work of Web designers and programmers in a manner that gives both groups the opportunity to do their best work in strong cooperation. Now that you’ve explored the software over the course of several hundred pages, I look forward to discovering where you take your installation of the program using plug-ins, filters, action links, and other software hooks. The opportunities that Movable Type offers as an information-gathering and publishing tool are limitless. So stop reading, start coding, and get moving!
Using Movable Type 3.1
F
ollowing the release of Movable Type 3.0, Six Apart announced a shift toward a more frequent software release schedule. New releases would appear as often as quarterly, according to an announcement on the company’s Web site. The first release under this new plan, version 3.1, extends the software’s publishing and weblog categorization capabilities. Version 3.1 also includes additional callbacks for plug-in developers and other enhancement software written to extend Movable Type’s functionality.
Publishing Templates Dynamically The most ambitious feature introduced with Movable Type 3.1 is the capability to designate parts of your weblog to publish dynamically each time they are requested. Up to this point, all files created by the software were generated from templates statically, changing only when the files were rebuilt. The new dynamic publishing feature, which is implemented with the PHP programming language, eliminates the need to rebuild those parts of the site in response to a template change or new data such as a weblog entry or visitor comment. You can choose a weblog’s publishing policy, dynamic or static, on a per-template basis or for the entire site.
•
A P P E N D I X
✦
✦
✦
✦
388 Movable Type 3 Bible, Desktop Edition Six Apart calls the new feature a “best of both worlds” approach. Frequently requested pages such as a site’s index page can be generated statically, causing them to load more quickly and consume fewer resources on your Web server. Less popular pages, such as your archives, can be generated dynamically, removing the time-consuming need to rebuild dozens or even hundreds of pages. Before you can use the feature, you must open the weblog’s main directory and create a subdirectory named templates_c that will hold template cache files. This directory should have the read, write, and delete permissions for all users (chmod 777 on a Linux system). Next, if you are publishing your weblog with the Apache Web server, you must create a text file named .htaccess in its root directory like the one in Listing A-1.
Listing A-1: Viewing Dynamic Files with .htaccess # Disable fancy indexes, so mtview.php gets a chance... Options -Indexes # The mod_rewrite solution is the preferred way to invoke # dynamic pages, because of its flexibility. # Add mtview.php to the list of DirectoryIndex options, listing it last, # so it is invoked only if the common choices aren’t present... DirectoryIndex index.php index.html index.htm default.htm default.html default.asp /mtview.php RewriteEngine on # don’t serve mtview.php if the request is for a real directory # (allows the DirectoryIndex lookup to function) RewriteCond %{REQUEST_FILENAME} !-d # don’t serve mtview.php if the request is for a real file # (allows the actual file to be served) RewriteCond %{REQUEST_FILENAME} !-f # anything else is handed to mtview.php for resolution RewriteRule ^(.*)$ /mtview.php [L,QSA] # if mod_rewrite is unavailable, we forward any missing page # or unresolved directory index requests to mtview # if mtview.php can resolve the request, it returns a 200 # result code which prevents any 4xx error code from going # to the server’s access logs. However, an error will be # reported in the error log file. If this is your only choice, # and you want to suppress these messages, adding a “LogLevel crit” # directive within your VirtualHost or root configuration for # Apache will turn them off. ErrorDocument 404 /mtview.php ErrorDocument 403 /mtview.php
Appendix ✦ Using Movable Type 3.1
389
Six Apart created this .htaccess file, but it is not included with the Movable Type 3.1 installation, either in the full or upgrade versions. You must create it manually. The purpose of the file is to redirect requests for the dynamic pages to a PHP script, mtview.php. The mtview.php script generates pages dynamically as pages are requested. The script will be created when a special index template is rebuilt, the Dynamic Site Bootstrapper. You can use a weblog’s overall template policy to declare how often, if at all, files should be created dynamically. When you click the Templates button in the sidebar menu of the software’s browser interface, the Build Options section atop the Templates page lists the possible choices, as shown in Figure A-1.
Figure A-1: Choosing a template publishing policy.
Choose the Build All Templates Statically option to adopt the same functionality as prior versions of Movable Type, publishing all files only as a consequence of a rebuild. Choose the Build Only Archive Templates Dynamically option to take advantage of the new functionality to eliminate the need for archive page rebuilds. All index templates will be published statically. Choose the Set Each Template’s Build Options Separately option to choose dynamic or static publishing on a per-template basis. Click the Save button to commit your choice. If you choose the last option and set template options separately, a new checkbox appears on each template’s editing form (see Figure A-2).
390 Movable Type 3 Bible, Desktop Edition
Figure A-2: Editing a template’s publishing policy.
To publish from a template dynamically, enable the checkbox above the text Enable Dynamic Building for this Template label. The fastest way to take advantage of this new functionality is to publish all archives dynamically and other files statically. Doing so speeds up the site rebuild process, making all features of the site more responsive.
Managing Entry Categories and Subcategories Movable Type 3.1 also includes a new category management tool for weblog entries that supports subcategories. This tool uses a system based on the SubCategories plug-in developed by David Raynes, incorporated into Movable Type with his assistance. You can create new subcategories under each category and even switch them from one category to another, which makes reorganizing your weblog easy if existing categories and subcategories prove inadequate. All of this new functionality has been integrated into the Categories form (see Figure A-3), which you can view by clicking the sidebar button Categories.
Appendix ✦ Using Movable Type 3.1
391
Figure A-3: Managing weblog categories and subcategories.
On the Categories page, the subcategories are displayed below each category. To add a new subcategory, type its name in the text field below the category and click Create Subcategory.
Gotcha
How can you tell the difference between categories and subcategories? Look for the indentation to the left of subcategory names. In Figure A-3, the News category has a Political subcategory.
Use the Move button to change the category to which a subcategory belongs.
Index SYMBOLS \ (backslash character), 118 / (forward slash character), 54, 164 > (greater-than character), 10 < (less-than character), 10 # (pound sign) Amazon content, 307 anchor tags, 133 script names, 41 uploading photos and other files, 105–106
A account TypeKey, verifying, 162 weblog configuration, setting up, 51–52 ActivePerl distribution, 23 activity log data, retrieving with MySQL plug-ins, 289 monitoring setup, 61–62 address, e-mail author’s, displaying, 128, 130, 272–274 Blogger, returning, 259 comments, tagging, 175, 206 phony users, 164 sharing publicly, 59 TypeKey verifying, 161–162 address, IP banned listing, 280 retrieving weblog data, 288 banning comments, 169–171 pings, managing, 188–189 exporting comments, 206 mapping host names, 170 throttling repeated messages from, 62 aggregator, content Movable Type category collecting, 193–195 other systems, 192–193 retrieving, 295 routing category to, 195–196 Allen, Jay (plug-ins creator), 213, 375 Amazon Associates, 307–308 Amazon plug-in content, sharing, 308–311 custom searches, 311–313 described, 301, 307–308
products, presenting by number, 313–316 wish and other product lists, sharing, 316–319 Amazon Standard Item Number (ASIN), 313–314 Analog Web server analysis program, 62 anchor tags, 133 animation, GIF, 97 Apache Web server CGIWrap, 30 Movable Type scripts, placing, 38 API (application programming interface) Blogger calling methods author’s account information, retrieving (blogger.getUserInfo), 259 deleting entry (blogger.deletePost), 257 described, 4, 255–256 entry, storable or publishable (blogger.newPost), 256 list of weblogs, retrieving (blogger.getUsersBlogs), 258 one or more recent entries, retrieving (blogger.getRecentPosts), 257–258 replacing existing entry (blogger.editPost), 257 weblog entries, exporting, 17, 240–241 Google search engine, 226–229 Metaweblog calling methods described, 260–261 new entry (metaweblog.newPost), 261 recent entries, retrieving (metaweblog.getRecentPosts), 262–263 replacing entry (metaweblog.editPost), 262 retrieving entry (metaweblog.getPost), 262 uploading files to Web server (metaweblog.newMediaObject), 263 Movable Type calling methods assigned categories, retrieving (mt.getPostCategories), 265 categories, setting or removing all (mt.setPostCategories), 265–266 defined categories, retrieving (mt.getCategoryList), 264–265 filters, supported (mt.supportedTextFilters), 267 Continued
394 Index ✦ A—B API (application programming interface) (continued) methods, supported (mt.supportedMethods), 267 rebuilding files (mt.publishPost), 264 titles, retrieving entry (mt.getRecentPostTitles), 266–267 trackback pings, retrieving (mt.getTrackbackPings), 266 XML-RPC libraries, 255 appkey, Blogger acquiring, 259 described, 256 application programming interface. See API applications acquiring Movable Type, 4–5 connecting Movable Type to other, 17–18 weblog configuration, licensing, 55–56 archive deleted entries, 87–88 file templates, 148–150 Google, slowing down, 229 index template, 108 linking tags identifying, 156 with template tags, 275 “on this day” feature, 270–272 organizing weblog, 88–89 pages creating automatically, 137–138 creating with template, 146–148 linking with template tags, 132–133, 275 template tags, 138–139 trackback functionality, 186 URL, 53 ASIN (Amazon Standard Item Number), 313–314 assigned categories, retrieving (mt.getPostCategories), 265 Atom newsfeed syndication files API, editing weblog with, 352–354 authentication tokens, seeking, 52 author, specific (person construct), 344 categories, limiting to, 89 content constructs, 340–342 creating, 338–339 date constructs, 342–343 globally unique identifiers, defining (id element), 347–348 index, 324 link constructs, 343–344 link tags identifying, 156 Perl module, installing, 27 publishing, 350–352 resources, linking together, 348–349 support for, 12, 18 writing, 345–349 XML data, 339–340
attributes category, grouping (glue attribute), 137 JavaScript text-encoding, 117–118 language, 121 tag author, 112 category, 125 global, 114–116 Google, 227–228 MTRandomLine, 305 Perl plug-ins handling, 360–362 trackback pings, 278 template entry, 125–128 audience, writing for, 15–16 author Atom element, 340, 346 Blogger account information, retrieving (blogger.getUserInfo), 259 comment tag, 174, 206 crediting imported entries, 244 displaying entry by, 128 exporting, 204 filtering entries by, 86–87 importing from other weblogs, 234, 235 permissions, retrieving with MySQL plug-ins, 290 plug-ins, managing, 272–274 programming plug-ins with, 382–383 retrieving with MySQL plug-ins, 280–281 tag attributes, 112, 125, 130 weblog, adding other, 59–61 autodiscovery feature, trackback, 190–192 automating archive page creation, 137–138 file rebuilding, 145 weblog backup, 207–210
B backslash character (\), 118 backups automating, 207–210 comments and trackback pings, 206–207 described, 200–203 multi-line entry fields, 205–206 single-line entry fields, 203–205 banned IP address comments, viewing, 280 retrieving with MySQL plug-ins, 288 viewing attempts to use, 169 banning IP address from comments feature, 169–171 pings, 188–189 TypeKey user, 171–172 Barger, Jorn (Internet writer), 337 Berkeley DB access, setting up, 39 Movable Type, installing, 43, 45
Index ✦ B—C setup, 23, 24 support for, 3 Blogger API (Application Programming Interface) application key, acquiring, 259 author’s account information, retrieving (blogger.getUserInfo), 259 deleting entry (blogger.deletePost), 257 described, 4, 255–256 entry, storable or publishable (blogger.newPost), 256 list of weblogs, retrieving (blogger.getUsersBlogs), 258 one or more recent entries, retrieving (blogger.getRecentPosts), 257–258 replacing existing entry (blogger.editPost), 257 weblog entries, exporting, 17, 240–241 BlogRoots Web site, 193 BloGTK client, 254 body tags, 112 books, product number for, 313 browser exported data, formatting, 201 file location, keeping in template, 123–124 JavaScript capability, needed, 3 Movable Type, controlling, 6 plug-ins, managing with, 376–377 PNG format, 99 QuickPost link, creating, 79–80 settings, checking, 6–7 sites listed, 4
C Cabral, Marcelo L. L. (w.bloggar creator), 253 caching Perl code, 297 calendar links, 151–154 “on this day” feature, 270–272 callbacks, object, 70 cascading style sheet (CSS) index template, 108 Web server, checking, 42 category content aggregator, converting to, 194–195 creating new, 90–92 described, 8, 9, 89–90 editing, 93–94 enhancing with plug-ins, 274–276 filtering entries by, 86–87 grouping (glue attribute), 137 importing from old weblogs, 90–92 from other weblogs, 234–235 retrieving with Movable Type API (mt.getCategoryList), 264–265
395
with MySQL plug-ins, 284–285 sorting, 127 routing to content aggregator, 195–196 tag attributes, 125 template tags, 136–137 10 most recent weblog entries, 137 cell phones, moblogging and described, 95 preparing files, 14 Central Perl Archive Network. See CPAN CGI (Common Gateway Interface) scripts enabling, 18 path, 38 plug-in, 378–380 relative and full URLs, 124 CGIWrap, 29–32 change, importance of, 1 checkboxes, search form, 219 Choate, Brad (plug-ins author), 270 classes, programming plug-ins with authors, 382–383 described, 380–382 entries, manipulating, 384–385 objects, 383–384 client software, connecting to Movable Type, 253–254 client/server application, Movable Type as, 3 Coates, Tom (trackback, comment on), 180 collaborating, 7–8 command-line environment, operating system, 22 comments abuses of, 159, 371 from banned addresses, viewing, 280 banning IP address, 169–171 TypeKey user, 171–172 benefits of using, 15 enabling, 75 exporting allowing, 204 performing, 206–207 HTML code, 124 importing from old weblogs, 17 from other weblogs, 234 managing and filtering, 168–169 policy, setting, 165–167, 172–173 rebuilds, 84 receiving with TypeKey feature account, verifying, 162 deciding whether to use, 164 described, 160 signing in, 160–163 token, acquiring, 163–164 rejected, logging, 62 retrieving with MySQL plug-ins, 285–286 Continued
396 Index ✦ C—D comments (continued) template filtering tags, 116 presenting, 175–177 tags, 173–175 weblog entries, importing, 236–240 Common Gateway Interface. See CGI scripts compression, graphics, 98 computer system requirements, 3–4 conditional tag, Perl plug-in, 372–373 configuration file, editing CGIWrap, 30–31 Creative Commons license, 56–59 Movable Type database access, 39–40 described, 37–38 directories, choosing, 38–39 e-mail servers, 40–41 script names, changing, 41 weblog account, setting up, 51–52 activity logs, monitoring, 61–62 authors, adding other, 59–61 creative commons license, adopting, 56–59 first, creating, 52–54 Movable Type, first run of, 49–51 path directories, 54 software, licensing, 55–56 connecting. See links container tag authors, filtered by permissions, 274 comments, managing, 173–175 conditional output, 113, 154–155 Creative Commons license, 124, 334 described, 112 extended entry, 132 Perl plug-ins, creating, 362–367 pings, determining, 196–197 searches, 219 weblogs, all on server, 125 content advantages of using Movable Type, 2–4 Amazon, sharing, 308–311 Atom element, 340 content aggregator, trackback links Movable Type category collecting, 193–195 other systems, 192–193 retrieving, 295 routing category to, 195–196 content-management systems, 2–4 context, 367 “continue reading” entries, creating, 72–74 contributor Atom element, 340, 346 Blogger account information, retrieving (blogger.getUserInfo), 259
comment tag, 174, 206 crediting imported entries, 244 displaying entry by, 128 exporting, 204 filtering entries by, 86–87 importing from other weblogs, 234, 235 permissions, retrieving with MySQL plug-ins, 290 plug-ins, managing, 272–274 programming plug-ins with, 382–383 retrieving with MySQL plug-ins, 280–281 tag attributes, 112, 125, 130 weblog, adding other, 59–61 Coordinated Universal Time (UTC), 342 copyright law, 58, 346 CPAN (Central Perl Archive Network), 302 crackers, 29 Creative Commons license RSS 1.0 template, 333–334 template tags, 124 weblog configuration, 56–59 CSS (cascading style sheet) index template, 108 Web server, checking, 42
D data exporting comments and trackback pings, 206–207 described, 200–203 multi-line entry fields, 205–206 single-line entry fields, 203–205 importing with MySQL plug-ins, 281–284 from old weblogs, 18 weblog entries, 231–236, 244–246 index templates, 209–210 uploading files, 104–105 XML-RPC support, 248–249 database access, 39–40 author permissions, 290 comments, displaying, 299 compatible, 3, 21 Movable Type, preparing, 36 programs, sites listed, 4 Radio UserLand entries, importing, 241 templates and linked template files, 293–295 trackback pings, 292–293 Web server, setting up, 23–25 date authored, enabling, 71–72 entries ordered by, 133–136 months, specifying for calendar, 153 date and time Atom element, 340, 346 entry, stamping, 129, 132
Index ✦ D—E exporting entry fields, 203–205, 206 importing single-line entry fields, 233–234 RSS 1.0, 333 template, formatting, 119–121 debugger, XML-RPC, 252 deleting all entry categories (mt.setPostCategories), 265–266 entries, 87–88 entry (blogger.deletePost), 257 entry form items, 77–78 files from import directory, 246 uploaded files, 14, 106 digital photos GIF format limitations, 97 JPEG format, 98 directories include files, specifying, 155 Movable Type, choosing, 38–39 name, transmitting HTML tag into, 117 path, setting up, 54 settings, 53 displaying database comments, 299 e-mail address, author’s, 272–274 HTML formatting, permissible, 117 images in pop-up window calendars, 151–154 containers, 154–157 described, 150 100 most recent posts, 133–134 pings, 197 template entry tags, 128–132 text, 113–119 trackback pings, 277 dividing weblog entry form into two fields, 72–74 domain-name system, 170 downloading Movable Type, 33–34 MySQL, 24 Dublin Core 1.1 Internet resource information, 345 Dumpleton Software XML-RPC debugger, 252 dynamic IP addresses, 170
E Ecto client, 254 editing authors, granting permissions to other, 60–61 configuration file, 37 entry form default values, 75–78 items excluded from additional, 77–78 trackback links, 182–183 uploading photos and other files, 103–104 writing entry, 70–72 images, 102
397
template, 143–146 text form, 76–77 word processing tool, 253–254 e-mail notification data, retrieving, 289–290 pings, notifying by, 188 servers, configuring, 40–41 Web hosting service provider, suggested, 18 e-mail address author’s, displaying, 128, 130, 272–274 Blogger, returning, 259 comments, tagging, 175, 206 phony users, 164 sharing publicly, 59 TypeKey verifying, 161–162 entry categories assigned, retrieving (mt.getPostCategories), 265 filing in, 9 setting or removing all (mt.setPostCategories), 265–266 container template tags, 133–136 data, retrieving with MySQL plug-ins, 286–287 deleting (blogger.deletePost), 257 described, 8 editing, 86–88 excerpt, 9, 71 exporting multi-line fields, 205–206 extended, 9 importing from Blogger, 240–241 comments and trackback pings, 236–240 data, moving, 231–236 data to Movable Type, 244–246 described, 231 from Radio UserLand, 241–243 manipulating, 384–385 new, logging, 62 one or more recent, retrieving (blogger.getRecentPosts), 257–258 pings, displaying all, 197 QuickPost window, 78–80 replacing (blogger.editPost), 257 sending pings for each, 190–192 storable or publishable (blogger.newPost), 256 summary, 71 template tags, 125–136 entry form described, 66–70 dividing into two fields, 72–74 editing setting default values, 75–78 trackback links, 182–183 Continued
398 Index ✦ E—G entry form (continued) uploading photos and other files, 103–104 writing entry, 70–72 graphic, adding, 103 Eriksson, Richard (MovableBLOG writer), 180–181 errors logging, 62 reporting, 368–369 escaped text, syndication formats’ use of, 342 Estey, Gavin (Weather Underground plug-in author), 302 excerpt, 9, 71 existing entry, replacing (blogger.editPost), 257 exporting Blogger entries, 17, 240–241 Radio UserLand entries, 241–243 weblog data to text file, 200–207 extended entry container tag, 132, 155 described, 9 extensible markup language. See XML external Web content plug-ins Amazon content, sharing, 308–311 custom searches, 311–313 described, 307–308 products, presenting by number, 313–316 wish and other product lists, sharing, 316–319 described, 301–302 random quotes and other text, 303–306 weather, local, 302–303
F feedback. See comments; trackback links; trackback pings fields, dividing weblog entry form in half, 72–74 file archive templates, 148–150 deleting from import directory, 246 uploaded, 14, 106 include, specifying, 155 moblog, preparing, 14 name, transmitting HTML tag into, 117 path to, 305 rebuilding all index templates or entire weblog, 143–144 automatic, turning off, 145 change prompting, 84–85 entry, all associated with (mt.publishPost), 264 error halting, 368–369 exporting all entries, 210
Google slowing down, 229 limiting to index files, 85–86 with Weather Underground plug-in, 303 uploading, 104–105 filters comments, 168–170 entries matching author, category, or publication status, 86–87 entry text, identifying, 205 line breaks, importing from other weblogs, 235 output text, processing, 118 supported, listing (mt.supportedTextFilters), 267 finding. See searches Footbridge client, 254 form entry described, 66–70 dividing into two fields, 72–74 editing, setting default values, 75–78 graphic, adding, 103 writing, 70–72 QuickPost, 78–80, 79 search basic, 215–217 enhanced, 217–220 format template, 10 text for, setting editing form, 76–77 Web graphics, selecting, 99 forward slash character (/ ), 54, 164 FTP permissions, 43
G Gainsbourg, Serge (French singer), 50 games, 104–105 GIF format best use of, 99 preparing for Web, 97–98 global attributes, 114–116 global filter Perl plug-in described, 357 scripts, enhancing, 369–371 global template tags, 122–125 Google licensing, 226 tags, 227–229 trackback content, 192–193 graphics manipulation tool, 28 graphics, pop-up window calendars, 151–154 containers, 154–157 described, 150 greater-than character (>), 10 Greymatter weblog program, 17
Index ✦ H—L
H Haughey, Matt (MetaFilter weblog publisher), 95 home page author’s, 128, 130, 175 index template, 108, 143 host, finding Movable Type, 18 publishing, 18 host names, 170 hosting service, 18 HTML (HyperText Markup Language) comments, 167 entries, composing, 67–68 Google search results, publishing, 228–229 permissible, listing in template, 116–117 search, converting to, 216 titles, extracting, 245 HTTP (HyperText Transfer Protocol). See also XML-RPC protocol Atom server, 354 plug-ins, handling, 360 hyperlinks. See links HyperText Markup Language. See HTML
I ID number, entry Blogger entry, returning, 256, 261 linking to archive pages, 132–133 padding, 131 image manipulation tool, 28 ImageMagik software, 102 images, pop-up window calendars, 151–154 containers, 154–157 described, 150 incentive, Amazon sales, 307 include files, specifying, 155 index archived pages, master, 138 files, limiting rebuild to, 85–86 100 most recent posts, displaying, 133–134 search form, attaching, 215 templates described, 108–110 exporting, 209–210 newsfeeds, 324 rebuilding, 143–144 stock quote, 366 initializing Movable Type software, 46–47 input element, form, 216 installation, verifying Perl 5, 22–23 Web server, 31 installing Movable Type database, preparing, 36 Perl 5 components, 35 security and connection issues, 18
399
software, downloading, 33–34 on Web server, 5–6 instructions, search, 222 interface. See also API (application programming interface); CGI (Common Gateway Interface) scripts browser, 123–124 graphics file, 42 links, 377–380 International Standard Book Number (ISBN), 313–314 Internet Explorer (Microsoft) exported data, formatting, 201 scripting settings, 6 Internet Topic Exchange Web site, 192 IP address banned listing, 280 retrieving weblog data, 288 banning comments, 169–171 pings, managing, 188–189 exporting comments, 206 mapping host names, 170 throttling repeated messages from, 62 ISBN (International Standard Book Number), 313–314
J J2ME (Java 2 Millennium Edition), 254 Java, XML-RPC, 255 JavaScript described, 3 interface functions, uploading, 42 QuickPost window, opening, 79 text-encoding attributes, 117–118 JPEG format best use of, 99 preparing for Web, 98
K Kablog, 254 keyword container tags, 155 multi-line fields, exporting, 205 summary entry, 71
L label element, form, 216 language attribute, 121 less-than character (
