Tutorial: Providing user-friendly and flexible note-tags

Help spread the word!Share on FacebookShare on TumblrTweet about this on TwitterShare on Google+Share on LinkedInShare on RedditFlattr the author

When it comes to coming up with note-tags, I think one of the most important things is whether it is user-friendly or not. When you look at a script from a user’s point of view, there are several things they have to do

  • Figure out what it does
  • Figure out how to use it
  • Writing up all  those note-tags and other required inputs
  • Hope it works

If it works, that’s great. But when it doesn’t work, then they have to figure out why it doesn’t work, and the worst thing is to realize an underscore was used instead of a hyphen, so why not try to make the process easier by providing flexible note-tags?

Background

Consider a simple notetag:

<custom value: 23>

The regex for this would be simple as well

/<custom value: (d+)>/

It works, and as long as users type the note-tag exactly as you have prescribed, but there are a few issues with this solution:

  • It is case-sensitive. If I accidentally type “Custom” instead of “custom” this value won’t be parsed, and so “it won’t work”.
  • It is space-sensitive. No space between the colon and the number? Won’t be parsed. Extra space after the number? Won’t be parsed.

Some other issues include user-preference when it comes to separating words. All of the following are possible variations that someone may naturally type

<custom value: 23>    - prefers spaces
<custom_value: 23>    - prefers pothole case
<custom-value: 23>    - prefers hyphens
<customValue: 23>     - prefers camelcase or pascal case

Specific characters aside, some people might just like to line everything up neatly:

<custom value:   112> 
<custom value:    23>

Techniques

My choice of note-tagging addresses all of these possible preferences. Although it makes the regex look unnecessarily long, it does not take much effort to write or maintain. The same note-tag I presented above would be parsed using this regex:

/<custom[-_ ]?value:s*(d+)s*>/i

Things to note:
I allow users to choose between a hyphen, underscore, space, or no separator at all.

[-_ ]?

I allow users to choose how much white-space they want before and after the data

s*

I allow users to choose whatever case they want to type in with the `i` modifier at the end of the expression.

Closing

There are of course many more things you could do to make your note-tags flexible, such as allowing users to split it across multiple lines, or adding support for white-space in various places. Some users might prefer to use a completely different set of characters to separate words.

I would typically just go with the tips shown above as I don’t think it is necessary to do much more beyond that. The purpose is to reduce the chances of user-error, and those are probably the more common issues.

Help spread the word!Share on FacebookShare on TumblrTweet about this on TwitterShare on Google+Share on LinkedInShare on RedditFlattr the author

You may also like...

1 Response

  1. eivl says:

    How nice, thanks! =)

Leave a Reply

Your email address will not be published.

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax