Tags That Don’t Work Very Well

Dictionary Lists

You could use a dictionary list like so:

<dl>
    <dt>Color</dt>
    <dd>Red</dd>
    <dt>Shape</dt>
    <dd>Square</dd>
</dl>

Semantically, this kind of works out. It has key and value tags, dt and dd. But the problem comes with formatting. What if you want to put a border around a key value pair? Well, you can’t. One solution is to wrap each key-value pair in its own dl tag, but that seems like a lot of work and then you lose out on the whole list wrapper, so you have to wrap the whole thing in a div or something depending on your formatting requirements.

This is not to say that dictionary lists are bad, they are perfect for things that closely resemble actual dictionary lists, but they are not a very good general key-value pair container because of limited formatting options.

Unordered Lists

Unordered lists are very flexible and can wisely be used for all kinds of lists. The other day I saw them used as a container for key-value pairs like this:

<ul>
    <li>Color <span class="Value">Red</span></li>
    <li>Shape <span class="Value">Square</span></li>
</ul>

In many cases this will work fine. It has the benefit over a dictionary list that both the key and value are contained within one element. It has the downside that the Value span has to be formatted to undo any formatting you’ve given the li (the key). This could be altered by adding a Key span, but at that point you may as well just use a bunch of divs. This doesn’t give you very good CSS free presentation and completely loses the semantics of the data. The point of HTML is that if there’s no style things still end up looking fairly decent and that at the very least, the HTML can accurately represent the data relationships.

The Winner

Tables

We’ve been so conditioned against tables and rightly so. People have abused tables in the past to format their pages to the point where you can’t tell what’s going on. But remember the rule, “Tables should be used for tabular data.” A list of key-value pairs is an excellent example of tabular data, but I think people don’t think to use tables at first because the tabular data in this case only has two columns. People start to think of tables for things with three or more columns. Here’s the markup.

<table>
    <tr>
        <th>Color</th>
        <td>Red</td>
    </tr>
    <tr>
        <th>Shape</th>
        <td>Square</td>
    </tr>
</table>

This fixes all the problems. Each key value pair is enclosed in a tr element. The key is enclosed in a th and the value is enclosed in a td. The default formatting is going to be perfect.

Furthermore, tables offer so much more extensibility. If you need a header row, break out the thead and tbody elements. If you need a summary row at the bottom, add another tbody element. It’s ultimately extendable with no classes.

Of course, that doesn’t mean it’s the solution for everything. If what you have is a dictionary list, then of course the dictionary list tags are going to work better. But for general key-value pairs, and the ways we generally think of formatting key-value pairs this is way better.

It might be time to get back in touch with tables if you’ve stopped thinking about them. Once you drop the idea of tables being used for page formatting and adopt the idea of using them just for small blocks of data you can really start to see how great they are.

The CSS for tables is a little more complex, so take some time to start understanding that. I’ll give you a hint, though. Do yourself a favor and use the border-collapse property. It takes a lot of the fuss and mess out of formatting tables:

table
{
    border-collapse: collapse;
}

Difficult Situations

I just thought I should mention here that I have run into one situation that isn’t covered very well by any existing HTML elements and in its nature is just difficult. This is the case where you have individual key-value pairs that you want “arranged” in an some custom manner. For instance you want the key on top with a border on the bottom and the value beneath that. Then you want those elements to be lined up horizontally:

Color     Shape
--------  --------
Red       Square

Using more radical CSS dictionary lists can be made to perform this way although it’s probably better handled by turning the table suggestion above on its side and using a table with two rows, a header row and a data row depending on how you want it formatted.

<table>
    <thead>
        <tr>
            <th>Color</th>
            <th>Shape</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Red</td>
            <td>Square</td>
        </tr>
    </tbody>
</table>

That’s more HTML than absolutely necessary, the thead and tbody can be left out, but it still feel like a lot of HTML for something semantically simple. But at this point it’s going to take either a lot of HTML (tables) or a lot of CSS (dictionary lists) to make this particular scenario work. If you want it to work without CSS, you really have no choice but tables.

The issue with this concept is that it doesn’t allow for very long values or very many key-value pairs horizontally and the whole scenario is only appropriate when you know in advance the range and quantity of values to expect.

For instance, if all your pages have a format involving a header element, a body element, and a footer element, then you have to duplicate that HTML in single.php, page.php, 404.php, etc. Then if you ever change it you have to edit every one of those files just to make the same changes over and over again. You’re probably going to forget to do it in some files and you’re going to do it wrong in others.

Wouldn’t it be great if you could just call a function that would establish this pattern for you in all files? Then if you needed to change it, you would only have to change it in one place and all your site’s pages would be effected. But what if you need to tweak the template slightly for different pages? This is exactly why object oriented design is important.

So you have a base class that draws the usual page structure and then provide override-able and abstract methods so that a new class can be created if you need to customize. It works perfectly because it gives you maximum code reuse and there’s no duplication.

However, it does make the theme very code heavy. There’s not a ton of code, but enough that would intimidate most people. Plus, if you don’t have a lot of experience with object oriented design getting the extensibility right is going to be a bit difficult.

But that’s kind of my point for this post. It’s not necessarily that you need to do this, because obviously themes can be made without it. But it’s the fact that object oriented design is important to web applications and even blogs too. If you do a lot of PHP coding but aren’t yet familiar with the concepts behind object oriented programming, then learning more about that will really be a benefit to you.

This rule is used mostly for a couple of reasons, and almost never to actually hide overflowing content. The first is to make sure that and element containing floating elements will clear itself. The other is to make sure that an element next to a float doesn’t wrap under that float.

If in your CSS file you clearly comment every time you use overflow: hidden you will be able to read your CSS much faster when you come back to it later. You will also almost certainly find all the unnecessary overflow: hidden; rules you have and it will help you get a much better overall understanding of your layout philosophy.

add_filter('the_content', 'MyPluginClass::FilterTheContent');

This is pretty handy, but sometimes when you’re writing a WordPress theme you want to allow plugins to add content, not just filter the usual content. Using apply_filters makes this pretty easy because you can call apply filters with custom “tags” and it will just work. For instance in your theme you can put:

<?php

    $theMessage = apply_filters('CustomThemeMessage', '' /* default value: empty string */);

    if (!empty($theMessage))
    {
        echo '<div class="Message">', $theMessage, '</div>';
    }

?>

If nobody ever filters on the tag ‘CustomThemeMessage’ it’s fine, your theme won’t break or anything. But plugins that know this tag is available can use it:

add_filter('CustomThemeMessage', 'MyPluginClass::FilterTheContent');

When you’re developing themes and plugins in tandem, this is incredibly useful and robust. It’s also not as risky as filtering a tag like ‘the_content’ where a mistake can really mess up your site. It will also be more performant when you only need the custom content on one or a few of the pages on your site.

$string = format_gmt_time_for_time_zone(
    'l, F jS g:ia', 
    $myGMTTimestamp,
    'America/Los Angeles');

or even better, using and object oriented approach:

$string = $date->Format(
    'l, F jS g:ia', 
    'America/Los Angeles');

It’s important because it’s kind of a “best practice” to store dates in the database in GMT (or really UTC) format and then translate them as necessary. Then I want someone in New York to see times in their time zone and also someone in Seattle. It would also help if WordPress had a per user time zone.

I know that PHP 6 is doing some enhanced date stuff, so hopefully that will include this simple functionality. But right now, both WordPress and PHP don’t seem to imaging a case where someone wants to print out a time for a timezone they’re not in.

What I ended up doing was this:

$oldTimeZone = date_default_timezone_get();

date_default_timezone_set($requestedTimeZone));
        
$convertedString = date($formatString, $gmtTimestamp);
        
date_default_timezone_set($oldTimeZone);
        
return $convertedString;

It works, but it’s fairly clunky. From my experience at Microsoft I know sometimes when there’s a whole category of things that needs improving, it can be hard to find someone to take that on. What has to happen is a person needs to say, “I’m going to take on times and dates and make the API better.” But either people aren’t interesting or people are too afraid to suggest such a drastic move. Furthermore, the people who wrote the original code will often be offended that someone would suggest it could be better. They will point to something like my code above an say that’s good enough. It isn’t.

I’m actually considering getting involved with WordPress on this, however, I am honestly scared that they will not be into it. I’d also like to add the per user time zone, but I sense something like that would be controversial.

Tonight was the first time that I needed to write some code for a business that would send email to customers, or at least email that needed to be reliable and feature rich. I looked at the documentation for the PHP mail function and after a lot of reading realized it was not going to work. If I wanted to use HTML, that involved a lot of uncertainty, if I wanted to use UTF-8, that involved a lot of uncertainty. There were a lot of unknowns but one thing that was quickly becoming a known was that I was not going to fix this problem.

I knew I could send simple text emails with a URL to details if I had to, but before I did that, I wondered if someone else had solved my problem since what I wanted was reasonable and obvious. To my great surprise a few people had. It came down to two tools, Swift Mailer and PHP Mailer.

After doing some Google searches and research, it became clear that Swift Mailer was probably going to be better for me. And the reasons why are big lessons for PHP Mailer. Swift Mailer had a nice simple website, they had one product, and they had a download link on the front page. Right off the bat, it was looking simple. On the other hand PHP Mailer has four products which I would have to investigate to find out which one was right for me. Their home page is a mess that for some reason seems to focus on ads for other people’s products along with tons of text about who knows what. It would take me hours just to parse the homepage.

But, what took it over the edge was that Swift Mailer has a beautiful object oriented design to their API and they talk about that being a goal, they have full easy to understand documentation, installation is a breeze, as it should be, all while offering an incredibly feature rich product. Swift Mailer wins by a mile.

Was it as easy as it looked? Well, in about an hour I had built a WordPress plugin that would include Swift Mailer’s functionality in my blog on demand. I had added code to another plugin to enable Swift Mailer at the right time and send an email from one Gmail account to another using Gmail’s smtp server with a secure connection over SSL.

One hour.

I literally copied the code over and changed the important bits. I had one issue where Gmail didn’t like the port the Swift Mailer docs used for SSL, but the Gmail docs listed the alternative port and things worked perfectly.

Furthermore, there are tons of features of Swift Mailer that will actually inspire me to do more with email.

Kudos to the Swift Mailer team, you’ve really created a great product and you are a poster project for open source. Thank you!

To start off, I think part of the reason this isn’t explained in a more upfront manner is because the writers of the documentation don’t really think it’s a valid question. Yes, if you’re where I was this morning that sounds ridiculous, and it is, but now I can understand their point of view.

The first rule of RewriteRule is:

RewriteRule never “changes” the URL in the user’s browser window.

Right now you’re probably saying no way, you’ve seen it happen, so you know it must be happening somehow. The end result is happening, you are correct, but it’s not happening the way you might think. RewriteRule does not say to the browser, “Please change the URL in the address bar to this.” Instead, sometimes RewriteRule says, “Oh, the page you’re looking for doesn’t exist, try this one instead.” This is called a redirection.

Rewrite versus Redirection

This is a very important distinction to most of us, but it is sort of glossed over in the Apache documentation because its writers forgot how revolutionarily important it is.

A rewrite is when Apache says, “OK, I am going to handle your request, and internally I am going to change the URL to this other URL. You are never going to see that other URL, but that is the URL that is going to be processed. You will continue to see whatever it is you typed in your browser’s address bar.”

A redirection is when Apache says, “Oh, I recognize that I can’t help you with this request, I suggest you ask for this URL instead.” After it says this, it’s done with you, the request is completely finished, and it has forgotten you ever existed. Your browser, however, receives this information and says, “Well if they suggest a different URL, I guess I’ll do my user a favor and request that URL next. Oh, and so my user knows what’s going on I’ll change the URL in the address bar.” Next your browser makes a whole separate request with the new URL. The brand new request is received by the web server and processed. The web server has no knowledge that these two requests are in any way related, and the web server certainly isn’t the one who changed the URL in the address bar of your browser.

This is a big deal! It’s totally lost on the writers of the Apache documentation. Because now you know you can effectively do the two things you want to do: change the URL internally or change the URL externally (or both, but in two steps.)

The Code

So what’s the difference between a rewrite and a redirect? One letter: R.

Rewrite

RewriteRule ^/cars/acura /cars/honda

Users who request the URL /cars/acura will still see /cars/acura in their address bar but they’ll see the content as if they had requested /cars/honda. (This is just an example and would lead to duplicate content warnings in Google because two different pages would have the same content.)

A better example:

RewriteRule ^/cars/(.*) /cars.php?make=$1 [QSA]

This will internally rewrite requests to /cars/acura to /cars.php?make=acura so you can pretty up your URL structure. It will handle those requests at the same time. The QSA stands for “Query String Append” and means that if the URL came in with additional query string info that will also be appended, not lost.

Redirect

RewriteRule ^/cars/acura /cars/honda [R]

This is the exact same example as the first example above except for the [R]. The R says, do a redirect which means once Apache is done processing the RewriteRule directives, it will stop processing the request and send the redirect message back to the browser as we discussed at the beginning of this post. This means the browser will most likely change the URL in the address bar and make a new request. There will be two web server requests, which are totally unrelated as far as the web server is concerned.

I should say, for the record, that normally the above code would be written as:

RewriteRule ^/cars/acura /cars/honda [R=301,L]

By default R returns code 302, meaning “moved temporarily” which isn’t often what people like you and me want. We want 301, meaning “moved permanentaly” which will also direct search engines to update their URL. The L means if a URL has matched this directive, do the redirect immediately and don’t process any more directives. Most of the time we don’t have complex sets of directives that all need to be processed, so just get out early to improve performance.

More on Redirects

I won’t go into detail here, but there are more things than just [R] that will force a redirect, for instance if you’ve given a substitution URL on another domain. Read the docs for more of those types of situations.

Conclusion

Hopefully this has been as helpful to you as finally figuring this out has been to me. It feels so good to finally have a good grasp on this topic.

*
{
    margin: 0px;    /* I include this just because I always do it and for this */
    padding: 0px;   /* example it will ensure the bottom is truly the bottom. */
}

html
{
    height: 100%;
}

body
{
    min-height: 100%;
}

I’m not entirely sure why the html element has to have a height of 100%, but it does. What’s interesting is if you apply a background to the html element it will fill the whole viewport, maybe the extra space is considered padding or something.

Some other examples on the web for other things will show the body having a height of 100% instead of min-height. This will put any absolutely position elements on the bottom at the bottom of the viewport instead of the bottom of the body.

add_action('init', 'MyPlugin::Init');

class MyPlugin
{
    public static function Init()
    {
        // Put Some Code Here
    }
}

Pretty easy. What I really like about this is that the class name acts as a namespace, so I can use the simple function name Init instead of naming my function something annoying like myplugin_init.

I use this pattern all the time to initialize an instance of the class so that it can be used elsewhere, such as in a theme:

add_action('init', 'MyPlugin::Init');

class MyPlugin
{
    private $userName = null;

    public static function Init()
    {
        global $myPlugin;

        $myPlugin = new MyPlugin();

        // The following line would probably go into a 
        // constructor method and get the real current
        // user name.

        $myPlugin->userName = 'bob';
    }

    pubic function GetUserName()
    {
        return $this->userName;
    }
}

Then any other non-plugin code, like a theme for instance, can detect the presence of the plugin and use it.

global $myPlugin;

if (isset($myPlugin))
{
    echo 'MyPlugin is installed, ', $myPlugin->GetUserName();
}

Happy Coding!

$my_favorite_variable = 5;

function add_numbers($first_number, $second_number)
{
    return $first_number + $second_number;
}

$answer = add_numbers($my_favorite_variable, 1);

But this became tiresome. The thing is, the underscore character is harder to type and using all lowercase really makes the code blur together at a glance. Also, it’s harder to tell the difference between variables and function names. After writing code at Microsoft for many years, I know that camel case is the way to go. Even Apple uses camel case. Modern C programming uses camel case. The PHP inventors made a mistake when using all those underscores.

Using camel case and adding in classes, the code becomes so much cleaner:

$myFavoriteVariable = 5;

class Calculator
{
    public static function Add($firstNumber, $secondNumber)
    {
        return $firstNumber + $secondNumber;
    }
}

$answer = Calculator::Add($myFavoriteVariable, 1);

Doesn’t that look better? We’re at this point in history where we’ve pretty much figured out that for all languages camel case it the easiest to read. Start variables with lowercase, classes and methods with uppercase and it looks so nice.

Having said that, every time I start to work on something I haven’t touched in a while there’s a flurry of code refactoring, but it feels so good to get that done. And it’s so much easier to read.

One of the many things I’ve found useful over the past couple of days has been the WordPress function do_action. I have a base theme that I repurpose for all of my websites. I really try to keep it flexible enough to do just about anything. Sometimes that can be difficult, but do_action really helps. You can place do_action calls throughout your theme files in handy places and then customize your theme outside of your standard theme files using the add_action function. If you don’t customize, everything works fine, but if you do, you can do it in a different file so you don’t have to modify the core theme files.

Obviously, this paradigm is used throughout WordPress in many different ways, and I have been a “consumer” of it many times. But it wasn’t until recently that I realized how much this could help me with my many different themes and save so much time. Or at least it will, after this exhausting week is over!

At the start of the process I had a PHP function that I would call to import some data. The problem is, that process would take longer than 30 seconds after which it would time out. A while ago, I changed the function to stop itself after 20 seconds. The result was an administrative web page where you had to hit an “update” button multiple times, waiting for 20 seconds each time.

My dream of dreams was to have this function work via AJAX instead and just update one record, return with status indicating how much work was left and then do another. I did this with the JQuery.post method. This is using the WordPress admin AJAX functionality.

cancelProcess = false;

function ImportOneRecord()
{

    jQuery.post(
        '/wp-admin/admin-ajax.php', 
        {
            'action': 'ImportOneRecord'
        },
        function (data)
        {
            if (data.succeeded 
                && (data.recordsLeftToImport > 0) 
                && !cancelProcess)
            {
                // Update Status
                jQuery('#statusBox').html(data.status);

                // Do It Again
                ImportOneRecord();
            }
        },
        'json');

}

My initial concern was one of stack overflows, but then I realized that the asynchronous nature of AJAX takes care of that. When this function runs, it doesn’t block. It sends the AJAX request that lives out in the ether and when that request receives a response, it runs my event handler. When that event handler runs it doesn’t block either, meaning it can be released. But when it did run, it created another AJAX request that also lives in the ether. Nothing is hanging onto it.

This function made it through thousands of records and I’m not sure how big the JavaScript stack is, but it didn’t overflow. I think it’s because like I thought, that’s not an issue here. There is no stack build up. This is just a very very complex loop… I think.]]> http://designoplasty.com/2009/09/18/jquery-post-recursion-or-not/feed/ 0 http://designoplasty.com/2009/09/14/wordpress-plugins-and-ajax/?utm_source=rss&utm_medium=rss&utm_campaign=wordpress-plugins-and-ajax http://designoplasty.com/2009/09/14/wordpress-plugins-and-ajax/#comments Tue, 15 Sep 2009 04:36:55 +0000 Matt http://designoplasty.com/?p=967 The last couple of days I’ve been doing a ton of AJAX programming on some WordPress plugins. Wordpress actually does have one very handy AJAX feature that makes using AJAX just a little easier. I also use jQuery because it’s really nice for a lot of things including AJAX work.

AJAX is a great technology, and while I know what I’m doing, sometimes even I am amazed at how difficult it is. You’ve got HTML, Javascript, PHP, and usually database tables to get right. If any one of those isn’t working it won’t work.

If you don’t already have good debugging skills, I wouldn’t even try it. I very much try to integrate my debugging in with my development to save time. For instance, I have a function that checks to make sure a database call went OK. If not it sends an ajax response with the query and the error string. My calls to AJAX are always prepared to receive and display that error. Even my CSS for the page even handles displaying the returned error string in the most clear way possible. This is code I can use again and again in all my plugins, and if I didn’t reuse it I would never get anything done..

Now that I’m getting it down, it’s so nice. I love AJAX. But the more I work on the web the more I see we need a replacement for JavaScript. I mean most of the language is fine, but it needs to be a real language with the standard object oriented features implemented in the standard way: class, public, private, protected, property getters and setters, etc. The prototype keyword needs to be completely removed from the language. JavaScript and PHP need to align such that AJAX is a natural part of both languages. It’s possible, but the web is a funny thing and its technologies have a heck of a time moving forward.

I didn’t get far. I realized what I needed was a thread-safe counter. Simply a function that spits out numbers one after the other, and absolutely positively guarantees it will not give out the same number more than once. I know how to do this many different ways using many different languages, but I wasn’t sure of the best way to do it using WordPress, PHP, and MySQL.

MySQL does have auto increment where if you add a row to a table it will make give a field a value that’s incremented. This is atomic, but I didn’t need a new row in a table, I just needed the number.

I figured I could store the number in a text file and have PHP use file write protections to do the locking I needed to make it atomic, but the performance would not be that great for such a simple task.

I thought I could create a simple table with the number in a row, and use MySQL table locking to accomplish this. For a while, I had settled on that plan, but something made me think there must be a better way.

I went about researching the MySQL update statement. It turns out that doing this is atomic.

UPDATE plugin_counters
    SET counter_value = counter_value + 1 
    WHERE counter_name = 'invoice_id';

But the problem is how to get that value before this happens again. Apparently you can just add one more expression to the WHERE clause.

UPDATE plugin_counters
    SET counter_value = counter_value + 1 
    WHERE counter_name = 'invoice_id'
        AND @value := counter_value;

This expression will always return true and will place the original value of counter_value into the MySQL variable @value.

I spent a good deal of time trying to verify that this is absolutely positively atomic and it seems to be. Even naysayers were accepting this to be atomic while pointing out that longer updates would not be atomic if the database crashed in the middle of the update. So to me, this means they’re saying as long as the database doesn’t crash, it’s atomic, which is good enough for me.

I just watched this video to see what was coming up in ECMAScript 5. What this video taught me is the JavaScript is junk and that design by committee always leads to bad solutions.

When looking at some of the ridiculous code examples in this video, I just couldn’t believe it. It is so difficult just to create an object with private typed variables. They aren’t doing anything to fix that, in fact they might be making it worse. Yes, they have technically made it possible, but they have practically made it impossible. Is it so bad to want to type:

object Point
{
    Int32 x;
    Int32 y;

    Point(Int32 x, Int32 y)
    {
        this.x = x;
        this.y = y;
    }
}

That is essentially JavaScript. Maybe it only works in “strict mode” I don’t care. But what they are doing makes the code for that look like complete garbage. All the things they’re whining about have already been solved, and years ago. Just use what already works! Stop reinventing the wheel as a square and telling me I just need to be on a really steep hill to use it.

I’m so tired of these crappy web programming languages and at this point I wish someone would just port C to be a scripting language. I have no idea how I would even begin such a process, but the problems with JavaScript are so bad for any good programmers, that I think someone needs to do something.