Hi, and welcome to the second edition of the Coding For E2 guidebook. I'm your host, kthejoker, star of such coding projects as The Costume Shop and that annoying thing where guest users "like" cocaine abuse. Today we'll be talking about some of the specific E2 syntax and code structures that keep this piece of sh fabulous family friendly website of awesomeness afloat.
As stated in the initial article, we'll be using everybody's favorite ubiquitous nodelet Epicenter as our review code. You can view its code by visiting the node directly and appending "&displaytype=viewcode" to the URL or using the "viewcode" link within the Everything Developer nodelet. Let's look at the first 4 lines:
1: {borgcheck}[%
2:
3: my $isGuest = $$USER{user_id} == $HTMLVARS{guest_user};
4: my $isRoot = htmlcode('isAdmin');
Right away, we've got some great examples of E2-specific syntax:
- {borgcheck}
E2 uses brackets to invoke all code on the site. It uses [% to invoke pure Perl, and [{ as a short of syntactic sugar for htmlcodes. An htmlcode is the equivalent of E2 (and any eCore implementation)'s library functions. That is, it accepts arguments and returns a value. Most commonly it returns HTML (hence the name) but they sometimes return values that are then used for logic purposes. In simplified form, the call is
{htmlcodeName:arg1,arg2,arg3...}
In this case, there's no args, so it's just {borgCheck}, which checks to see if the USER is borged or not. (Advanced Coding Tip: edev members can view htmlcode code by visiting the htmlcode. Check out borgcheck and see if you can figure out how it works.)
- my $isGuest = $$USER{user_id} == $HTMLVARS{guest_user};
From the original primer, can you tell what this is doing? It's assigning the value of whether or not $$USER{user_id} (value of the user_id key of the $USER hash) is equal ("==", remember?) to $HTMLVARS{guest_user} (guest_user key, $HTMLVARS hash) to the variable $isGuest. Both $USER and $HTMLVARS are global supervariables for E2: $USER is the actual user visiting the page (i.e. you!), and $HTMLVARS is a lookup table of common E2 data elements (such as the common node_ids for things like Guest User and the Findings: page). So if the USER's user_id is guest_user's user_id, then $isGuest is set to 1, and we can do things like "if ($isGuest) {don't show them the vote buttons}". Other supervariables include $NODE (the node you're viewing), $VARS (your personal vars, such as your user preferences and ekw themes), and $DB (the database handle.)
- my $isRoot = htmlcode('isAdmin');
This is the other form of an htmlcode call, actually invoking the htmlcode() function found in E2's custom HTML perl module. The syntax is htmlcode('htmlcodeName','arg1,arg2,arg3'). (Advanced Coding Tip: Sometimes this syntax can be troublesome, especially if your argument values contain quotes, apostrophes, or commas - the argument list is just passed as a bare string and is exploded within the htmlcode() function, so it's in your best interest to sanitize data before invoking htmlcodes using the data as an argument.)
Let's skip ahead now to line 12:
12: $loginStr = htmlcode('minilogin')."<p align='center'>".linkNode(getNode('Everything2 Help','e2node'), 'Everything2 Help')."</p>";
I've highlighted the relvant part of this line. This line contains two of the most important node functions E2 has: linkNode and getNode. getNode, as you can see, will return a node by using a title and nodetype. If there are more than one result, it returns an array of the matching nodes. linkNode takes the form of linkNode(NODE, linkText, Optional Hash of Parameters) and then generates a link from this information. What's nice about linkNode is it can also accept a node_id instead of a NODE reference for its first argument as well as a null second argument, so you can just return a node_id from the database and use linkNode to do the extra fetching of the title - so linkNode(220) will return a link to nate without having to do any more work. It's also nice because if you provide it a node, it links directly to it, whereas using linkNodeTitle or brackets doesn't guarantee there's not a similarly titled node out there that might conflict with your code. In this case, linking directly to Everything2 Help ensures nobody subverts that link.
For one more check of E2 syntax, let's head to line 102:
102: my $link = $DB->sqlSelect('to_node', 'links', 'from_node='.$$NODE{node_id}. ' and linktype='.getNode( 'coollink', 'linktype' )->{node_id}.' limit 1');
Here we have one of our many database helper functions, sqlSelect. There is a convenient list and explanation of these (and many other node functions, such as the previously mentioned getNode) at
Everything::Nodebase Functions
Which is pretty much required reading for E2 coders. But the key here is that the database functions link into the $DB supervariable to return results from the database. In this case, sqlSelect always returns either a variable if you're only looking for one field or an array for multiple fields based on a single record's worth of criteria. So it's useful when you're looking for counts, averages, or one specific database entry (such as a person's vote on a given writeup.) Here it's being used to pull the ed cool link for the node you're on.
So now you've had a bit of a primer in E2 syntax. There are of course over a hundred htmlcodes in use around the site, and plenty of module functions, too. For the most part, though, you just need to know how to get nodes and node info from the database and then do something with it in the code, be it displaying or computation or logic testing.
In our third installment, we'll take a look at the many different nodetypes of E2 and how they are used to govern each request from talking in the catbox to posting a writeup to joining a usergroup. We'll also trade pictures of our cats!