This article is part 2 in that series, in which we write said application in Ruby.

The Interface

You can refer back to the introductory article for all the details, but I’ll reiterate the command-line interface here for easy reference:

• todo – list all incomplete tasks sorted by priority then chronologically
• todo next – list all incomplete tasks that are high priority
• todo done – list all complete tasks chronologically
• todo high “pay bills” – add high priority task called “pay bills”
• todo low “get milk” – add low priority task called “get milk”
• todo finish “pay bills” – complete task called “pay bills”
• todo dont “get milk” – delete task called “get milk”
• todo help – list all commands and their usage

Okay, let’s write this thing!

The Driver

10gen distributes the Ruby driver using Ruby’s most popular package distribution tool, RubyGems. To install the driver on your machine simply execute:

gem install mongo

Our program will need to load in the driver before anything else, and we’ll use RubyGems to do it, so create a new text file called mongo_todo.rb and begin it with the following:

require 'rubygems'
require 'mongo'

The ToDo Class

Ruby is a purely object-oriented language, so our program will employ a single object of a class we’ll write called ToDo. The class will take in the required command-line arguments, connect to the MongoDB collection that stores our todos, and execute the appropriate command on them.

To facilitate these needs, our object will need to take some arguments from the user and store a reference to the MongoDB collection when it is instantiated:

class ToDo
  def initialize(args)
    @args  = args
    @mongo = Mongo::Connection.new.db("todo").collection("todos")
  end
end

In Ruby, the initialize instance method is called when a new object of a class is instantiated, most often using the new class method, like this:

my_todo = ToDo.new

When a new ToDo object is instantiated, our class will store the arguments passed in to it in an instance variable called @args and store a connection to MongoDB in an instance variable called @mongo. Mongo::Connection is a class provided by the mongo gem that we’re using.

Since our class expects some arguments passed in to the initializer, we need to provide them to the new method. The arguments will be read in from the command-line when the program is executed, and Ruby exposes these to our program via the ARGV variable. So, we call new like this instead:

my_todo = ToDo.new(ARGV)

At this point, the entire program should look like this:

require 'rubygems'
require 'mongo'

class Todo
  def initialize(args)
    @args  = args
    @mongo = Mongo::Connection.new.db("todo").collection("todos")
  end
end

ToDo.new(ARGV)

You can execute this program from the command-line, but nothing will happen. Well, stuff will happen but you won’t see it displayed back to you. We still need to implement the bulk of the program, which parses the user’s command-line arguments and acts appropriately.

A Little Help

The first thing we’ll implement is a method that prints usage help for the program. It looks like this:

def help
  abort <<-HELP
  usage: #{__FILE__} <method>

  == Methods ==
  <none>            list all incomplete tasks sorted by priority
  help              show this help
  next              list all incomplete tasks that are high priority
  done              list all complete tasks chronologically
  high "argument"   add high priority task called argument
  low "argument"    add low priority task called argument
  finish "argument" complete task called argument
  dont "argument"   delete unfinished task called argument
  HELP
end

In Ruby, abort is a method you can call which will exit the application and display a string you pass to it. The string we’re passing in shows all the ways the program can be used, which will be displayed back to the user. This will be executed by default if the user doesn’t pass in an argument that we want to handle. More on that in the next section.

Run, Baby, Run

At some point, our application needs to run, so lets create an instance method called run which will handle the program’s flow. In this method we will determine what the user passed in from the command-line and call another method that handles the different use cases. The default action is to list all incomplete tasks, and the catch-all is to execute the help method we implemented above. Here is what run looks like:

def run
  if @args.empty?
    show :complete => false
  else
    case @args.first
    when "help"   then help
    when "high"   then add "high"
    when "low"    then add "low"
    when "next"   then show :complete => false, :level => "high"
    when "done"   then show :complete => true
    when "dont"   then complete false
    when "finish" then complete true
    else
      help
    end
  end
end

ARGV is an Array, so we can call methods like empty? and first on it. The meat of the run method is a Ruby case statement which checks if the first argument passed in by the user matches any of our predetermined keywords and calls other methods, add, show, and complete. These methods are the ones that actually interact with MongoDB and display information back to the user. We’ll implement them next.

Using Mongo

So far we’ve only dealt with setting up our class and parsing user arguments, we’ve barely even touched MongoDB! This is the meat of the application, so let’s get straight to it. First, the show method:

def show(params)
  sort = [["level", Mongo::ASCENDING], ["added", Mongo::ASCENDING]]
  @mongo.find(params, :sort => sort).each { |todo| puts "#{todo["task"]} (#{todo["level"]})" }
end

show takes a hash of params as an argument and passes that hash on directly to the mongo library’s find method, which will return an array of the found items in the collection.

We print each of the todo items returned from find along with the level of the todo. How do those items get in there in the first, place? That is up to the add method, which we will implement next.

def add(level)
  help unless @args.length == 2
  @mongo.insert "task" => @args.last, "level" => level, "complete" => false, "added" => Time.now
  puts "added #{level} level task: #{@args.last}"
end

add takes a single argument, the level of the todo to create (e.g.- “high” or “low”). It then makes sure that the user had passed in two arguments at the command line because it needs the second one for the name of the task. If not, it calls help which aborts the application.

If so, It calls Mongo’s insert method and passes it all the information to be stored in the datastore.

Finally, we need to implement the complete method, which is the most complex of the lot. Like add, it makes sure there were two command-line arguments given. Then it tries to find the todo by the “task” name. If found, it will either “finish” the task or “remove” the task depending on a boolean argument passed in. The method looks like this:

def complete(finish)
  help unless @args.length == 2
  if (document = @mongo.find_one("task" => @args.last, "complete" => false))
    if finish
      document["complete"] = Time.now
      @mongo.save(document)
      puts "finished: #{@args.last}"
    else
      @mongo.remove(document)
      puts "removed: #{@args.last}"
    end
  else
    puts "No ToDo matching #{@args.length} found"
  end
end

The mongo-related calls in the complete method are find_one, save, and remove.

Finishing Up

So, we’ve written our run method which calls the other methods using the user’s passed in arguments. Now all we have to do to get the class going is finish the program by creating a ToDo class object and calling run on it, like this:

ToDo.new(ARGV).run

You can view/download the program in its entirety here. One thing to note is how little code is needed to add CRUD to an application when using MongoDB as a datastore.

Hopefully this article has helped you with Ruby or MongoDB or both. Stay tuned for our next article in the series when we write the exact same application in PHP!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Down & Dirty with MongoDB Part 2: Ruby ToDo

General service announcement: it is written “jQuery” not “Jquery” or “JQuery”… even if it comes first in a sentence!!!! ∞

Then Saturday I put out a stronger tweet, and caught some stronger feedback for it:

Test: “If you want jQuery help, which misspelling will greatly hurt your chances: a) Jquery b) JQuery c) jquery d) All of the above. ∞

At the end of the day, does it really matter how someone writes the name “jQuery”? Does it make them a better or worse programmer based on how they type it out?

Let me clarify that I have never failed to answer a question on Stack Overflow (Where I like to hang out and answer jQuery questions) because the asker typed jQuery with incorrect capitalization. I would never fail to respond to an email because the asker wrote it as Jquery or JQuery. I would hate to be that petty an individual, and I think that is the feeling some people were picking up from my tweets.

However, I can say I notice it and it bothers me when people seeking help don’t type out the library name correctly. It really is a small thing, and maybe it shouldn’t bother me, but it does. It got me thinking about things that might negatively affect a request for help, and I came up with a list of six suggestions. I hope these suggestions are helpful when you need to ask for help with open source software.

Asking for Help

If you need help with an open source project, you will often be dealing with people that 1) don’t have a lot of time and 2) must use the time they have wisely. With that in mind, here are few suggestions that might help you get answers easier:

1. Take the time to make sure your question makes sense. Complete sentences, clear code examples, and links to a page demonstrating the problem all go a long way in ensuring a quality answer.
2. Run spell-check before sending your question. There are at least two reasons there would be a lot of spelling errors in a question: 1) English is not the native tongue of the person requesting help 2) The person requesting help didn’t take the time ensure a quality question. Most applications have spell check. If they don’t, you can copy and paste your question to an application that does have spell check. Reason #1 is understandable and should be overlooked; reason #2 is what will stand out most to someone reading your question. It may affect that person’s decision to answer you.
3. Getting back to my original statement regarding Jquery, JQuery and jquery. Some libraries have really weird spelling or capitalizations, some are more straight forward. Write the library/plugin name correctly when asking for help with it! jQuery should be very easy, but so many people get it wrong. It is like the names iPad and iPhone: the first letter is lowercase! For another example, the popular blogging platform is WordPress, not Wordpress or Word Press.
4. At the very least, run a Google/Yahoo/Bing search (pick one) with some of the words from the question you plan on asking. I almost always take time to run a few searches to answer a question myself before asking on Stack Overflow or emailing someone for help. It is just common courtesy to spend some of your time before asking for the time of someone else.
5. If you find the answer yourself after asking for help, be sure to let the person know you no longer need their help. Sometimes emails will sit around until there is time to answer them while in the mean time you find the answer somewhere else. It might reduce your chance of getting future emails answered if the person who takes the time to answer your question finds out they wasted their time.
6. Be respectful and kind. If an open source project is screwing up your project, you have a few choices 1) use a different project 2) pay for help 3) Ask kindly for help from the project. Notice I didn’t put “4) Demand help for free.” On a very positive note, I have to say every request I have gotten for help on the few small projects I maintain have been both respectful and kind. This is really important!

What It All Means

The bottom line is this: If it appears to someone reading your question that you have not put any time into either solving the problem yourself or writing a decent request for help, they will be less likely to put any time into answering it.

Remember, it isn’t always about just getting an answer. Sometimes its about getting the right person to answer your question. For instance, there are tons of programmers answering questions on Stack Overflow, but not all of them have equal qualifications and skill. Put in the effort up front when asking the question. It will be worth it when you get a solid answer!

Do you have any tips to add? If so, please let me know about them in the comments!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Jquery, JQuery and Asking for help

We’ve found the datastore a joy to use and wanted to feature it somehow on FYC. However, there are many, many introductory articles and getting started tutorials for MongoDB (also the information on the project’s website is spectacular), so we would be remiss to provide yet another basic intro.

Instead, we decided to highlight how the datastore is used from a few popular dynamic languages. 10gen – MongoDB’s creator – provides many official client drivers (libraries) and the open-source community has produced a handful of libraries as well. We couldn’t feature them all, so we chose three favorites – Ruby, Python, and PHP – to include in the series.

The Plot

Many demonstrations use throwaway “Hello World” type programs. We thought it would be much cooler to write something that we can actually use, build upon, and maybe derive some value from. With that in mind, we tried to think of an application that had the following characteristics:

1. Real-world use case
2. Few lines of code (~ 100)
3. Simple to understand and implement
4. No 3rd party libraries or frameworks
5. Demonstrate the basic CRUD operations

For better or worse, we chose to write a command-line todo list app as it fit the requirements well.

The Spec

Our todo application is invoked from the command-line and works as follows:

• todo – list all incomplete tasks sorted by priority then chronologically
• todo next – list all incomplete tasks that are high priority
• todo done – list all complete tasks chronologically
• todo high “pay bills” – add high priority task called “pay bills”
• todo low “get milk” – add low priority task called “get milk”
• todo finish “pay bills” – complete task called “pay bills”
• todo dont “get milk” – delete task called “get milk”
• todo help – list all commands and their usage

The only requirement outside of the user interface outlined above is that MongoDB be used to persist the todo list.

The Setup

An identical application will be written in Ruby, Python, and PHP using the official MongoDB drivers. Each language will get its own article in the series. You have the application requirements so feel free to code along in your language of choice. Also, we’d love to see versions in some other languages that we won’t be covering. Show us your skills by submitting them in the comments. We’ll happily tweet them out and link them up in our final article in the series!

Be sure to grab our RSS feed or follow @fuelyourcoding on Twitter so you don’t miss out as we get down & dirty with MongoDB!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Down & Dirty with MongoDB Part 1: the Plot

Without any further ado, here they are listed alphabetically:

Air Display

Price: $9.99
Type: iPad
Version: 1.0.1

Air Display lets you use your iPad as a wireless display for your Mac OS X computer. Why is this great for developers? Because we need screen real estate, baby!

Here’s a pic of Air Display in action as my 3rd monitor. The iPad monitor is perfect size for your Skype windows, API documentation, or a browser session with programming tutorials.

DomainStorm

Price: Free
Type: iPhone
Version: 1.0

When inspiration for that new web application hits you, the first (and most fun) thing to do is buy a great domain name for it.

DomainStorm is a relatively new app from Network Solutions built to help you accomplish just that. It tells you if domains are available, helps you brainstorm name ideas, lets you mark domains as favorites for later purchase, and even provides you WHOIS information so you can contact current domain owners about a purchase. A must have for sure!

Ego

Price: $1.99, $4.99
Type: iPhone, iPad
Version: 2.1

Obsessed with checking your site analytics? There is no better way to get a quick glance at your traffic than the beautifully designed Ego by Garrett Murray.

With support for Google Analytics, Ember, FeedBurner, Twitter, Mint, Vimeo, Tumblr, and SquareSpace this app has your analytics needs covered. Did I mention it was beautifully designed?

Evernote

Price: Free
Type: Universal
Version: 3.3.5

Evernote is a wonderful way to store all the programming tips, tricks, tutorials and gotchas that we accumulate as we go about our development efforts. The power of Evernote is the universal access to your notes that it provides. They have a web interface, Mac/Windows clients, and mobile apps including a highly polished iOS app.

If you haven’t tried Evernote yet, now is a great time to put all your notes in one highly accessible place. You can even save passwords in Evernote as they provide encrypted strings inside your notes.

iOctocat

Price: $4.99
Type: iPhone
Version: 1.7.1.1

iOctocat is, hands down, the best way to keep up to snuff with open-source development on GitHub from your iPhone.

This app features access to your personal news feed, repositories, individual commits, issues, user profiles and site search. While the app is not free as in beer, it is free as in speech and the source is aptly hosted on GitHub. That makes it a great candidate for learning iOS development as well!

iSSH

Price: $9.99
Type: Universal
Version: 4.2.5

Most developers have found themselves AFK when a very important server is having problems. If you know the feeling, then iSSH is your new best friend.

There are a few remote server control iOS apps available, but this one is the best one that I’ve come across. It allows SSH, telnet, and even VNC connections and boasts many features. The iPad version provides a display size large enough to allow determined coders like myself to fire up vim and get some coding done. The price is a bit steep, but if iSSH saves your butt one time then it has already earned its keep.

iStat

Price: $0.99
Type: iPhone
Version: 1.2

Bjango makes gorgeous and useful software including the OS X system monitoring tool iStat Menus. They also offer a similar app called iStat which displays your iPhone’s system stats.

The beauty of the iStat app for developers is that you can also use it to monitor remote servers running Mac, Linux or Solaris! You simply install a daemon on the server you need monitoring and iStat will show you its CPU, memory, disk, temps, uptime, and tons more information. It feels great to have intimate details about your servers always at your fingertips.

Nezumi

Price: $4.99
Type: iPhone
Version: 1.2

This one is specific to Ruby-using web developers. For those who fit that description, you absolutely need to try deploying an application to Heroku. It is the dead simplest way to get deployed and if you haven’t tried it yet then you don’t know what you’re missing out on.

For those who’ve seen the Heroku light, Nezumi is a must-have companion app for the Heroku service. Nezumi gives you instant access to your Heroku apps from your iPhone so you can add collaborators, manage your dynos, toggle maintenance mode, execute rake/console tasks, and even restart your application on the go. Love it!

So there you have ‘em. Eight great iOS apps for developers. Hopefully you’ll find that one or more of these apps helps you increase your productivity as a developer. I know I’m better off with them than I was without.

If you know of any other iOS apps that did not make my list, please give them a shout out in the comments, so we can all check them out!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Eight Great iOS Apps for Developers

If you want to dramatically increase your programming skills you need to be reading other people’s code.

Maybe you believe that, maybe you don’t. You should. And if you’re willing to give it a shot, I believe you will be rewarded greatly for your time.

In this article I will help you choose what to read and give you practical advice on how to go about reading it. If you’re already a code reader you may find a few ways to get more from your efforts. If you aren’t, you absolutely must read on.

What to Read

This is a big decision, and one that is difficult to advise on. I won’t simply point you toward code I think you should read, because it really comes down to what you’re in to. However, I will provide some guidelines which you can follow to help you choose what to read.

» Read Code That You Rely On

A great place to start is with any plugins or libraries that you are already using.

• A WordPress plugin that you really like
• A Ruby gem that you’ve found useful
• A jQuery plugin that you keep going back to

These are all great candidates for learning. You are already familiar with their public APIs so the barrier to understanding their inner workings is lower. Also, as a user of the code you have an opportunity to add documentation, implement a new feature, or generally give back to the project in some way.

» Read Code That Impresses You

I remember the first time I saw 280 Slides and I thought to myself, “Now that is impressive.” I quickly learned that the code driving that site was the open-source Cappuccino project. I tucked that knowledge into the far recesses of my brain and when I eventually came across another impressive app running on Cappuccino I knew I had a project that I could learn a lot from. What have you been impressed by lately? Is it open-source? If so, it’s a great choice for reading since the code is likely to impress you as much as the resulting application.

» Read Code Written By Somebody You Respect

If you’ve been coding with open-source software for more than a little while, there are probably other programmers who have earned your respect. I can think of a few developers off the top of my head whose code is downright enviable.

If you don’t have a respected developer in mind, it’s easy to find one. He or she has probably authored some code in one of the previous two sections (code you rely upon, or that impresses you).

» Read Code That You Can Actually Grok

If you’re the adventurous type you may be considering diving into a large project like Ruby on Rails, Drupal, or jQuery. I suggest avoiding projects like these for now unless you are an experienced code reader.

Large projects have a lot more moving pieces, and you may end up struggling too much with the concepts to learn anything of immediate value. Confusion leads to discouragement, and larger projects more likely to confuse and discourage you in your reading. The advantage of picking a small project to read is that you can hold the entire program logic in your head at once. This leaves you with just the details to discover and learn from.

How to Read

Now that you’ve chosen some code to read, what is the best way to go about reading it? I’ve read a lot of code in my days, and I can suggest a few ways to maximize your ROI.

» See the Big Picture

I’m going to assume that you at least know at a macro level what the code you’re reading accomplishes. If not, I suggest reading the project’s website, tutorials, documentation, and anything else you can get your hands on except the code.

Okay, with that cleared I suggest your first step is to wrap your head around the project’s structure. This is a variable amount of work depending on the size of the codebase you’ve chosen, but anything larger than one file will require a little bit of time.

First, note the file structure. This step is aided by an editor that has a folder hierarchy view like TextMate. For example, here is a nice overview of the Twitter Ruby gem:

The goal with this step is to just get familiar with the source. Find out which files include/require/load other files, where the bulk of the code is, the namespaces used if any, and things of this nature. Once you’ve got the big picture you’ll be ready to dig into the details.

» Document Your Findings

Reading code should not be a passive activity. I encourage you to add comments as you go, documenting your assumptions and your conclusions as you begin to understand the program flow. When you first get started your comments will probably look something like:

# I think this function is called after 'initialize'

# What does this equation even do?

# Pretty sure this variable loses scope after line 17

As your understanding progresses you can remove the little breadcrumb comments you left yourself and perhaps write more meaningful and authoritative comments that could possibly be committed back to the project.

» Use the Tests, Luke

Hopefully the project you’ve chosen has a test suite. If not, you can skip this section altogether (or find one that does).

Tests are a great place to start whenever you read somebody else’s code because they document what the code is supposed to accomplish. Some tests are more informative than others, but no matter how well written, you’ll often find the programmer’s intent in the tests much more easily than you’ll find it in the implementation. While you’re reading, try to get the test suite to run successfully. This will make sure your development environment is configured properly and will make you more confident when making changes.

» Execute, Change Stuff, Execute

Who said reading code had to be hands off? You’ll really start to understand things once you’ve broken everything and put it back together again. Remember those tests you got passing? Make them fail, add some more, or try changing the implementation without breaking them. Try adding a small feature that you think is cool, or setup project-wide logging so you can print output at various stages of the code. Is this still reading? Absolutely, but at this point its more of a choose your own adventure than a mystery novel. And that’s a good thing!

» Rinse and Repeat

Once you finish reading one codebase, pick another one and start the process over again. The more code you read, the better you get at reading it and the more you get out of it in less time. I think you’ll find that the ROI increases quite quickly and that it’s actually a very enjoyable way to learn.

Where To Start

The single most influential factor in my code reading is GitHub. The site makes it so easy to find new projects and great coders that you’re doing yourself a disservice if you’re not leveraging it. I suggest starting on GitHub and reading code right on the site until you find a project you know you can learn from. Then git clone that baby and get to reading!

How about you? Do you read code as a learning tool? Which projects would you recommend to others? Read any good code lately?

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

One Sure-Fire Way to Improve Your Coding

Two example links of this simple functionality in action are:

1. http://www.meghantelpner.com/shop/?c=books

2. http://www.elmwoodspa.com/shop/

In the first example, you can click on one of Meghan’s books to see more information before deciding to purchase. If you click on “buy now”, you will be taken to her e-junkie store. Additionally, if you click on a specific book to see more information, you get a small navigation block at the top of the article that allows you to quickly browse the next and previous products. You may notice that if you click on one of the other submenus within her store, such as the Books/DVDs/Audio, that you will be taken directly to the Amazon affiliate link for that product. The client has the capacity to choose whether or not to link the product to an external link (Amazon, e-junkie, paypal) or whether or not to link to the full product page itself first, with a “buy now” button.

In the second example, you can click to see details/shop online which takes you immediately to Elmwood Spa’s online store.

I will be using the first example as a basis for the tutorial.

Plugins used: cbs_category_list, zem_nth (both optional) and upm_image

First you’ll want to set up some custom fields, depending on how you want your shop to function. For Meghan’s shop, there are instances where she links to external products via a buy now button. Other times, she’ll want to link to an external site without the buy now button. So I have created 2 custom fields, “link to this site” and “buynow.” If you link exclusively to Paypal links, you could name it paypal, or whatever is easy for you to remember. (As long as you adjust it accordingly in the article forms)

Now let’s take a look at one of the product pages inside textpattern:

1. The title that will appear on the shop landing page

2. The description that will appear only one the item is clicked on

3. This is the link that the thumbnail and title will link to if you put a link (full url) here, otherwise:

4. A buy now button will appear and will link to the full url pasted here (if a link is not placed in either field, the title and thumbnail will merely link to the full article page automatically)

5. Place the image id number here that you want to associate with the article (the thumbnail version of this image will appear on the shop landing page, while the full image size will show on the individual article page.)

6. Choose the appropriate section for your article, in this instance, “shop.”

7. Select the appropriate categoryfor the article (if applicable. You may not have a need for categories)

8. IF USING THE BUY NOW FIELD you must use the override form named shop_listing2 (I’ll explain below)

SAVE your article!

shop subnav

In the actual page template for the shop, the code that calls the shop submenu (books and guides, etc) looks like this:

<txp:cbs_category_list parent="shop" wraptag="ul" break="li" class="subnav" section="shop" showcount="false" class="subnav" activeclass="active"/>

Using the plugin cbs_category_list, this pulls a list of all of the categories with a parent category of “shop”, wraps each category in a list tag, wraps the whole thing in an unordered list with a class of subnav, and assigns a class of active on list items when they are active. Handy dandy! You don’t necessarily need to use this plugin if your shop does not need this type of subnav.

Ok, so how do we pull all of our shop items into the page? The article tag in our shop page template looks like this:

<txp:article listform="shop_listing" form="shop" limit="99" sort="posted asc"/>

So this tag basically says: on the landing page (or listform version of the page), display the articles using the form of “shop_listing”. If you’re looking at an individual article page, (i.e. an individual product page) display the article using the form “shop”. Limit the amount of articles shown to 99, and sort them by date of Posted Ascending.

The “shop_listing” form looks like this:

<div class="shop-item">  <a href="<txp:permlink  />"><txp:upm_article_image type="thumbnail"  class="shopimg"/></a>  <h3><txp:permlink><txp:title  /></txp:permlink></h3>  <span><a href="<txp:custom_field  name="buynow" />">BUY NOW</a></span>  </div>

Translation: the thumbnail version of the article’s image is being pulled from the “Article image” field in the article, and assigned the class of “shopimg” for styling purposes. Both the title and thumbnail are linked to the permanent link to the article (which will show the body/description of the product. The Buy Now button links to whatever gets put into the custom field named “buynow.” The shop-item css looks something like: .shop-item {float:left; margin:20px 25px 10px 0; width:175px; }

Alternately, if you want to get really nerdy, you could use the plugin zem_nth to tell every third (or whatever number) post to display with different class. I use it to apply “shop-item-last” (which has a margin-right of zero) to every third item , so the last item in every row doesn’t have any extra margin space on the right. You can choose to do your layouts with or without zem_nth. This is what my shop_listing article form really looks like:

<txp:zem_nth step="1" of="3"><div class="shop-item"></txp:zem_nth><txp:zem_nth step="2" of="3" ><div class="shop-item"></txp:zem_nth><txp:zem_nth step="3" of="3" ><div class="shop-item-last"></txp:zem_nth><a href="<txp:permlink />"><txp:upm_article_image type="thumbnail" class="shopimg"/></a><h3><txp:permlink><txp:title /></txp:permlink></h3><span class="register"><a href="<txp:custom_field name="buynow" />">BUY NOW</a></span></div><txp:zem_nth step="3" of="3" ><hr class="space" /></txp:zem_nth>

The “shop_listing2″ form (for products without a buy now button, linking externally) looks like this:

<div class="shop-item">
 <a href="<txp:custom_field name="link to this site" />"  rel="external"><txp:upm_article_image type="thumbnail"  class="shopimg"/></a>
 <h3><a href="<txp:custom_field name="link to this site"  />"><txp:title /></a></h3>
 </div>

This tells the title and thumbnail on the listing page to link directly (in a new window/tab) to the link that is found in the “link to this site” field shown in the image above, #3. You could also include the <txp:excerpt /> tag if you wanted to include an excerpt. If you want the article to appear this way (without the buy now button), you need to ensure that you are using the override_form in the article named “shop_listing2″.

Now that we have set up what the listing page looks like for product pages, let’s look at how the individual product pages look. If you will recall the article form we used:

<txp:article listform="shop_listing" form="shop" limit="99"  sort="posted asc"/>

We need to create a form called “shop” that will determine how the individual pages look once you click on the thumbnail/title.

The “shop” article form looks like this:

<p><a href="/shop">Back to Shop</a> |  <txp:link_to_prev>Previous Product</txp:link_to_prev> |  <txp:link_to_next>Next Product</txp:link_to_next></p>
 <div class="right"><txp:upm_article_image/><br /><span  class="register" ><a href='<txp:custom_field  name="buynow"/>' >BUY NOW</a></span></div><txp:body />

Translation: The tags inside the paragraphs set up a small subnav which allows the user to click through to the next/previous products. Then it puts the full version of the article image in a div labelled “right” (which I float right in my css), below that place a Buy Now button which links to the url provided in the “buynow” custom field. Then display the body of the article. You could of course format the tags however you want. (image on top with text below, etc). Individual product page pictured below:

individual product page

Using custom fields is a great way to allow the client (who doesn’t know how to code) to be able to add new items to the shop easily without having to see any textpattern or html tags, and avoid them forgetting to close link tags and add things like rel=”external”. Yay!

This tutorial assumes that you have textpattern installed and ready to go, and have a good grasp of the tags.

( Download the latest version of Textpattern here: http://textpattern.com/download )

Did I miss anything? If you need any more clarity or have any questions, please feel free to put them in the comments, and I will do my best to help.

Happy Coding!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Create a simple “shop” page in Textpattern

Lifestreaming is the aggregation of all of your actions throughout the web in one place to present a complete picture of your digital life. There are several lifestreaming applications out there, and Storytlr was one of the first.

Storytlr was originally a closed source, hosted web application started by Laurent Eschenauer and Alard Weisscher in 2008. In October 2009 they decided to close the service and in December they open sourced the code.

Considerable community development has occurred since the project was open sourced, including many new plugins, bug fixes and features.

Installing Storytlr

Storytlr is written in PHP and based around the Zend framework. It is usually run on Apache, but works fine on lighttpd and Nginx. The current stable release is 0.9.2, although there is an RC 0.9.3 that works well. Additionally you can use the bleeding edge code on GitHub. I currently maintain my own version of 0.9.3 that has a few more features and plugins you won’t find in the core. You can find it here.

Since it’s coming out of a close source system, expect some rough edges and thin documentation. This is improving all the time with the growing wiki and the issues board. Installation is still one of those rough edges, but it’s fairly easy anyway.

For simplicity I’ll be using the 0.9.2 release from the Google Code site, but these instructions can be easily adapted to other versions. I’ll be doing just about everything from the command line, so if you don’t have shell access, be prepared to tweak things a bit.

Requirements

First, let’s make sure our server is compatible. 0.9.2 has the following requirements:

• PHP 5
• mcrypt
• PDO
• Tidy
• MySQL
• Zend Framework

An easy way to check compatibility is to use this script.

Most hosts have these extensions. The rarest one is Tidy.  For instance, Dreamhost does not run Tidy. If your host doesn’t have Tidy, you can work around it by using a different version with the htmLawed patch.

If you are missing Zend, that can be downloaded here. Make sure to put it in your PHP include path.

Getting Started

Now that you’ve got the requirements met, download the 0.9.2 file and unpack it into your root web directory.

jmhobbs@katya:/var/www/lifestream$ wget http://storytlr.googlecode.com/files/storytlr-0.9.2.tgz
--2010-05-07 13:33:05--  http://storytlr.googlecode.com/files/storytlr-0.9.2.tgz
Resolving storytlr.googlecode.com... 74.125.45.82
Connecting to storytlr.googlecode.com|74.125.45.82|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 8748114 (8.3M) [application/x-gzip]
Saving to: “storytlr-0.9.2.tgz”

100%[============================================>] 8,748,114    233K/s   in 36s

2010-05-07 13:33:41 (239 KB/s) - “storytlr-0.9.2.tgz” saved [8748114/8748114]

jmhobbs@katya:/var/www/lifestream$ tar -zxf storytlr-0.9.2.tgz
jmhobbs@katya:/var/www/lifestream$ ls -a
.  ..  feeds  flash  friendconnect  .htaccess  images  index.php  INSTALL  js  LICENSE  protected  storytlr-0.9.2.tgz  style  themes
jmhobbs@katya:/var/www/lifestream$

The Database

Now you need to load the database schema. The schema files is located at protected/install/database.sql. If you don’t have a database or user set up, now is the time to do that as well.

jmhobbs@katya:/var/www/lifestream$ cd protected/install/
jmhobbs@katya:/var/www/lifestream/protected/install$ mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 5515
Server version: 5.0.81-1 (Debian)

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> create database lifestream;
Query OK, 1 row affected (0.05 sec)

mysql> grant all on lifestream.* to lifestream@localhost identified by 'supersecretpassword';
Query OK, 0 rows affected (0.11 sec)

mysql> flush privileges;
Query OK, 0 rows affected (0.08 sec)

mysql> use lifestream;
Database changed
mysql> source database.sql
Query OK, 0 rows affected (0.00 sec)

(Lines Removed For Brevity)

Query OK, 0 rows affected (0.00 sec)

mysql> Bye
jmhobbs@katya:/var/www/lifestream/protected/install$

Configuration

Your last major step is the configuration file, which goes at protected/config/config.ini. Storytlr provides an example file with good defaults, so we’ll edit that. The key settings to change are:

• db.username
• db.password
• db.dbname
• security.cookie
• web.host
• web.timezone

jmhobbs@katya:/var/www/lifestream$ cd protected/config/
jmhobbs@katya:/var/www/lifestream/protected/config$ ls
config.ini.sample
jmhobbs@katya:/var/www/lifestream/protected/config$ cp config.ini.sample config.ini
jmhobbs@katya:/var/www/lifestream/protected/config$ vim config.ini

[general]

;Database connection settings
db.adapter=PDO_MYSQL
db.host=localhost
db.username=lifestream
db.password=supersecretpassword
db.dbname=lifestream

;Security
security.cookie = kg89y6gbval

;Caching
;cache.content = 1
;cache.metadata = 1
;cache.path = /tmp/cache/

;Web deployment settings
web.host=lifestream.velvetcache.org
web.path=/
web.redirect = 1
web.timezone=America/Chicago
jmhobbs@katya:/var/www/lifestream/protected/config$

The Fruits of Our Labor

At this point your lifestream should be working, open a browser and take a look.

Now we need to change our password, so go to the admin page http://www.example.com/admin and log in. The default username and password are admin and storytlr respectively. You can find that under Configure » Password.

There are lots of options to browse through, and I won’t cover them all, but I’d like to run through setting up a source. Sources are the core of lifestreaming, and there are lots of options to choose from. In the admin interface go to Sources and click Add next to a source you want to add, I’ll use Delicious in my example.

This should present you with a form asking for some information. Each source is going to be slightly different, but all should be pretty easy to understand. Fill that out and it should import what it can from that source.

There you have it! Add some more sources until your lifestream really fleshes out.

Keeping Current

The very last step, which is often overlooked, is updating your sources. The primary means for this is the PHP script protected/tools/update.php. This must be run from the command line with the name of the user to update. Here’s an example:

jmhobbs@katya:/var/www/lifestream$ php5 protected/tools/update.php admin
Memory usage on startup: 4997940
Memory: 5351904
Memory: 5351904
Updating source delicious for user admin [0/2] (5).... found 0 items
Updated 1 out of 2 sources in 1 seconds.
jmhobbs@katya:/var/www/lifestream$

It’s common to set up a cron job to handle these updates. It’s often important to put in full paths for your cron jobs. This example will update my sources every 10 minutes. You can learn more about cron here.

jmhobbs@katya:/var/www/lifestream$ crontab -e
MAILTO=jmhobbs@towncommons.com
# m h  dom mon dow   command
*/10 * * * * /usr/bin/php5 /var/www/lifestream/protected/tools/update.php admin
jmhobbs@katya:/var/www/lifestream$

Storytlr has lots more features and configuration options, I would encourage you to browse around and make your installation suit your taste. To see an example of a fully customized Storytlr installation, you can visit mine at http://lifestream.velvetcache.org/

Going Further

Storytlr is rich with opportunities to contribute. It’s fairly young and has lots of finicky little things to figure out, and it can always use one more plugin. Lots of stuff is in the works, including a much simpler installer which will make most of this article obsolete!

Documentation is in need of some TLC, and more eyes on the bug reports would be great.

To get involved visit the Storytlr Google Code site or hop onto Github and fork the project. Finally, you can also join us on Freenode IRC in #storytlr.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Meet Storytlr

To get started, register an @Anywhere application and get an API key. Then plug this snippet into your page:

<script src="http://platform.twitter.com/anywhere.js?id=YOUR_API_KEY&v=1" type="text/javascript"></script>

Now you can begin using any of the following features:

Auto-linkification of Twitter usernames

This is a convenient way to link Twitter usernames on your site to the appropriate user’s profile page on Twitter. The most basic usage looks like this:

<script type="text/javascript">

  twttr.anywhere(function (T) {
    T.linkifyUsers();
  });

</script>

Hovercards

A Hovercard is a small, context-aware tooltip that provides access to data about a particular Twitter user. It looks like this:

To enable hovercards on a page:

<script type="text/javascript">

  twttr.anywhere(function (T) {
    T.hovercards();
  });

</script>

Follow buttons

The feature name pretty much says it all. Let people follow Twitter users from your page. To enable it for user sant0sk1 inside a span with id of `follow-me`:

<span id="follow-me"></span>
<script type="text/javascript">

  twttr.anywhere(function (T) {
    T('#follow-mei').followButton("sant0sk1");
  });

</script>

The buttons look like this:

Tweet Box

Let Twitter users tweet from inside your webpage or web application. An example of using this on a div with id of `tweetbox`:

<div id="tbox"></div>
<script type="text/javascript">

  twttr.anywhere(function (T) {
    T("#tbox").tweetBox();
  });
</script>

User login & signup

This feature allows users to perform some of the authentication-required activities like following users and tweeting from your page. It uses OAuth and provides authComplete and signOut callbacks that you can hook into. It’s more complicated than the others so we won’t provide an example here.

Try it!

@Anywhere looks like a solid API that can provide immediate advantages over other solutions. If you need quick, easy and official Twitter integration on your site we highly recommend trying it out. Start with the official documentation from which we derived much of this overview. Then you can move on to the full API documentation which is (at the time of posting) in a preview state. Enjoy!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

A Brief Overview of Twitter’s New @Anywhere API

One fun (and useful) example of a Rack middleware is a Firebug logger written by Simon Jefford for the CodeRack competition. This middleware allows you to send arbitrary messages directly to Firebug. Why? Since you’re already debugging much of your Rails app in a browser anyway, sending debug output to your browser’s console (instead of tailing a log file) makes a lot of sense.

NOTE: FirebugLogger plays nice with WebKit’s Web Inspector as well.

Simon also released a Rails plugin that you can install to set up the middleware for you, but it’s more fun (and informative) to set it up yourself. Here’s how:

Setup

The goal is to be able to send arbitrary messages to Firebug from any controller or view.

Rails autoloads (and namespaces) any code placed in the lib directory, so that is where we’ll place our FirebugLogger code. Grab the code from my gist, which is a fork of Simon’s original with minor improvements, and place it inside your Rails app in:

lib/rack/firebug_logger.rb

Rails will load the code for us, but we need to manually activate the middleware. Since this bit of code is only useful during development, we’ll load it up in that environment only.

# config/environments/development.rb
# ... other stuff ...
config.middleware.use ::Rack::FirebugLogger

Using FirebugLogger

Using the middleware is pretty straight forward. It will process an array of arrays, each of which has a log level and a message. Add a single line like the one below to an existing controller action and load up the page:

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def index
    @posts = Post.all
    request.env['firebug.logs'] = [[:info, "hello from rack!"]]
  end
  # ... other actions ...
end

Open Firebug and you should see “hello from rack!” glaring back at you. You can do the same thing in views:

# app/views/posts/index.html.erb
<% request.env['firebug.logs'] = [[:warn, "inside a view!"]] %>

Adding a Helper

Using the logger like this is a bit tedious, and it’s not easy to create multiple messages for a single request. Let’s wrap the functionality up into a method that we can call. This method should be placed in the application controller so that all other controllers inherit it.

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
# ... other stuff ...
helper_method :firebug

  private

  def firebug(message,type = :debug)
    request.env['firebug.logs'] ||= []
    request.env['firebug.logs'] << [type.to_sym, message.to_s]
  end
end

This method will initialize an empty array the first time it is called and then push new messages on to the array on subsequent calls. Notice that it calls to_s on the message variable before passing it on. This means you can send the method a string or any object that responds to to_s and it will just work. Specifying a log type is optional, the method is private and it is explicitly added as a helper_method so that you can access it from views as well.

Now writing logs to Firebug is as easy as:

firebug "woop woop!"
# optionally specify a log level
firebug "it's a trap!", :warning

Here are a few ideas of helpful messages to send to Firebug:

# inspect the attributes of an object
firebug @posts.first.inspect
# dump the session
firebug session
# check a user's roles
firebug current_user.roles.inspect

I highly encourage you to try this in one of your Rails apps. It has proven a useful addition to my toolkit. Let me know how it works for you by leaving a comment!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Set Rails Logging on Fire

print_r( $post );
die();

One the statements are in place, the programmer refreshes the page and looks at the source to view a nicely indented array or object. Next they comment out the print_r and die statements, change some lines, and try the code again. If it fails, they are back to square one and in go the print_r,echo and die statements so the brutal cycle can begin again.

We know these methods partially work (who hasn’t done the above during a PHP project!), but we also know they are less than optimal. Is there a better way?

WordPress Debug Mode

WordPress offers quite a few ways to enable and customize a debug mode while developing. To enable debug mode, you want to define WP_DEBUG as true in your wp-config.php. Here is the complete code block I suggest you use. We will look at the individual parts shortly. Place this in your wp-config.php file after the lines that define the database variables. Be sure to change development_user to be your development database user name:

@ini_set('display_errors',0);
if( 'development_user' === DB_USER ){
  define('WP_DEBUG',         true);  // Turn debugging ON
  define('WP_DEBUG_DISPLAY', false); // Turn forced display OFF
  define('WP_DEBUG_LOG',     true);  // Turn logging to wp-content/debug.log ON
}

display_errors

The first line in our code block turns off the display of errors, regardless of php.ini or .htaccess settings to the contrary. This is important because though WordPress can force the display of errors to be on, it won’t force them to be off if display_errors is already turned on.

Testing for local vs. production

There are probably fifty ways of doing this part, so use a method that works for you. In my environments, my local development database rarely if ever has the same user name as the production database. Simply checking what I expect the local user name to be against what is defined in DB_USER is a simple way of knowing if the files are on the development or production servers.

WP_DEBUG

This is the most important constant as it determines if WordPress will use any of the other debugging constants. Thankfully it is quite simple. If set to true, debug mode is turned on. If undefined or set to false, debug mode is kept off.

WP_DEBUG_DISPLAY

This constant confused me at first, but it is actually quite simple. If set to true, it will override the current display_errors configuration setting and turn it on. However, if set to false it will not turn off display_errors. This setting is simply an override. This is the reason we turn display_errors off before setting any of these constants.

Set this constant to true if you want to see errors displayed in your browser when they occur. Keep in mind this will sometimes complicate errors because once at least one error has been written to the page, all redirect requests will fail. This is because the header information can no longer be modified once content is sent, and a displayed error counts as content.

WP_DEBUG_LOG

This constant is the whole reason I found the WordPress debug methods so helpful. Set this constant to true and WordPress will set up PHP to write to an error log in wp-content/debug.log. Sadly you can’t specify a different file location that is not in the content folder, but at least you know where it is!

Note: because this is written to a public directly, be extremely careful not to upload the log by mistake. Additionally, if you run WP_DEBUG on a production server, do so only for immediate troubleshooting then turn it off and remove wp-content/debug.log.

Leveraging WP_DEBUG

In addition to PHP errors being sent to debug.log we can also send our own output using the error_log PHP function. The only problem with this, is even in production mode your errors will still most likely be written to a PHP log; it just won’t be debug.log. Because of this, its a good idea to provide a wrapper function to handle the logging for your theme or plugin.

Place the following code in your functions.php in your theme, or in the plugin file for your WordPress plugin:

if(!function_exists('_log')){
  function _log( $message ) {
    if( WP_DEBUG === true ){
      if( is_array( $message ) || is_object( $message ) ){
        error_log( print_r( $message, true ) );
      } else {
        error_log( $message );
      }
    }
  }
}

Feel free to expand on this function if it doesn’t exactly meet your needs, but the concept is simple: Centralize all your log calls to use your custom function. Then, in that _log function, only output the message if WP_DEBUG is set to true. There is no reason to test if WP_DEBUG has been defined because as soon as wp-settings.php is processed, WP_DEBUG will be defined, even if it wasn’t already defined in wp-config.php.

This particular _log snippet will call a print_r on arrays and objects passed to the function for simple debugging.

Trying it Out

If you have followed these steps, you can run a quick test by adding these lines into your header.php file in your theme folder:

_log('Testing the error message logging');
_log(array('it' => 'works'));

After refreshing your page once, you should see a newly created debug.php file with a few lines of output. Use any log viewing utility that supports tailing the file for maximum productivity. On Mac, Unix and Linux systems, you can use this command from the main directory of your site:

tail -f wp-content/debug.log

More Solutions

If you are looking for a more interactive console for debugging, be sure to look at our review on the WordPress Console.

What about you? If you didn’t already know about this built in WordPress feature, what methods did you come up with to make debugging WordPress easier? Please leave us your tips in the comments below!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Simple Debugging with WordPress

I was really happy to see so much participation in this giveaway! After seeing how many people entered, I was feeling really bad that only one of them would leave with a copy of the book. I talked to Cody, and he graciously provided two more free copies so we can award a total of three books! I randomly picked three winners (using Random.org) and am happy to announce the following winners:

• Brad Rhine (truetech.org)
• Mila
• Geoff Woodburn (woodburndesigns.com)

Book Review

Late in 2009, Cody Lindley published a PDF book on jQuery titled jQuery Enlightenment. Today we are presenting our view of the book as well as offering a free copy to one lucky reader.

About The Author

Cody Lindley is a core team member of the jQuery project, and the original developer of the well known Thickbox plugin for jQuery. I had the pleasure of meeting and listening to Cody present at the jQuery Conference last year in Boston. He describes himself on his website:

Today I am a Christian, husband, son, brother, professional Web developer, and outdoor enthusiast. I spend a majority of my time sleeping and working, but who doesn’t? In between the daily routines of the average American, I desire an existence that entails a relationship with God, my family, and nature. I would like to consider myself a bookworm (a novice theologian at best), but truth be told, I simply enjoy watching movies and playing xBox way too much. I guess I also have the luxury of pursuing my profession as a personal passion. Yes, I often work even when I am not at work.

Overview

jQuery Enlightenment is a different type of book than I am used to seeing in the tech field. A list of what it is not might help shed light on what I mean. It is not documentation, a tutorial/walkthrough, or just conceptual material. jQuery Enlightenment is an amazingly clear montage of principals and code samples every jQuery developer needs to know grouped by topic. Cody covered topics both basic and profound throughout the pages of the book.

I consider myself quite adept at using jQuery, but found myself constantly amazed at the things I was learning while reading this book. Cody says it picks up where the jQuery documentation leaves off. I can see his point, but I think this book would be a better starting place for a new jQuery developer than even reading through the jQuery API site.

Pros

Code Samples

Code samples make up over 70% of the book (rough estimation). The book is not written in an editorial way at all. It is about presenting what you need to know, demonstrating it with an example, and moving on. For this reason the book is an extremely fast read and perfect for reference on a day to day basis.

Possibly one of the neatest features of the book itself is that (almost) every code sample provided in the book has a link to the same code on JSBin.com. JSBin is an online playground for testing and demonstrating JavaScript, HTML, and CSS technologies. jQuery Enlightenment isn’t a flat reading experience, it allows you to immediately jump in and play with the code samples until everything makes sense.

Additional Notes

Many of the topics are followed by a little box titled ‘Notes’. I am glad Cody didn’t choose some cheesy title for these boxes, but ‘Notes’ really does not sum up what they provide. You will find many undocumented (or hard to find) tips and tricks about the finer points of jQuery in these boxes. Skip over them at your own peril!

No Fluff Quality

Cody doesn’t waste any time on any of the topics presented in the book. The pattern used is simple: explain, demonstrate, move on. I personally will be using this book not just for reference, but for a quick read-through every few weeks to keep my jQuery senses sharp.

Cons

You will be hard pressed to find something negative to say about this book, and it wasn’t until I reached the end that I had one complaint about the content. The chapter on Ajax (Chapter 11) was far too short. Perhaps this is because the documentation is very clear, but I still wanted to learn more and have more examples to glean from. Perhaps the second edition of the book (which will cover jQuery 1.4) will provide more detail on jQuery’s AJAX implementation and associated methods.

Conclusion

I am confident new users and seasoned users alike will find much to learn in jQuery Enlightenment. After reading the book, my only concern is that I won’t remember all of the cool things I learned while reading it!

Win a FREE Copy!

Next Wednesday we will be selecting a winner to receive a free copy of jQuery Enlightenment. Entering the competition is easy!

Head over to jQuery Enlightenment and quickly look through table of contents. Then, leave a comment below telling us what chapter you think you would learn the most from if you were to win the book. Only comments referencing one of the actual chapters in the book will be eligible to win. We will randomly select a winner next Wednesday and announce it here on the site.. Sorry, but the contest is over!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

jQuery Enlightenment: Book Review and Giveaway (Winners Announced!)

The Problem

As a developer, you are rapidly building your newest web creation. You start with the HTML, knowing full well you don’t have the hyperlinks you will need to complete the design. Nonetheless you put in:

<ul id="nav">
   <li><a href="/">Home</a></li>
   <li><a href="">About</a></li>
   <li><a href="">Contact</a></li>
   ...
</ul>

What seems like a long time later, you get to the point where you finish up your site for demoing or production. How do you quickly find all those empty links? Well, you could use a link checker… or, just use CSS3!

CSS3 Solution

Just paste this line to the end of your last included CSS file for a quick visual display:

/* Find all links where an href is not provided */
html body a:not([href]), html body a[href='']  { background: red !important;}

Then open your site in modern browser that supports CSS3, and any empty link now has a background of red. Edit your HTML, and check the page again. When all the links are fixed, none will have a red background!

You can see for yourself by checking a quick demo:
Standard Page | Page With CSS3 Link Checking

Bonus: Testing Progressive Enhancement

For mission critical functionality it is generally good practice to have a fallback for non JavaScript users. To test if your page has any JavaScript only code, add this rule to your CSS file after the rule we just added:

/* Find all links where the href = # */
html body a[href='#'] { background: yellow !important;}

Next, disable JavaScript in your browser (In Firefox and Safari it is an option in your preferences.).

Now, any of those links you cleverly enhanced with JavaScript, but forgot to add a valid fallback URL, will show up with a yellow background. If an item truly has application only when JavaScript is enable, you should consider adding it dynamically with JavaScript.

Variations

As a leftover vestige from IE6 days, many developers use href='#' so signify an empty url (So the :hover pseudo selector will still work). If this is your case, you have two options: 1) Change your style going forward and use href='' to signify an empty URL and href='#' for JavaScript enhanced links. or 2) Use only the second CSS3 rule and change the color to Red.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Unconventional: CSS3 Link Checking

This is accomplished by using the prototype object. Each native object in JavaScript includes a prototype object. Don’t get this confused with the PrototypeJS framework… the prototype object is a way to extend all objects that have inherited from the base object you extended. You can easily extend the prototype object by adding functions to it like this:

Object.prototype.functionName = function(){

}

You can then call them directly:

var obj = new Object();
obj.functionName();

There are a number of advanced uses of the prototype object, but this is the important thing to remember: any function added to the prototype of an object is available on any object that inherits from it. So if you extend the prototype on the Number object, all numbers will have access to the new function; if you extend the Array object, all arrays can access your custom function. You only use the prototype.functionName syntax when declaring the new function, not when calling it.

Enough theory, lets see some (somewhat) practical uses:

Do you find yourself capitalizing a lot of words in a particular JavaScript app? Just add a capitalize method to the String object.

String.prototype.capitalize = function(){
  if(this.length == 0) return this;
  return this[0].toUpperCase() + this.substr(1);
}

Now you can capitalize any string in your application by calling "lower".capitalize() and get "Lower" in return. Since it returns a string, you could chain it with any other function you can execute on a string.

Do you always find yourself forgetting you can call Number(”25″) to turn a string into a number? Just add a toNumber() function to the String prototype:

String.prototype.toNumber = function(){
  return Number(this);
}

If you need to split large JSON arrays into groups of two or three each, you could extend the Array object like this:

[js]
Array.prototype.inGroupsOf = function(num){
	var ret = [],
		length = this.length,
		groups = Math.ceil(length / num);

	for(var i = 0; i < groups; i++){
		var start = i * num,
			end   = start + num;

		ret.push(this.slice(start, end))
	}
	return ret;
}

Now calling inGroupsOf(3) on any Array would return that same array split into as many parts as needed to ensure no group has more than three items in it.

There are a number of objects you can extend, but the ones you will use the most are String, Array, Object, Number, Date. One trouble area you might face is calling methods on numbers. The following example will fail:

Number.prototype.to_s = function(){
  return this + "";
}

25.to_s();

The prototype function is correct, but the way we called it is wrong. There are two ways to call our custom functions on numbers:

var n = 25;
n.to_s(); // Returns "25"

(25).to_s(); // Also returns "25"

Think Start, Not End

Its important when deciding what object to extend that you focus on what object type you are starting with, not so much which type you plan on ending with. For instance, if you wanted to extend an object to easily parse Twitter date strings you would not extend the Date object. You would extend the String object, and your function would return a Date object.

Load Your Extensions First

It is normally a good idea to load these extensions prior to any other library, including jQuery. Anytime you extend the prototype object, the new method is instantly available to all objects of the same type or any object that has inherited from that type. However, since you want to be sure your methods are always available, you guarantee their availability by loading them first.

How to Group The Extensions

Naming your files Prototype.Date.js and Prototype.Array.js is an easy way to keep all your extensions in one part of your JS folder, and easy to access during development. If you follow this method, you would simply put Date.prototype methods in the Prototype.Date.js file, etc. This starts to break down when you have parallel functions. You might have a toDateFromTwitter() method on the String object and a toTwitterFromDate() method on the Date object. Putting these in separate files might not make sense. At that point, you should put both these extensions in a file named TwitterHelpers.js or something similar. Obviously use what makes sense to you and works with your flow.

Don’t Bloat

Just because you write 500+ awesome Array extensions in the next 2 years, does not mean you need to include them on every project. Be sure to only use this technique when it makes sense for the project and when it helps clean up your code.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

JavaScript Can Learn: Now Teach It Tricks!

Mini-series Overview

• Part 1: URL Routing and Directory Setup
• Part 2: Templating
• Part 3: Database Interaction

You can download all the files put together during this three part series here:

I’m not going into detail about how to create an ORM or ActiveRecord clone. We are just going to write a simple helper class to setup our connection and query. Also I’m going to assume you know how to create a database and table in the database.

I have created a database called “peanut” and created table:

users:
+----------+--------------+------+-----+---------+----------------+
| Field    | Type         | Null | Key | Default | Extra          |
+----------+--------------+------+-----+---------+----------------+
| id       | int(11)      | NO   | PRI | NULL    | auto_increment |
| username | varchar(255) | NO   |     | NULL    |                |
| password | varchar(255) | NO   |     | NULL    |                |
+----------+--------------+------+-----+---------+----------------+

In this example we are going to use Mysql and the php mysql_ methods. So break open system/database.php and drop the following in:

<?php

// Here is where we are setting up a simple wrapper class around mysql
// functions just to make it a little more convenient.  Our models will
// simple extend our database class and simplify making queries just a bit.
class Database
{
	protected var $connection;
	// Every time you instantiate this class you are going to create
	// a new connection to the database.
	public function __construct()
	{
		// First we setup up a nice little connection to the database,
		// make sure you use your connection information.  If the
		// connection fails we just die with the error.
		$this->connection = mysql_pconnect("localhost", "root", "somepassword") or die("MySQL Error: " . mysql_error());

		// And let's tell mysql which db we are going to use.
		mysql_select_db( "peanut", $this->connection );
	}

	// This is just a helper function to help out against
	// possible sql injection attacks.
	public function escapeString($string)
	{
		// we call mysql's 'cleaning' function on strings
		// just to make sure we get a little safer item to query
		// with.
		return mysql_real_escape_string($string);
	}

	// Here we will query the database with the passed query string,
	// build up an array of objects and return them, simple enough.
	public function query($qry)
	{
		// Here we make our query and set the result to a $result variable
		$result = mysql_query($qry) or die("MySQL Error: " . mysql_error());

		// Create a container array variable to hold all of our result objects.
		$resultObjects = array();

		// This might look weird, but all we are doing is saying,
		// While you are still getting results, please put the next
		// result into the next spot on my array.
		while($resultObjects[] = mysql_fetch_object($result));

		// Now we just return our array that has all our result objects in it
		return $resultObjects;
	}

	// Here we add a simplier method for handling INSERTs and UPDATEs since
	// they do not return a result set.
	public function execute($qry)
	{
		$exec = mysql_query($qry) or die("MySQL Error: " . mysql_error());
		return $exec;
	}
}
?>

So we have our database class in place and ready to use, now we just need to require it in the index.php like we did the others, so pop that bad boy open and after the template require, do one just like it but for the database.php

Now let’s crack open actions/helloworld/models.php and let’s write a simple addUser and getAllUsers method to it. We are going to make our model a class as well so that it can extend our Database class that we wrote.

Here are the guts:

<?php

// All of our database back-and-forth will be handled in our models file
// Don't be mistaken, this is no where close to an ORM (Object Relational Mapper)
// it's just simplified database access.

class myModel extends Database
{
	// When our model is instantiated we just need
	// to also instantiate our parent class (Database)
	// so it knows to make the connection to the database.
	public function __construct()
	{
		// We just call the __construct of Database class.
		parent::__construct();
	}

	// addUser will use the execute method of Database
	// since we are inserting a value and not expecting
	// anything in return.
	public function addUser($username, $password)
	{
		// Here we use that little cleaning method we
		// wrote to make our strings pretty and make sure
		// they will play nice with mysql
		$username = $this->escapeString($username);
		$password = $this->escapeString($password);

		// We execute our insert and if it worked $success
		// will be true else it will be false.
		$success = $this->execute("INSERT INTO users (username, password) VALUES ('{$username}','{$password}')");

		// We return $success to inform our page action that it has or hasn't worked.
		return $success;
	}

	// This method does just what you think it would.
	// We are going to use the query function because
	// we are expecting data back, then we are just
	// going to return the array of user objects.
	public function getAllUsers()
	{
		// Populate the $users variable with the results of our query
		$users = $this->query("SELECT * FROM users");

		// Now we return our results
		return $users;
	}
}
?>

Now we need to change our actions/helloworld/actions.php mypage page action to:

<?php
// We need to include our models file so we can access the database
require(PEANUT_ROOT_DIR . 'actions/helloworld/models.php');

// We simply define the function (the second item in our request url)
// making sure it is the same name as the one in the url.

function mypage()
{
	// Let's do some database work!
	// Here we are going to instantiate our model
	$model = new myModel();

	// Now let's add a user
	// On a funny note, if you keep refreshing it will add this
	// user over and over in your users table so your getAllUsers call
	// will result in a list that grows by one each time.
	$model->addUser("wess", "password");

	// Now let's fetch all of our users and put them in our users
	// variable.
	$users = $model->getAllUsers();

	// Let's create a new template object and pass it the path to our template
	$template = new Template("helloworld/templates/helloworld.php");

	// I bet you want to display a table in your template with all your newly
	// created users. So let's do it

	// That's write we use the same set command, and it will set our array of users
	// to our template variable $users, and since php is our template language
	// it's real easy to print them to the screen.
	$template->set('users', $users);

	// Set our page variable "title" with the value "Hello World"
	$template->set('title', 'Hello World');

	// Set our page variable "message" with our little message
	$template->set('message','This is my first message for my template');

	// Now we can call render and return it to dispatch to
	// display in our browser
	return $template->render();
}
?>

So now you are handing all your users from your database to the template, so let’s display them. Change your actions/helloworld/templates/helloworld.php file to:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-type" content="text/html; charset=utf-8">
		<title>My PEANUT Page</title>

	</head>
	<body>
		<h1><?php echo $title ?></h1>
		<p><?php echo $message ?></p>

		<h2>Users:</h2>
		<table>
			<thead>
				<tr>
					<th>ID</th>
					<th>Username</th>
					<th>Password</th>
				</tr>
			</thead>
			<tbody>
				<!--
					Here we are going to use native php foreach look
					to create each row of the table with our list of users.
					Notice how the foreach is done with a : and surrounding php tags.
				-->
				<?php foreach($users as $user): ?>
					<tr>
						<td><?php echo $user->id ?></td>
						<td><?php echo $user->username ?></td>
						<td><?php echo $user->password ?></td>
					</tr>
				<?php endforeach; ?>
			</tbody>
		</table>
	</body>
</html>

Now if all went well, you should save all your files and open up: http://mywebapp.local/helloworld/mypage and see all the users that you added in a table.

So you have created a template class, url basic url routing, simplified database access, and a page action. You have all the core basics of a PHP Framework at your hands now. This is just for a starting point or foundation of understanding, please do not use this in a production environment.

I have really enjoyed writing this and I hope you learned something from my rambling! The source code is available for download at the top of this article.

Take care,
Wess “Wattz”

Updated October 26, 2009: Thanks to Alex and Ian for spotting some errors in the code and supplying the fixes. The code examples have been updated to reflect the changes as has the ZIP file.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Roll Your Own PHP Framework: Part III

Below is a screen capture of the final gallery. To see the gallery in action, click here

This tutorial assumes that you have textpattern installed and ready to go.
( Download the latest version of Textpattern here: http://textpattern.com/download)

Galleriffic

This gallery is based on Galleriffic, a jQuery plugin for rendering fast-performing photo galleries. This is adapted from http://www.twospy.com/galleriffic/ to work with textpattern so you (and your clients!) can easily update the gallery. In a nutshell, the gallery works by associating image id #s with a specific article. The article form gallery and article_image_form work together to render the article in the form of all of the associated images (in their thumbnail format) to appear as an unordered list on the left, while the full version of the current image appears on the right. All that is necessary to add or change images, is to change the numbered list appearing in the advanced options on the left of the article containing the images. So easy once implemented, even a client that doesn’t speak nerd can add, subtract or change their own images.

Upload the files

Upload both of the galleriffic files included in the files folder of the download, by uploading them through the Content > Files tab. I modified the jquery.galleriffic.js file so that the pagination does not appear above the thumbnails. Should you wish to further customize the gallery, I do suggest checking out the original Galleriffic demo.

Install the relevant plugins

Install the following plugins (these are included in the Plugins folder in the download):

• upm_image by Mary Fredbord – more powerful image display
• ebl-image-edit by Eric Limegrover – introduces advanced image editing functionality

(I have had technical issues with v.2 of this plugin, so I continue to use v1. Both are included in the plugin folder.)

ebl-image-edit is great for sizing/creating thumbnails on the fly, without having Textpattern automatically centre the thumbnail. It is not essential to this tutorial, but it’s very very handy!

Set up your forms

You can find these forms in the forms folder in the download.

gallery

Create a new form called “gallery” and choose “article” for the type:

<txp:upm_article_image form="article_image_form" wraptag="ul"
class="thumbs noscript" />

article_image_form

Create a new form called “article_image_form” and choose “misc” for the type:

<li><a href="<txp:upm_img_full_url />" title="<txp:upm_img_caption />" class="thumb"><img src="<txp:upm_img_thumb_url />" alt="<txp:upm_img_alt />" /></a>

<div>
<div><txp:upm_img_alt /> </div>
<div><txp:upm_img_caption /></div>
</div>
</li>

If you don’t want captions, delete the whole caption div.

Basically we have taken this code from galleriffic:

<ul> <li> <a href="path/to/slide" title="your image title"> <img src="path/to/thumbnail" alt="your image title again for graceful degradation" /> </a> <div> (Any html can go here) </div> </li> ... (repeat for every image in the gallery) </ul>

and modified it so the article forms generate this code from the image numbers that we will associate with the gallery article. We’re basically saying, “take the images associated with this article, put the thumbnail versions of those images on the left with these classes and this formatting, and put the full version of the selected image on the right.” Huh? Just follow along, I promise it will all make sense soon…

Set up your page

In the pages folder I have included a template for this gallery page (gallery.html). Create a new page template in textpattern: Presentation > Pages. At the bottom, “copy page as”, name it gallery, and click “copy.” Make sure whatever section you are using for the gallery is in fact using the gallery page as its template. At the bottom of the page you will notice the galleriffic script. This is where you can make adjustments to sizes, number of thumbnails, etc. In this example I have set a limit of 9 to the thumbnails. At the bottom of the page, near the top of the script, it looks like:

numThumbs: 9,

Set up your style

I have created a master style sheet that incorporates some of the Textpattern defaults as well as galleriffic specific css. Copy the content from the screen.css file provided in the Styles folder and paste it into your default styles tab under Presentation > Style.

Add your images

Go ahead and start uploading some images, and create some thumbnails. Make sure your images are all using the same size of thumbnail. Take note of the image ID numbers, as that is what you will use to call your images into the article. Make sure to add the Alt text and Caption when you upload, as this is what will appear to the left of the main image (unless you opted to delete the captions).

Create a new article called gallery. On the left hand side, click advanced options, and enter the ID numbers of the images you want to appear in the gallery, separated by commas. Make sure you post the article to the gallery section, or whichever section you have set up to display the gallery, and click publish. Your article should look something like this:

View Site. You should notice that the images have been automatically formatted into thumbnails on the left, with the first one appearing in full on the right. That’s it! You have a galleriffic gallery integrated with Textpattern. Play around with the html, settings, scripts and CSS to customize it to suit your own needs.

If you have any questions, suggestions, or requests for future articles, please do not hesitate to leave a comment.

Thanks, and happy coding!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Easy to update thumbnail gallery using Textpattern and Galleriffic