Panorama went through a pretty rapid development cycle, making it into Firefox 4 which was released today (yay!). Moreover, for a while we were developing outside of mozilla-central, without the regular “patches require tests” requirement. This makes checking its test coverage particularly important.

Check out the final result, the Panorama test coverage report. The good news: our code coverage is 86%! (Some notes on what improvements can be made are in the bug.)

PhiliKON had previously worked on hooking into the JS Debugger service’s interruptHook to test xpcshell tests. I modified this code to run instead in the Mochitest browser chrome tests. This code can be found on the bug.

With this patch applied, I invoked the test suite with the following code: TEST_PATH=browser/base/content/tests/tabview COVERAGE_FILTER="*tabview*" COVERAGE=true make -C obj-ff-dbg mochitest-browser-chrome . That’s a regular mochitest-browser-chrome invocation with the COVERAGE=true flag which turns on code coverage checking, and COVERAGE_FILTER=*tabview* which filters out results from files which don’t have “tabview” in their paths. This creates a file called coverage.json in the working directory of the test suite, meaning, for me, obj-ff-dbg/_tests/testing/mochitest/.

This JSON file is a multidimensional array, with file paths and then line numbers as keys. The file paths here, as best as possible, have been converted into local filesystem paths. PhiliKON built a script which produces beautiful reports based on this output.

A word of warning: running with this JSD interruptHook is ridiculously slow. A number of tests for Panorama are timing-dependent (drag-drop tests, for example), making some of them fail, but that’s okay… as long as it completed not via a timeout, it actually did run through all the code. In order to get this to run through everything with some degree of control, I split up the mochitest tabview suite in to a few chunks. I then took the multiple resulting coverage.json files and passed them into another script, in tools/coverage/aggregate.py, which takes multiple JSON results like this and puts them together into a single JSON file. I then passed this aggregate JSON file to PhiliKON’s wonderful report script and—voila—the Panorama test coverage report! Easy as pie.

Related posts:

1. Performance vs Responsiveness —or— How I Made the Parser Twice As Fast in One Day
2. Beginning development with Jetpack SDK 0.2
3. Keep up with Yet Another Related Posts Plugin with RSS!

Related posts brought to you by Yet Another Related Posts Plugin.

Mozilla Labs recently released version 0.2 of the Jetpack SDK, which fixes some issues of the 0.1 release such as a glitch regarding development with Windows. SDK 0.2 doesn’t include the planned APIs for rapid development of new browser functionality, but you can still play with SDK 0.2 to get a flavor for development with the Jetpack SDK.

In this article we begin by setting up an SDK 0.2 development environment and explain the steps required to develop a simple, practical add-on using SDK 0.2. The instructions here are for Windows, but the basic steps are the same in every platform.

Installing Python

The first step to using the Jetpack SDK is to install Python. How to install Python depends on your OS, but in Windows you can choose the “Python 2.6.5 Windows installer” from the Python site and follow the installation wizard. Here, I’ll use C:\Python26\ as the installation path.

After the install, you can activate the python command in your command line by adding C:\Python26 to the Windows Path preference. (If there is already another value, delimit with a semicolon: “;”.) Run the command “cmd” from the Start menu to start the command prompt and run python -V to confirm the Python version, Python 2.6.2:

C:\>python -V
Python 2.6.2

Setting up the Jetpack SDK

Next, we set up the Jetpack SDK. Download the Jetpack SDK 0.2 package from the Jetpack site, unzip it, and place it somewhere convenient. Here, I used C:\jetpack-sdk-0.2.

To use the Jetpack SDK, it must be “activated.” From the command prompt, go to the Jetpack SDK folder and run bin\activate:

C:\jetpack-sdk-0.2>bin\activate
Welcome to the Jetpack SDK. Run 'cfx docs' for assistance.
(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2>

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2>cfx docs
One moment.
Opening web browser to http://127.0.0.1:8888.

The package directory structure

Addons built with the Jetpack SDK are called “packages.” Let’s try building a simple “hello world”-style package, but first let’s see what the final directory structure of this package will look like:

directory/file	Note
jetpack-sdk-0.2	the Jetpack SDK folder
packages	the main packages folder
hello-world	package root
package.json	package manifest file
README.md	package documentation
lib	the package code directory
main.js	main program code
simple-dialog.js	a custom code library

The package’s root directory is placed in the “packages” directory in the Jetpack SDK folder, and includes the package.json manifest file and the README.md documentation file. The lib folder includes the package’s main program code and any custom libraries used by our addon.

Creating the package

We begin by creating the hello-world directory in C:\jetpack-sdk-0.2\packages . Next the manifest file package.json is created. The manifest file includes metadata about our package in JSON format. If you’ve ever created a XUL-style addon before, you can think of this as similar to the install.rdf file. Here, I used the following as the manifest:

{
    "id": "helloworld@xuldev.org",
    "version": "0.1",
    "description": "This is my first package.",
    "author": "Gomita <gomita@xuldev.org>"
}

Next, reload the SDK documentation in the browser and confirm that “hello-world” shows up under “Package Reference.”

Writing the main code

The next step is to add some working code to the hello-world package. Create a lib folder under the package root and create a main.js under lib with the following code:

exports.main = function(options, callbacks) {
    console.log("Hello, World!");
};

It’s worth noting that, in the current Jetpack SDK, calling “console.log("こんにちは");” doesn’t yield the expected Japanese output. In the future such output will be handled through the planned localization API.

Testing our package

With some simple code in our main function, it’s time to try this code out. To test this code, we run cfx run -a firefox in the command prompt. By running cfx run with the -a firefox option, we load our package into a brand new Firefox profile and launch Firefox.

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2>cd packages\hello-world


(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2\packages\hello-world>cfx run -a firefox
info: Hello, World!
OK
Total time: 1.531000 seconds
Program terminated unsuccessfully.

Using a standard library

Now we’ll edit our code to invoke the timer library which is one of the Jetpack SDK’s standard libraries. The timer library is a module which abstracts various timer-related functionality, similar to the DOM’s window.setTimeout, window.clearTimeout. Details on this library are available in the SDK documentation. Moreover, although not in the documentation, timer.setInterval and timer.clearInterval also work in this version.

To use this library in our main program code, we first must invoke this library with the CommonJS require function. We modify the main.js file as follows:

var timer = require("timer");
exports.main = function(options, callbacks) {
    timer.setInterval(function() {
        console.log(new Date().toLocaleTimeString());
    }, 1000);
};

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2\packages\hello-world>cfx run -a firefox
info: 10:37:21
info: 10:37:22
info: 10:37:23
info: 10:37:24
info: 10:37:25

Creating a custom library

Next we’ll create a custom library to add some functionality not currently included in the Jetpack standard library. Implementing advanced functionality in add-ons, like filesystem access, involves using XPCOM components. Jetpack encourages seprarating the use of XPCOM components into separate modules which are then used by the main program code. The Jetpack SDK doesn’t currently disallow direct XPCOM access within Jetpack add-on code, but such a restriction is forthcoming. Modularizing XPCOM code into separate libraries now allow you to easily migrate to equivalent standard libraries in the future.

Let’s create a simple-dialog library to display a modal dialog much like window.alert does. The Jetpack code’s runtime environment doesn’t include access to the regular window or document objects, so just calling window.alert doesn’t work. To create an alert from this context, we use the <a href="https://developer.mozilla.org/en/nsIPromptService">nsIPromptService</a> XPCOM component. In our package’s lib folder, create a simple-dialog.js file. Just like our main program code, we implement this library as a CommonJS module using exports.<em>methodname</em> = function(...){...}.

The simple-dialog library will have these two methods:

Here is the code for simple-dialog.js:

var promptSvc = Cc["@mozilla.org/embedcomp/prompt-service;1"].
                getService(Ci.nsIPromptService);


exports.alert = function(text) {
    promptSvc.alert(null, "[Jetpack]", text);
};

exports.confirmYesNo = function(text) {
    var pos = promptSvc.confirmEx(
        null, "[Jetpack]", text, promptSvc.STD_YES_NO_BUTTONS,
        null, null, null, null, {}
    );
    return pos == 0;
};

Using our custom library

Let’s call this new custom library from our main program code and verify that it works. Here’s our updated main.js file:

var simpleDialog = require("simple-dialog");


exports.main = function(options, callbacks) {
    var adult = simpleDialog.confirmYesNo("Are you over 18 years old?");
    if (adult) {
        simpleDialog.alert("Welcome!");
    }
    else {
        simpleDialog.alert("Good bye!");
    }
};

Implementing a network status observer

Now let’s use this hello-world package as a foundation for a more practical add-on. Using the <a href="https://jetpack.mozillalabs.com/sdk/0.2/docs/#module/jetpack-core/observer-service">observer-service</a> module included with the Jetpack SDK, we can monitor Firefox’s online/offline network status changes.

Firefox internally broadcasts various application events to observers via the <a href="https://developer.mozilla.org/ja/NsIObserverService">nsIObserverService</a> XPCOM component. When Firefox goes offline, a network:offline-status-changed notification is broadcast. To subscribe this notification and act on it, we use the observer-service library’s add method. add’s first argument is the name of the notification we want to subscribe to and the second argument is a callback function. The callback function is given two arguments, of which the second is a string equal to either “online” or “offline.” In our add-on, we’ll check this value and display an appropriate alert using simple-dialog.

var simpleDialog = require("simple-dialog");
var observer = require("observer-service");


exports.main = function(options, callbacks) {
    observer.add("network:offline-status-changed", function(sbj, data) {
        if (data == "online") {
            simpleDialog.alert("Firefox is now online.");
        }
        else if (data == "offline") {
            simpleDialog.alert("Firefox is now offline.");
        }
    });
};

Adding documentation

If you add documentation to a package, you can view it by clicking that package in the SDK Documentation. To add documentation, create a README.md file in the package root directory. README.md is written in Markdown format which looks like this:

This is my *first* package.
* foo
* bar
* baz

Now if you load the SDK documentation using cfx docs and click on the “hello-world” link, you’ll see this documentation together with the package metadata.

Exporting an install package

Jetpack add-ons which are created in this way can then be exported into Firefox-standard XPI files. To export an XPI, go to the package’s root directory in the command prompt and run cfx xpi.

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2\packages\hello-world>cfx xpi
Exporting extension to hello-world.xpi.

Related posts:

1. Jetpack Ambassadors in MV
2. Ubiquity Localization Update
3. Spring is for Speaking: JSConf, WordCamp SF, IACL

Related posts brought to you by Yet Another Related Posts Plugin.

Shadowbox is organized around different “players”—one for each kind of media that will be displayed. The library by default comes with players for Flash, HTML fragments, iframes, QuickTime, and Windows Media. Some of these players, like those for images and video, automatically recognize the media size and adjust the lightbox accordingly, while others such as the iframe player can use a set size or can fill the screen. For the Edgerton site, though, we had a need for displaying an iframe but in the dimensions of a set image, so that we could display the image with an overlay. Here are some notes on how to implement a custom player for Shadowbox.

The first step to getting Shadowbox to recognize a custom player is to modify the players loaded by shadowbox.js. I called my player “hybrid,” as it’s like a cross between the iframe and img players.

Shadowbox.options.players=["html","iframe","img","hybrid"];

Now Shadowbox will try to look for the file players/shadowbox-hybrid.js. That’s where we will create our custom player. Start by duplicating the iframe player file. Next, we can make one more change to shadowbox.js. In the getPlayer function, add a line that will return “hybrid” when it recognizes a lightbox which should use the hybrid player. I added the following line, which uses the hybrid player when the text “galleries” is in the a tag’s href attribute.

if (/galleries/.test(content)) return "hybrid";

Finally, you must actually write the new player. There’s a readme file which describes the interface:

All players should implement the same interface. This makes it possible for the Shadowbox class to know what methods to call and properties to check on player objects.

The interface is described here, with some simple explanations of how each method and/or property is to be used.

height

(Number) The height of the object (in pixels)

width

(Number) The width of the object (in pixels)

ready

(optional, Boolean) True if the content is ready to be loaded, false otherwise. Useful when the script should wait until the content loads before proceeding (see below)

resizable

(optional, Boolean) True if the content can be dynamically resized by the script (e.g. images, but not most movie formats)

append()

Appends this object to the DOM

remove()

Removes this object from the DOM

onLoad()

(optional) Called after the content is loaded and the loading layer is hidden

onWindowResize()

(optional) Called when the window is resized

I found these directions quite easy to follow. For our purposes, there was also a note on how to set an object’s height and width based on an image.

Hopefully these notes are helpful for others who hope to take full advantage of this very powerful JavaScript library.

Related posts:

1. I’m Seriously Dreaming of a White Christmas
2. The Gift That Keeps On Giving
3. Atayal cultural festival

Related posts brought to you by Yet Another Related Posts Plugin.

Warning: preg_match() [function.preg-match]: Compilation failed: unrecognized character after (?< at offset 3 in /…/html/blog/wp-content/plugins/wp-syntax/geshi/geshi.php on line 2132

This seemed to be coming from the version 1.0.8.4 version of Geshi I had installed. A quick google search for “geshi line 2132” gives you over a thousand errors, so this seems to be common issue. Geshi is a fabulous and popular syntax highlighter and is the core component of the WP-Syntax plugin for WordPress.

I did some digging around and realized that the issue was with the compilation of this monstrosity of a regular expression, used (as far as I can tell) to identify PHP code snippets, for example the <?php … ?> keywords:

/(?<start><\\?(?>php\b)?)(?:
(?>[^\"'?\\/<]+)|
\\?(?!>)|
(?>'(?>[^'\\\\]|\\\\'|\\\\\\\|\\\\)*')|
(?>\"(?>[^\"\\\\]|\\\\\"|\\\\\\\\|\\\\)*\")|
(?>\\/\\*(?>[^\\*]|(?!\\*\\/)\\*)*\\*\\/)|
\\/\\/(?>.*?$)|
\\/(?=[^*\\/])|
<(?!<<)|
<<<(?<phpdoc>\w+)\s.*?\s\k<phpdoc>
)*(?<end>\\?>|\Z)/sm

Not knowing exactly where to start in diagnosing this crazy expression, I simply disabled those “script delimiters” in the geshi/php.php file. The sections I commented out are lines 1080-1101. Now the script delimiters like <?php don’t get highlighted nicely, but I feel that’s a small price to pay for eliminating these errors. Another solution for the WP-Syntax users seems to be to downgrade to 0.9.4. Hopefully in the near future an update to Geshi will come out which fixes this issue once and for all.

Related posts:

1. Keep up with Yet Another Related Posts Plugin with RSS!
2. Yet Another Related Posts Plugin
3. Modifiying WordPress plugin activation behavior

Related posts brought to you by Yet Another Related Posts Plugin.

You’ve seen the video. You speak another language. And you’re wondering, “how hard is it to add my language to Ubiquity with Parser 2?” The answer: not that hard. With a little bit of JavaScript and knowledge of and interest in your own language, you’ll be able to get at least rudimentary Ubiquity functionality in your language. Follow along in this step by step guide and please submit your (even incomplete) language files!

As Ubiquity Parser 2 evolves, there is a chance that this specification will change in the future. Keep abreast of such changes on the Ubiquity Planet and/or this blog (RSS).

Set up your environment

If you’re new to Ubiquity core development, you’ll want to first read the Ubiquity 0.1 Development Tutorial to learn how to get a live copy of the Ubiquity repository using Mercurial. Once you’ve set up your Firefox profile to use this development version, make sure to try changing the extensions.ubiquity.parserVersion value to 2 in about:config (as seen in this demo video) to verify that Parser 2 is working for you.

As you read along, you may find it beneficial to follow along in the languages currently included in Parser 2: English, Japanese, Portuguese, and Swedish (and the incomplete Chinese and French).

The structure of the language file

Each language in Parser 2 gets its own file which acts as a JavaScript module. You’ll need to look up the ISO 639-1 code for your language… Here we’ll use English (code en) as an example here and the JavaScript language file would then be called en.js and go in the /ubiquity/modules/parser/new/ directory of the repository.

Here is the basic template for a Ubiquity Parser 2 language file:

1
2
3
4
5
6
7
8
9
10
11
12

var EXPORTED_SYMBOLS = ["makeEnParser"];
 
if ((typeof window) == 'undefined') // kick it chrome style
  Components.utils.import("resource://ubiquity/modules/parser/new/parser.js");
 
function makeEnParser() {
  var en = new Parser('en');
 
...
 
  return en;
};

After lines 1-4 which set up the JavaScript module, everything else is wrapped in a factory function called makeLaParser (for Latin) or makeEnParser (for English, en) or makeFrParser (for French, fr), etc. This function initializes the new Parser object (line 7) with the appropriate language code, sets a bunch of parameters (elided above) and returns it. That’s it!

Now let’s walk through some of the parameters you must set to get your language working. For reference, the properties the language parser object is required to have are: branching, anaphora, and roles.

Identifying your branching parameter

  en.branching = 'right'; // or 'left'

One of the first things you’ll have to set for your parser is the branching parameter. Ubiquity Parser 2 uses the branching parameter to decide which direction to look for an argument after finding a delimiter or “role marker” (most often, these are prepositions or postpositions. For example, in English “from” is a delimiter for the goal role and its argument is on its right.

So “John” is a possible argument for the source role, but “Mary” should not be. Ubiquity can figure this out because English has the property en.branching = 'right'.

In Japanese, on the other hand, the argument of a delimiter like から (“from”) is found on the left of that delimiter, so en.branching = 'left'.

In general, if your language has prepositions, you should use .branching = 'right' and if your language has postpositions, you can use .branching = 'left'.

For more info:

• see branching on Wikipedia.

Defining your roles

  en.roles = [
    {role: 'goal', delimiter: 'to'},
    {role: 'source', delimiter: 'from'},
    {role: 'position', delimiter: 'at'},
    {role: 'position', delimiter: 'on'},
    {role: 'alias', delimiter: 'as'},
    {role: 'instrument', delimiter: 'using'},
    {role: 'instrument', delimiter: 'with'}
  ];

The second required property is the inventory of semantic roles and their corresponding delimiters. Each entry has a role from the inventory of semantic roles and a corresponding delimiter. Note that this mapping can be many-to-many, i.e., each role can have multiple possible delimiters and different roles can have shared delimiters. Try to make sure to cover all of the roles in the inventory of semantic roles.

For more info:

• Writing commands with semantic roles
• the proposed inventory of semantic roles
• Wikipedia entry on thematic relations

Entering your anaphora (“magic words”)

  en.anaphora = ["this", "that", "it", "selection", "him", "her", "them"];

The final required property is the anaphora property which takes a list of “magic words”. Currently there is no distinction between all the different deictic anaphora which might refer to different things.

Special cases

Some special language features can be handled by overriding the default behavior from Parser. Many of these features are still in the works, however, so we’d love to get your comments!

Languages with no spaces

If your language does not delimit arguments (or words, more generally) with spaces, there will be a need to write a custom wordBreaker() function and set usespaces = false and joindelimiter = ''. For an example, please take a look at the Japanese or Chinese.

Case marking languages

If you have a strongly case-marked language, you’ll have to write some rules to identify those different cases in wordBreaker() and then add some extra roles for these case markers, but for a number of languages the current design does not allow an elegant solution for parsing such arguments. Updates to this issue will be posted to this trac ticket.

In the mean time, however, if you could write a parser even with only the prepositions/postpositions in your language, that would be a great benefit in getting started in your language. UPDATE: a proposal on how to deal with strongly case-marked languages has been written here: In Case of Case….

Stripping articles

Some languages have some delimiters which combine with articles. For example, in French, the preposition “à” combines with the masculine definite article “le” but not “la”:

1. à + la = à la
2. à + le = au

You can add both “à” and “au” as delimiters of the goal role, but then you will get feminine arguments back with the determiner (e.g. “la table”) while masculine arguments would be parsed without a determiner (e.g. “chat”).

1. “à la table” = “to the table”
2. “au chat” = “to the cat”

One possible solution to this is to write a custom cleanArgument() method. After arguments have been parsed and placed in their appropriate roles, each argument text (say, “la table” or “chat”) are passed to cleanArgument(). You can simply write a cleanArgument() to strip off any “la ” at the beginning of the input and return it and both example inputs will get normalized arguments: “table” and “chat”, respectively. UPDATE: For more up-to-date information on how to deal with these types of articles, please see Solving a Romance Problem.

Test your parser

Now you can go into about:config and change extensions.ubiquity.language to be your language code and restart. All the verbs and nountypes at this point will remain the same as in the English version, but it should obey the argument structure (the word order and delimiters) of your language.¹ If you run into any trouble, feel free to ask for help on the Ubiquity i18n listhost or find me on the Ubiquity IRC channel (mitcho @ irc.mozilla.org#ubiquity). Of course, once you’re at a good stopping point, please contribute your language file to Ubiquity!

More to come…

At this point, you’ve only localized the argument structure of your language… additional work will be required to localize the nountypes and verb names, which is the subject of ongoing discussion… join the Google Group to get in on the discussion!

Related posts:

1. Ubiquity Parser: The Next Generation Demo
2. Rolling out the Roles
3. Foxkeh demos Ubiquity Parser: The Next Generation

Related posts brought to you by Yet Another Related Posts Plugin.

In order to introduce an external ordering source, we need to do four things: 1. create the external ordering source, 2. hook up (read “join”) the external ordering source 3. make sure we use that order, and 4. make it play nice. ^^

By the way, I’m going to assume you, dear reader, are PHP-savvy, proficient in MySQL, and already know a little about WordPress. This how-to is not for the PHPhobic.

The ordering source

For this example, suppose we want to display posts by order of “interestingness.” We’ll just create a table called wp_interestingness with two columns, ID and interestingness and populate it with some data. We’ll even be nice to our database by making sure the ID is the primary key. Easy.

Hook up the external ordering source

When you run a query through query_posts() (or use WP_Query’s query method²), what it’s doing is taking your special request and translating it into a MySQL statement. This means a query like "monthnum=1" is turned into SELECT ... wp_posts.* FROM wp_posts WHERE 1=1 AND MONTH(wp_posts.post_date)='1' .... Every different query introduces something new to the basic SELECT command—in this case, the AND MONTH(wp_posts.post_date)='1'.

We first want to introduce the interestingness for each post and that means joining the new table into the query. We’ll do this using the posts_join filter. This filter lets you add a join statement to the MySQL request.

1
2
3
4
5

add_filter('posts_join','my_join_filter');
function my_join_filter($arg) {
	$arg .= " natural join wp_interestingness ";
	return $arg;
}

Note that here we’re using natural join as wp_posts and wp_interestingness have only one key in common, ID, and that’s exactly the column we want to join them on.

Use the new order

Now that we’ve joined wp_interestingness in, we can refer to wp_interestingness.interestingness in our query. Note now that, by default, an $wpdb->posts.post_date will be used to order the posts. We’ll use another filter here; this time posts_orderby, to patch this part of the query. We’ll search for the default ORDER BY value and replace it with our own interestingness.

1
2
3
4
5
6

add_filter('posts_orderby','my_orderby_filter');
function my_orderby_filter($arg) {
	global $wpdb;
	$arg = str_replace("$wpdb->posts.post_date","wp_interestingness.interestingness",$arg);
	return $arg;
}

By the way, you can now check the resulting MySQL query by echoing $wp_query->request. (If you’re using the WP_Query method I advocated below in footnote (2), you’ll of course have to change $wp_query to the WP_Query object you’re using.)

Learn to play nice ^^

The instructions above do indeed work, but they also cause some major breakdowns in other functions of your blog. Why? That’s because the current code will edit your queries for every instance of The Loop: your index page, your archives, and your RSS feeds. You probably only want to search by interestingness in certain situations. What we need is a way to tell our (admittedly stupid) my_join_filter and my_orderby_filter when they should apply their interestingness magic and when they shouldn’t. There are several ways to set up such a system but here I’ll lay out one that I feel is particularly elegant. We’ll set it up so you can actually use query_posts("orderby=interestingness") and it’ll know what you’re talking about.

One of the first things that happens in query_posts—indeed, way before even the posts_join and posts_orderby filters—is an action hook called parse_query. This lets us look at the initial state of the WP_Query object as it starts to run. In particular, we can look at the orderby query variable and see if we want to order by interestingness. If we do, we’ll set a global variable called $use_interestingness_flag to be true.

1
2
3
4
5
6
7
8

add_action('parse_query','set_use_interestingness_flag');
function set_use_interestingness_flag($query) {
	global $use_interestingness_flag;
	if ($query->query_vars['orderby'] == 'interestingness')
		$yarpp_score_override = true;
	else
		$yarpp_score_override = false;
}

Now we just have to edit our filters so they only run when $use_interestingness_flag == true. We also will make sure to turn the flag back off in my_orderby_filter, as it’s our last filter to run during each query. It’s just like putting the seat back down after using a unisex bathroom.³

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

add_filter('posts_join','my_join_filter');
function my_join_filter($arg) {
	global $use_interestingness_flag;
	if ($use_interestingness_flag)
		$arg .= " natural join wp_interestingness ";
	return $arg;
}
add_filter('posts_orderby','my_orderby_filter');
function my_orderby_filter($arg) {
	global $wpdb, $use_interestingness_flag;
	if ($use_interestingness_flag)
		$arg = str_replace("$wpdb->posts.post_date","wp_interestingness.interestingness",$arg);
	$use_interestingness_flag = false;
	return $arg;
}

This method has a great advantage as you can just set it up once and invoke it whenever you want, even together with other parameters, without any additional code. For example, you can try query_posts("monthnum=1&orderby=interestingness") or query_posts("cat=-529&orderby=interestingness").

Conclusion

Adding an external ordering source to your WordPress post queries can be relatively straightforward if you understand what query_posts does and take advantage of its hooks. This tutorial can also serve as the basis for many other patches to WP_Query, not just the orderby parameter. To better understand the way WordPress builds its MySQL queries and the many posts_* filters which you can take advantage of, go to the source: wp-includes/query.php. Finally, you can use the special parse_query hook and global variables as flags to only apply the filters when necessary.

Related posts:

1. Yet Another Related Posts Plugin 2.0
2. Markdown for WordPress and bbPress
3. Yet Another Related Posts Plugin

Related posts brought to you by Yet Another Related Posts Plugin.

Clicking on a version’s permalink will let you download the plugin. Subscribe now and be the first to find out when the upcoming version 2.1 is released!

I decided to semi-automate this RSS-producing process as well. As a plugin developer using wordpress.org’s plugin hosting, I sync a local copy of the plugin to their server using SVN. I wrote a PHP script to get the modification date information directly from the local files, parse the version log in the read me, and produce the RSS feed. If there’s an interest, perhaps I’ll release this code in the future.

Related posts:

1. Yet Another Related Posts Plugin 2.0
2. Yet Another Related Posts Plugin
3. Modifiying WordPress plugin activation behavior

Related posts brought to you by Yet Another Related Posts Plugin.

Note: Many of the considerations here are specific to Fulbright English Teaching Assistants (ETA’s) in Taiwan. If this exact grant doesn’t apply to you, you may be better off simply taking a look at the IRS’s guide for Fulbrighters and also the Tax Guide for U.S. Citizens and Resident Aliens Abroad. I am not a Certified Public Accountant, tax advisor, nor Enrolled Agent¹ so your mileage may vary. Consider yourself warned.

Leaving the States

First, make sure that any employers you’ve had so far this year know some permanent address of yours (your parents’, say) and will send your income statements to that address come next January. If they only have some temporary address of yours, try to see if you can change that record with your employers before you leave. Worst case, you won’t get one in the mail, and you’ll call them up when you start your taxes and have them send it to you then.

Your Taiwanese income

In terms of actually doing your taxes: there are a few things to note, most of which they will tell you during orientation or afterwards:

1. Your Fulbright payment will not exist in Taiwan for tax purposes—i.e., you do not pay Taiwan taxes—but they will count toward US taxes.
2. The ETA-ship payments, according to the IRS’s own guidelines count as wages, not as scholarships, for tax purposes as, after all, they’re paying you to teach.
3. You will not, however, receive a W-2 form for your “wages”—instead you’ll get a nice letter from the Foundation (with your income in US$) which you can use as proof of those wages.

All of the above are pretty straightforward. The bottom line is, you pay federal taxes just as if the job were in the US. The only major difference is that approximate payments will not be withheld from each paycheck like it would be in the US.

Filing your federal taxes

The fact that you’re filing from abroad, however, adds a few other issues:

1. Whenever you file from abroad, you get an automatic two month extension on filing. While there’s no penalty to do this and file by June 15th, if it turns out that you do owe taxes, those taxes will still have interest accruing since April 15th. So it pays to just figure it out earlier rather than later.
2. If you end up being out of the US for more than 330 days, as some ETA’s may (depending on their itineraries, or if they decide to stay in Taiwan afterwards), there’s an option to take a Foreign Earned Income Exclusion (IRS Form 2555), which lowers your tax liability in the US (and thus, lowers your taxes). It’s a bit complicated, however, so even if this option applies to you, if you’re like me and enjoy doing your taxes, you can calculate your taxes both ways: with and without Form 2555. My personal experience was that, as I was already filing for certain educational credits (Lifetime Learning), it didn’t matter whether I used it or not, so I didn’t.

State and local taxes

Finally, there’s the issue of state and local taxes. The bottom line is that you pay state and local taxes only for wages that were made in those states. The way this is done in most states is by filing a non-resident/partial-year-resident form which makes you calculate your total adjusted income and also your your adjusted income in that municipality, and charges you the appropriate tax based on your income in that place. As your Taiwan wages weren’t in any US state, they won’t count toward any state or local taxes.

Help is just a phone call away

If you get confused along the way, there’s always the option of calling the IRS. The IRS has a 1-800 number for individual taxpayers (1-800-829-1040), and 1-800 calls are free from Skype.

Related posts:

1. Obama for Taiwan 2008
2. Survival Tips for Visiting Taiwan
3. Family in Taiwan

Related posts brought to you by Yet Another Related Posts Plugin.

Verdict: suitcase 18kg, guitar 6kg. I think I’ll make one more box to send at the post office tomorrow morning.

I feel like a caveman. THAT IS ALL.

No related posts.

Related posts brought to you by Yet Another Related Posts Plugin.

As an added bonus, I set this recipe to Sufjan Stevens’ Illinoise. I was just in a Chicago-missing mood and listening to it while cooking, and it seemed to work so well.

Time: 45 minutes (mostly waiting, though)
2 tablespoons extra virgin olive oil
1 medium onion, chopped
2 cloves garlic, chopped
Salt and pepper
1 1/2 cups (400cc) chicken stock (I used a bouillon cube—雞湯塊)
1 medium head of broccoli, just the flowers, in small chunks (maybe 3/4-1 cup)
1 cup (250cc) short grain white rice
1/2 cup (130cc) chopped parsley, optional

1. Track 1: “Concerning the UFO Sighting Near Highland, Illinois.” Put oil in a pan on medium heat. Add the garlic, onion, and a pinch of salt and stir occasionally until the onion is translucent or until you hear the piano riff on track 3, “Come On! Feel the Illinoise!” In the down time, you can make sure your chicken broth is heated up in a pot.
   
2. Track 3: “Come On! Feel the Illinoise!” Add rice to the onion pan and stir occasionally until they get clear and start to brown, sometime during the second half of track 3, “Come On! Feel the Illinoise! Pt. II: Carl Sandburg Visits Me In a Dream.” Throw the broccolli in the broth to let cook for the last minute of “Carl Sandburg.”
   
3. Track 4: “John Wayne Gacy, Jr.” Add the stock/broccolli to the rice/onion pan. Heat to a boil and then let cook for the rest of the track. Stir occasionally. Compare yourself to a serial killer as you watch the bubbles.
   
4. Track 5: “Jacksonville.” Cover and cook until the end of track 9, “Chicago.”
   
5. Track 10: “Casimir Pulaski Day.” Enjoy my favorite song on the CD. Turn heat off and let sit, uncover, stir gently, cover again, and let sit on the burner until track 15, “The Predatory Wasp of the Palisades Is Out to Get Us.” Optionally mix in chopped parsley for additional green. Serve.

Happy St. Patrick’s Day!

Related posts:

1. Patricks Nortons on Tekzillaz

Related posts brought to you by Yet Another Related Posts Plugin.

Last.fm offers a number of Flash-based widgets you can add to your website. Unfortunately, this doesn’t give you much flexibility and, of course, requires Flash. But you, dear friend, have a site written in PHP, and the rankings are just XML files. There is a better way.

Looking around on the web, there are some good instructions and recommendations for using PHP 5’s object-oriented XML support. But, as we know, not everyone is using PHP 5. Here’s what I did on my PHP install, which includes the DOM/XML and DOM/XSLT extensions.¹

Write your XSL Transformation

The first step is to write your XSL Transformation, or XSLT, a special XML “program” which takes an XML file and reformats it into another XML file. Remember when you learned in Algebra class what a function was? An XSLT defines a function from XML to XML. In our case, we need to take a special proprietary XML file like the this one for my weekly top artists and return some solid XHTML.

Let’s take a look at the XSLT I used: (it helps to take a look at the original XML file at the same time.)

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="weeklyartistchart">
<ol>
<xsl:apply-templates select="artist[position() &lt; 6]"/>
</ol>
</xsl:template>
<xsl:template match="artist">
<li><a><xsl:attribute name="href"><xsl:value-of select="./url"/></xsl:attribute><xsl:value-of select="./name"/></a><span><xsl:value-of select="./artist"/></span>: <xsl:value-of select="./playcount"/></li>
</xsl:template>
</xsl:stylesheet>

The full spec description will give you all the juicy details, but you really only need a few basic details (or you can just steal my code). First, we note the <xsl:template match="weeklyartistchart"> and <xsl:template match="artist"> items. Each of these code blocks describe what to do to each <weeklyartistchart> and <artist> nodes, respectively, in the input XML. In the code above, when a <weeklyartistchart> is found, an ordered list is opened and the artist template is applied to the first five (position() < 6) <artist> nodes. In the artist template (<xsl:template match="artist">), the script takes each <artist> and prints a list item with the name of the artist, with a link to the url given in the original <artist>’s <url> subnode.

Process the XML with your XSLT

Once your XSLT is written, save it to a file, like last.fm.xml. Now we’ll use the DOM/XSLT extension and apply this XSLT file to the live weekly artist chart XML file from last.fm. Here’s the code I used:

$chartxml = domxml_open_file("…/weeklyartistchart.xml");
$xslt = domxml_xslt_stylesheet_file("last.fm.xsl");
$charthtml = $xslt->process($chartxml);
echo $charthtml->dump_mem();

The code is pretty self explanatory—just four lines: 1. open the remote XML file using domxml_open_file, 2. open the stylesheet (XSL transformation), 3. apply the stylesheet to the remote XML file, and 4. echo the output.

That’s it! You can see the results here on my music page.

Related posts:

1. Updating your zenphoto theme for zenphoto 1.1
2. Buklavu
3. Yet Another Related Posts Plugin

Related posts brought to you by Yet Another Related Posts Plugin.

1. Don’t flush the toilet paper in the toilets. For this reason, almost every bathroom here has a trash basket. Also, keep some tissue paper on you as most public restrooms do not provide paper.

2. Don’t drink the tap water. I don’t know what happens if you do, as I haven’t tried, but I’m not planning on it. The good news is that most public buildings and many other establishments have drinking water machines. Bring a good water bottle.¹

3. If you’re visiting northern Taiwan in the winter, bring some raingear. Sure, you’ll probably buy a few umbrellas (I’m on number three), but rain coats are pretty useful too. You can also be really Taiwanese by wearing your raincoat backwards.²

4. Taiwan is big on recycling. Luckily, though, in most places there’s just a trash can (垃圾桶, pronounced lèsètǒng as opposed to the Mainland lājītǒng) and a recycling bin… in general, most paper and plastic containers that don’t have food waste can be recycled. Plastic bags and wrapping cannot be.

5. Keep all your receipts. Taiwan has a receipt lottery (formally the Uniform-Invoice Prize). While you can claim it as a foreign visitor with a valid visa, as the winning numbers are released about a couple months after each time period ends, you’ll probably just want to give the receipts to me. ^^
   

6. Oh, and cold tea is sweetened by default. This freaked me out when I first tried some. Just a warning.

Of course, if you’re not planning to visit me yet but have time between late-January and mid-February (my Chinese New Year break), let me know. Let’s talk.

Related posts:

1. Affirmative action, Taiwan style
2. Fire drill!
3. I am not a Nazi

Related posts brought to you by Yet Another Related Posts Plugin.

Since then, though, I (along with many others) have been slightly disappointed by the lack of development in the promising project, without having the time or energy to pitch in myself. Such is life. But now the wait is over: Zenphoto 1.1 is out.

Zenphoto 1.1, I believe, does a good job balancing this tradition of simplicity with some popular new features. Highlights include (there are many) tagging, subalbums, chronological archives, RSS feeds, EXIF support, Google Maps, search, and preliminary video support. Exciting stuff.

As I maintain my own theme, though, some of these new features of course require me to update my theme. Below is my rough guide to editing your theme to take maximum advantage of zenphoto 1.1.

First things first

Between the core components moving from /zen to /zp-core and the addition of subalbums, your old .htaccess will no longer be valid. Make sure to copy over the new .htaccess (in the zenphoto 1.1 zip file, though probably invisible in your filesystem) with necessary updates for your setup, or else none of your images will show up. Ha!

Search and Archives

The first thing you’ll notice if you check out the default theme is the search and archive pages… the easy way to implement these, I think, is to copy over the search.php and archives.php pages and then make the necessary organizational changes. This is of course easier said than done, but everyone’s custom theme exists for different reasons.

To implement search, you first have to add the search box to the index page:

if (getOption('Allow_search')) {  printSearchForm(); }

The default theme has this right above the gallery title, but I put it at the bottom of my main div.

Subalbums

Subalbums are an exciting new feature for organization buffs, but it does require some quick changes. First of all, the subalbum-path breadcrumb must be added to album.php and image.php, right before the current album/image name. Use the three parameters to change the delimiters.

printParentBreadcrumb($before,$between,$after);

By default, subalbums are listed at the top of an album’s page, so we have a new while(next_album()) loop there. The default theme’s additional loop¹ is:

<?php while (next_album()): ?>
    <a href="<?php echo getAlbumLinkURL();?>">
    <?php printAlbumThumbImage(getAlbumTitle()); ?></a>
    <a href="<?php echo getAlbumLinkURL();?>">
    <?php printAlbumTitle(); ?></a>
    <?php printAlbumDate(""); ?>
    <?php printAlbumDesc(); ?>
<?php endwhile; ?>

Tag Support

Simply add this line to the bottom of album.php and image.php:

printTags(true, 'Tags: ');

RSS Support

To enable RSS support, simply put the printRSSHeaderLink() in your headers. I used these three lines:

printRSSHeaderLink('Gallery','RSS title');
printRSSHeaderLink('Album','RSS title');
printRSSHeaderLink('Image','RSS title');

Now your RSS feeds are added as links in your header, and will be recognized automagically by a smart browser. You can also add an explicit link:

printRSSLink('Gallery','','RSS', ' | ');

Maps and EXIF

While I haven’t implemented these myself in my theme,² these look fairly simple to add to a theme. The key PHP code to include are:

  if (getImageEXIFData()) {
    printImageMetadata('', false); 
  } 

and

printImageMap();

There’s more

There’s of course more advanced stuff that might be of interest to other theme designers. The place to start is probably normalizeColumns().

Feel free to check out my final product, the updated photos section.

Related posts:

1. Exploring Nanao, part 2: hot springs, waterfall, and beach
2. Exploring Nanao, part 1
3. Field trip: Guang-xing Farm

Related posts brought to you by Yet Another Related Posts Plugin.