T (01) 234 5678 - F (01) 234 5678 - E bob@boztangle.com

It looks quite nice and clean, especially in a vertical format on a screen as the single letters all line up in nice columns. And it’s pretty obvious what the letters stand for if they stick to the obvious words: telephone, fax, mobile, email. But too often people try to be clever and end up creating confusion. Here are some examples.

P (09) 876 5432

P is meant to stand for “phone”. This is a real howler; it reminds me of the Simpsons episode that mentioned a horror movie called “P is for Psycho”. P is obviously not a natural abbreviation of “phone” or “psycho” because these words don’t sound as if they begin with P. And “phone” is already an abbreviation. For telephone. Which begins with T.

D (02) 468 1357

D stands for “direct”. In this case, there’s probably a T that gives the number of the company reception desk. But wait a minute. This is Bob’s business card, so when I see a T, I expect it to be Bob’s phone number. His direct phone number. The number of the reception desk is a secondary number, and we must face the fact that there’s no clear single-letter abbreviation for this.

C (021) 468 1357

C stands, of course, for “cellphone”. That’s “of course” only if you live in the USA or some other country where mobile phones are called cellphones. I think that M for mobile is more universal than C for cell, as well as being more descriptive. I’ll bet that most people who call their phone a cellphone don’t know why it’s called this.

DDI (02) 468 1357

This stands for Direct Dial In. You also sometimes see DID for Direct Inward Dial. This is pretty common in New Zealand — it’s a quaint reminder of a simpler time, when most companies had only a few incoming phone numbers and having a direct line was a big deal; of course this concept required its own special abbreviation. Nowadays I think we can just stick with T for telephone.

So here’s a handy guide to the single-letter abbreviations you can safely use for your English-language contact details.

T Telephone — the person’s phone number. This is the direct number if there is one, otherwise the general reception number.

M Mobile — the person’s mobile phone number.

F Fax — the person’s fax number. (Some people like to write “FAX” instead of “fax” for some reason, but I’m sure you’re not one of these people.)

E Email — the person’s email address.

W Web — typically the general company website. Of course you should leave off the http:// from the website. But then you knew that already.

Anything else is going to need more than just a single letter. For consistency in these cases, just spell everything out rather than have funky single-letter abbreviations for some details but not others.

Some of these contact details don’t really need any indicator at all: bob@boztangle.com is obviously an email address. Mobile phone numbers are often distinguishable by the number of digits, but this only works for people who are familiar with that country’s numbering plan. (Even then it doesn’t always work: Hong Kong has no area codes and uses eight digits for all phone numbers, fixed and mobile. Then again, in my experience nobody used fixed line phones in Hong Kong anyway.) Given that, if there’s only a fixed line or a mobile or both, and also maybe an email and a website, you can just give them unadorned:

(09) 234 5678 - ( 021) 234 5678 - bob@boztangle.com - www.boztangle.com

Now that’s clean and elegant. But more importantly, it’s clear. Adding “P” would just confuse the matter.

Share This

Unless otherwise indicated, all comments apply to Lotus Notes client version 6.5, though a lot of the comments apply to version 7.0 as well. Webmail comments apply to version 7.0.

Preferences: Looking for Preferences? There is a Preferences submenu under the File menu. It contains six menu items for different kinds of preferences (but none of them are to do with files). But there’s also another preferences command, in the Actions menu under the Tools submenu (note: not an action). So for example if you want to add a digital signature to all your sent mail, you set this in File/Preferences/User Preferences/Mail; but if you want to add a text signature, you go to Actions/Tools/Preferences/Mail/Signature. This is ridiculous.

New Folder: I wanted to create a new folder to file some emails. In the panel on the left hand of the window, there’s the standard Inbox, Drafts, Sent and so on, as well as a Folders icon that can be expanded to show all your folders. You’d think that the command to create a new folder would be obvious. You’d be wrong.

Right-click the Folders icon. Huh? I get a context menu with options like Italic and Underline, amongst others. (I select Italic just for fun. Nothing happens.) But no New Folder option.

Right-click the panel itself. Huh? I get a context menu with options like Document properties and even Forward. (Just for fun I select Forward — a new email appears containing a picture of the lefthand panel. It’s hard to overstate the uselessness of this.) But no New Folder option.

File/New from the menu bar. This gives me a few options: Memo, Calendar Entry, Contact, To Do, and URL. (URL?! I try selecting that. It turns out that it actually just lets me type in a URL rather than create a new one. And then it opens up the URL in Internet Explorer. Even though Firefox is my default browser.) But no New Folder option.

Create from the menu bar. Surely. But no: I can create a new Memo, Reply, To Do, etc. There’s a Special submenu that lets me send a message to the database manager. There’s also an Other… option. Surely here! But no, Other… actually just gives me a list of the same options in the rest of the Create menu. Brilliant — the Other option actually does not give me any other options at all! It’s utterly worthless and confusing and I really can’t be bothered trying to come up with words to express how monumentally stupid the whole thing is. And I still can’t create a new folder, even from the Create menu.

And now finally I discover the several ways to create a folder. I select the Inbox icon to show the Inbox view. There is a button bar above the actual Inbox view. It’s not a toolbar — there are already two toolbars below the menu bar. This button bar is just a row of buttons, except that some of them are really dropdown menus that look like buttons. Anyway, there is a Folder button (actually a menu) that has a Create Folder… option. I didn’t notice it before because it wasn’t there — I had the Trash displayed, and the Folder button/menu does not appear when the Trash is displayed.

With the Inbox showing, there’s also a Folder/Create Folder… item in the Actions menu. But I also notice that if I click the Inbox icon, the menu bar shows File, Edit, View, Create, Actions and Help. But if I click the word “Inbox” beside the icon, the View, Create and Actions menus disappear after a second. If I click it again, those three menus appear for a second and then disappear again. Oh dear.

Also, it turns out that I could right-click the Inbox icon — a New Folder… item is in the context menu. Note that the new folder does not appear in the Inbox. In fact it has nothing to do with the Inbox.

So finally I have created a new folder, which appears under the Folders icon. It appears that I can now right-click on my new folder to get a context menu that will let me create another folder. And now that there’s a folder under the Folders icon, right-clicking the Folders icon gives me a different context menu! It’s the left-hand panel context menu (with the nonsensical Forward option) rather that the old Folders icon context menu (with the nonsensical Italic option).

All this just for a folder. In the time it took me to do this I could have simply run the Lotus Notes uninstaller and ended up much happier.

Scrolling: I got a meeting invitation that contained several screenfuls of text, but there was no scrollbar. In fact I didn’t even discover the text until I printed it out and was surprised that it was 5 printed pages. Scrolling with arrow keys or scroll wheel didn’t work. I also couldn’t select any text. I tried going into edit mode, and that seemed to make things better, though the scroll wheel still didn’t work unless I actually selected some text. (!?)

Daylight Saving: This is from a Certain Company’s intranet from 31 March 2008. This is not a joke:

The end date of Daylight Saving Time in New Zealand has been extended for 1 week this year. We now revert back on Sunday 6th of April.

When browsing your calendar for the week starting Monday 31st of March, your meetings may appear to be 1 hour late, so please OPEN the calendar entries to view the correct start time.

Ugly: The Notes client has its mysteriously-changing “keychain” picture. The Web client has a big red stop sign on its login page. The stop sign has a fat, fleshy hand on it, just to hammer home the point that you have to stop. It looks like a scary error icon. Why is it even there at all? The only sensible interpretation I can think of is that it’s saying “Stop, the application you are about to log in to is hideously bloated and ugly.”

Meeting invitations: There’s no obvious way to accept a meeting invitation without sending a response. Even worse, select Respond with Comments; an email form appears. Change your mind and close the email form. You get an “are you sure?” dialog box, and since it’s Notes, you get several choices: Send as is, send without comments, or continue editing. That’s right, there is no way to cancel. You are forced to send the response. You can’t even quit from Notes now — if you try you will get the dialog box offering the same three choices. The only way to quit Notes without sending the response is to use the Windows Task Manager to kill the process. This is magnificently, fantastically stupid and is just another reason why the people who designed Notes should hang their heads in shame.

It turns out that even killing Notes won’t kill the meeting response form. When I started up Notes again, the form was there. Apparently that form will now be a permanent fixture of my Notes usage forever, until I finally give in and send it. Even though I don’t want to send it. Shame! Shame!

I noticed that a couple of days later, the form had finally gone. I can’t even remember if I restarted my PC or something like that, or if I finally gave up and sent the confounded thing. I have no more comment.

Webmail drafts: When you’re writing an email using the webmail interface, the Save button saves the email as a draft and then closes the window. So if you’re writing a long email and you want to save periodically, you have to keep pressing the button and then going back to the main window, opening the Drafts folder, opening your message and scrolling down to the bottom to continue. What a waste of time.

Spurious error: In webmail, if I create a new message and start editing it and then return to the main window and select a mail folder, a message pops up saying that they are sorry (which is nice) but “we were unable to process your request at this time.” (I don’t know who “we” refers to — the entire Lotus Notes development team, presumably). So I click OK to dismiss the dialog box and guess what? Everything works fine.

Well, I could go on. In fact I already have. It’s important to pick holes in Notes like this because otherwise we might get used to its warts. If we relax our standards for the software we use, it might flow on to affect the software we write. For this and for so many other reasons, Lotus Notes is rubbish.

Share This

The Model-View-Controller application structure came from Smalltalk and has been around for 25 years or so. The Model refers to the application classes, the Controllers are the classes that interpret and respond to user input, and the View displays the results to the user. Web MVC frameworks like Struts, Spring Web MVC and Ruby on Rails use a similar kind of structure, refined to fit the way the Web works.

Problems with MVC

Here’s the standard MVC overview. There are three dependencies. First, the Controller updates the Model and extracts Model data. Second, the Controller packages Model data for the View. Third, the View displays data from the Model.

A few things bothered me about the MVC architecture as implemented in Spring and elsewhere.

1. The Controller classes depend on the View. The Controllers create a Model object which is displayed by the View; because of this, the Controller needs to know which data to include in the Model, because the View is expecting certain named data items. In effect, the Views have an implicit interface that the Controller must honour. This seems wrong if the Controller processes input and the View displays output — they should be completely decoupled.

2. In many cases, Controllers do too much work. For example, a typical edit controller carries out three separate functions. First, it displays a form for editing a record. Second, it processes user input (e.g. “user clicks the Delete button”). Third, it creates a Model and forwards to a View (e.g. show a list of widgets). These activities are not necessarily related, so why bundle them together in one class, or even in one package?

3. The definition of Model seems inconsistent. Originally the model referred simply to the data that was to be displayed in the view. This is sometimes referred to as a Presentation View. However, the J2EE “Model 2″ MVC architecture considers the Model to be all domain-specific code, including data but also including business logic. Rails is similar, but the Model is tied to the database layer, and business logic often seems to live in the Controller. Frameworks like Spring revert to the original meaning, where the Controller creates a Model data structure for use by the View.

These are not really problems; they are just a result of the high-level nature of the MVC structure. It’s easy to understand MVC, but it’s impossible to follow it strictly because the structure itself is ill-defined. Drilling down insde the MVC pattern lets us bring out more detail and understand better the responsibilities of each component. The Controller → Model dependency is straightforward, but the other two dependencies can be refined so as to clarify the MVC architecture.

Refactoring the Controller

In many cases, a Controller carries out several tasks. For example, a typical edit controller carries out three separate functions: form display, input processing, and results display. Code like this is typical.

Controller:
if (editing a new record) then
   Display the form
else
   Save changes
   Display the updated record
endif

Often, the code to set up and display a form has only a tiny amount in common with the code to just display a record. The form Controller code need to retrieve values for dropdown menus and checkboxes and other supporting information; the form View needs client-side data validation and other presentation code. And the code for saving changes has little in common with either of the views. This suggests separating the two. Controller code that sets up a view doesn’t need to update the Model; it only reads it. This type of Controller I call a Presenter. A Controller that updates the Model is called an Actor.

With this structure, the three tasks previously managed by the single Controller become the responsibility of three separate objects: two Presenters and one Actor.

Presenter 1:
Display the form

Actor:
Save changes

Presenter 2:
Display the updated record

Also, note that the Presenter depends on the View (as the Controller did before) but there is no dependency between the Actor and the View. This confirms that the Presenter and the Actor really are separate kinds of object.

Refactoring the Model

The other dependency is that of the View on the Model. To clarify this, I noticed that “Model” sometimes refers to all classes that embody application data, and sometimes it refers only to specific subsets of that data: for example, a specific data structure used by a specific View (as in Spring), or an object-based abstraction to a database (as in Rails). For my purposes, I have decomposed the Model into two separate pieces. One part is the plain data entities that represent business data; these are called Entities. The other part is the code used to store and manipulate the entities; this is called the Store.

Starting from the basic MVC, here’s what happens when we split the Model into Entity and Store.

This shows that the View depends only on the Entity, not the Store. This makes sense, since the View only needs to display the basic data objects provided to it by the Controller; it does not access the Store itself.

The Vespa pattern

Putting these two ideas together gives us a unified diagram showing how the five areas of the application depend on each other.

This diagram makes it clear that everything depends on the Entities. This is what we would expect. The essential function of an application is to manage data; we would therefore expect all areas of the application to depend on the data to some extent.

Since the Entities are essentially a global dependency, we can simplify the diagram by making that explicit. The result is an architectural pattern that I like to call Vespa. (It’s an acronym for View, Entity, Store, Presenter, Actor; but it looks ugly if written in capitals. It’s also a brand of motor scooter, so conjures up images of sleek, fast, shiny things.)

The Vespa diagram is almost as simple as the original MVC diagram, but it is far more instructive and useful. It’s easy to see where each application function fits and what other functions it depends on. It’s particularly appropriate for Web applications. If you’re writing a simple application or a custom framework, you can follow the Vespa architecture directly. Even if you’re using an existing framework such as Spring, Vespa can help to clarify your thinking as you organise your Controllers.

Share This

try {
   doSomething();
} catch(err) {
   // Die quietly
   alert(err);
}

Share This

Widgets

Search Meter 2.3 includes two WordPress widgets. Popular Searches shows a list of the most popular search terms that have produced hits at your site during the last 30 days, and Recent Searches shows a list of the most recent searches that produced hits at your site. Readers can click search terms in the list to search for the term themselves. Both widgets display up to 5 search terms by default, but you can change this to whatever number you like.

Security

This version fixes a security hole in previous releases where it was theoretically possible for an unscrupulous website to trick you into deleting your saved search data. This was a pretty minor risk: the search data is transient anyway, and I have not heard of anyone even thinking of doing this, let alone actually managing to carry it out. Anyway, from Search Meter 2.3 the “attack” is no longer possible. Previous version are still vulnerable, so truly paranoid users should upgrade. And don’t forget to wear your tinfoil hat.

A polite suggestion

The Options and Statistics screens now include a button allowing convenient access to PayPal to make Search Meter donations. This is meant to be a gentle, unobtrusive suggestion rather than a blatant advertisement. There’s an option to turn it off if you don’t like it (or even better, if you have already made a donation).

Remember, donating is optional. You can donate nothing, or you can donate $1000 (yes, really) but Search Meter will work the same regardless.

Other changes

I have made a number of changes to the internal workings of the Search Meter code, just to tidy things up a bit and make it easier for me to work with. This version also contains the installation bug fix from Search Meter 2.2, which I released quietly a few months ago. That problem was caused by a core change made in WordPress 2.2.1.

Download

As always, go to the main Search Meter plugin page to see full details and to download Search Meter 2.3.

Share This

I could revert to using WPFV as a default GIF viewer by using Windows Explorer Options, but this seemed to affect only Explorer; if I opened an email attachment in Thunderbird it still tried to use IE. The real answer is simply to re-register the DLL the WPFV uses. Here’s the command to run, courtesy of Leo:

regsvr32 /i shimgvw.dll

Just run this once in your Windows system and all will be right with the world again.

Share This

The best new feature is that Code Markup now fixes a WordPress bug where backslashes inside a <pre> block would not be displayed. With Code Markup, such backslashes are now displayed even if not in a code block.

The “allow” attribute is now called “markup”. I could never remember whether allow="span" meant that <span> was allowed as a literal or allowed as markup. Now I hope it’s clearer: markup="span" means that <span> will be treated as markup, not displayed literally.

For backwards-compatibility, you can still use “allow” as the attribute name. So any existing code blocks will still work with the new Code Markup.

Finally, Code Markup works better now with tags and comments that span multiple lines.

Download

For details and download, see the main Code Markup page.

Share This

Using the elementReady plugin is very similar to the existing jQuery.ready() function, except that you must also pass in a string representing the ID of the element that should have the function call attached.

This version of the plugin works well for me in testing (and on this page), but it has not been exhaustively tested. I would appreciate your comments on the idea and the implementation.

Download

Get jquery.elementReady.js here. Then read on for instructions and details.

Documentation for jQuery.elementReady()

$.elementReady( String id, Function fn ) returns jQuery

$.elementReady('powerpic', function(){
    this.src = 'powered-by-jquery.png';
});

$.elementReady('header', function(){
    $(this).addClass('fancy');
});

$.elementReady('first',  function(){ $(this).fancify(); })
 .elementReady('second', function(){ $(this).fancify(); });

jQuery.noConflict();
jQuery.elementReady('header', function($){
    $(this).addClass('fancy');
});

$.elementReady.interval_ms = 100;

Why?

I asked about this feature on the jQuery development list, and to my surprise nobody had made much of an effort to do this. jQuery author John Resig has some magic code that makes this happen automatically(!), but including this “auto” feature in the core would complicate things unnecessarily. He suggested that a plugin should be written. So here it is.

Implementation notes

The jQuery.elementReady() function is interesting because it’s quite unlike most other jQuery methods. It’s not a method applied to a normal jQuery object; it can’t be, because a jQuery object is normally constructed from a DOM element (or list of DOM elements). But in this case, all we have is the ID of an element: the element itself does not yet exist.

When the function is called, the matched element is passed to the callback function as a raw DOM element rather than a jQuery object. This is consistent with other event handlers, and is also the most efficient approach.

The function returns the global jQuery object, so you can chain calls to elementReady().

My implementation is inspired by the Yahoo UI library’s onAvailable(), but is simpler (and, to be sure, less well-tested). YUI also includes a related method called onContentReady(), which is supposed to fire when the element and all its content is available. I have not implemented that feature yet, but I think I may end up doing so in elementReady(). This will make it more robust yet still dead simple to use.

I thought about somehow overloading the original ready() function but thought that would just add complexity for no real benefit.

Things to do

This is an early version of the plugin. I’m afraid I have tested it only on Windows browsers, but I have had no problems with it yet. The main thing to do is to test it more thoroughly. As I mentioned above, I also might decide to modify the function to check that the entire contents of the target element are loaded, not just the element itself.

Have your say

Apparently blog posts get x% more comments if the last heading says “Have your say”. So have your say! Is this useful? How can it be improved?

Share This

I have recently redesigned this website; it now uses the marvellous jQuery library for some of the effects. So to avoid having to include Prototype, I modified Share This to use jQuery instead of Prototype. If you want to reduce the time taken for your pages to load, you could replace the original Share This with my version; this is is especially good if you are already using jQuery.

To use this version of Share This, first install the original Share This (version 1.4), and then download Share This (jQuery) and replace the original share-this.php file with the new one. Read on for more details.

Here are the changes I made, compared to version 1.4 of Share This.

Use jQuery instead of Prototype.
jQuery is included in WordPress 2.2 and later versions. For earlier versions, you should download jQuery and copy it into the wp-includes/js/ directory in your WordPress installation. Make sure the file name is jquery.js.

Behave nicely if somebody tries to load the plugin file directly.
If someone tries to load the share-this.php file directly, just show a blank screen. The original version shows an error message.

Use a sliding “roller blind” effect when showing the Share This popup window.
Just because it looks nice.

Remove some unused code.
Because it was unused.

My modifications are in the public domain.

Now, there is one other change. The position of the popup window is not the same in all browsers; in some browsers (such as Firefox) the popup appears below the “Share This” link; in others (such as Internet Explorer) the popup appears just to the right of the link. I don’t mind the inconsistency: both variations look nice in themselves.

I thought about using the Dimensions plugin to emulate the original Share This more exactly. But in the end I decided to keep things simple and avoid introducing yet another file.

Share This

Local variables in JavaScript are scoped to the function they are in, not to their containing block. This is different to C++, Java and similar languages. One of the consequences of this is that a var statement by itself generally does nothing at all, unlike in C++, Java, etc. Here’s a contrived example.

for (var i = 0; i < 5; ++i) {
	var t;
	// If i is even then set t to "even"
	if (i % 2 == 0) {
		t = "even ";
	}
	// If t is not set then i must be odd
	if (!t) {
		t = "odd ";
	}
	document.write(t);
}

After one iteration, t contains the value “even ”. In the second iteration, a Java or C++ programmer might expect the var t to initialise the variable t again, so t will subsequently end up with the value “odd ”. But actually the var t has no effect and t always has the value “even ”. The program above writes “even even even even even ” to the document.

The fix is simple. Instead of an ineffectual var t, use var t = null to explicitly set the value of t. In fact, you could follow Douglas Crockford’s JavaScript coding conventions, which recommend:

All variables should be declared before used. JavaScript does not require this, but doing so makes the program easier to read and makes it easier to detect undeclared variables that may become implied globals.

The var statements should be the first statements in the function body.

…

JavaScript does not have block scope, so defining variables in blocks can confuse programmers who are experienced with other C family languages. Define all variables at the top of the function.

Following this recommendation, you’d write the following code, which produces “even odd even odd even ” in proper accordance with the laws of parity.

var t;
var i;
for (i = 0; i < 5; ++i) {
	t = null;
	// If i is even then set t to "even"
	if (i % 2 == 0) {
		t = "even ";
	}
	// If t is not set then i must be odd
	if (!t) {
		t = "odd ";
	}
	document.write(t);
}

Share This