Andrew Woods Seattle Web Developer

Application Architecture on Localhost

You’re ready to begin development on your project. Now what? Since you are a professional, you need to setup your environment not just a for a single project, but the many projects to come. Sure you could just create a folder on your desktop, and start hacking together an html file from scratch. but I’m gonna show you a better way. The solution I’m going to show you will use a local webserver. I’m using Apache, and you should be too. If you’re using PHP at all, you have to use a web server.

Filesystem Setup

It should be easy to get to, and easy to manage. Lets start by going to root of your filesystem either in Finder or the Terminal, and create a directory ‘www’. This will contain everything web related. In the ‘/www’ is where you begin to organize. I suggest by type first. Think for a minute about the kinds of things you’ll need – websites, log files, software from third parties like jQuery, Smarty, BluePrint – are a few of the basics. Create a directory to hold each of these type of information. ‘libs’ for the 3rd party libraries, ’sites’ to contain each of your client web projects, and ‘logs’ to hold the log files that are associated with each of your websites. So your structure should look like the following:
  • www
    • libs
      • php
      • js
      • css
      • sql
    • logs
    • sites
In the libs directory I suggest one more level of organization – language name. That way your PHP, Javascript, Ruby, and CSS all separate. Then the only other thing to do is to make sure you include the version number of any libraries you extract into here. e.g. /www/libs/{lang}/{software-1.0} Now you have one place on your system to store all your software libraries. When you create your website projects , copy the desired libraries to your /www/sites/{project} directory. In my ‘/www/sites’ directory, I use project names, which is typically the domain name minus the top-level domain. Generically it looks like ‘/www/sites/{projectname}’. So my Mastodon Labs project is in the directory ‘/www/sites/mastodonlabs’, which lives on the internet at mastodonlabs.com. If you know that you’ll have a client where you work on multiple projects, you could use the client name as a level of organization e.g. /www/sites/{clientname}/{projectname}. Now that your structure to for organizing projects is intact, what should go into the project? a folder for documentation, one for sql scripts, one for the website root, and one for your framework (if you use one). I use CodeIgniter
  • /www/sites/foobar
    • ci_system
    • docs
    • site
    • sql
You may be wondering why the directory ‘foobar’ isn’t the site root. There are multiple reasons. Most importantly, it’s a best practice not to have any config files in the document root of your website. This helps keep your website secure by design. Every framework has at least one, usually containing database information. So a user should never be able to visit a URL like http://foobar.com/system/config/database.ini.  While there are techniques to hide such directories, it’s just best not to put them in the document root. ‘docs’ is a good place to keep notes about the project, a list of things to do for the current project, special instructions, list of notes for the specific versions of the site. For projects that require a database, it’s also good to have a set of SQL scripts that build/modify your database structure. For that purpose, you use the ’sql’ directory. Since all these directories are contained in one project directory, it’ll be easy to manage them all in a version control system. We’ll talk about that in the next post, but for now, let’s focus on your Apachefgv configuration setup.

Apache Configuration

When Apache starts up, it parses it’s config file httpd.conf. On my mac (OS X 10.4), this is located at /etc/httpd/httpd.conf. While it’s possible to have all your configuration in one big file, I use a second file called vhosts.conf which is read in with an include statement. 
Include /etc/httpd/vhosts.conf
This file holds all the virtual hosts (read: websites) configurations on your machine. At its most basic, this file is responsible for mapping the url of the website to the corresponding directory in the filesystem. There’s a lot it you can put here, but for a simple websites this is all you need. When you’re doing your local development, you only need to worry about one hostname – localhost. You’re probably wondering “but how do we access more than one website?”. The answer is ports. By default, websites are served on Port 80. It’s possible to have your web server listen to more ports for requests.  If you want to listen to port 3000, you would put this statement in httpd.conf 
Listen 3000
This gets to you have way there. Now apache will listen to requests on that port. When it gets a request, what should happen? First add the following to your httpd.conf, if its not already in there. 
NameVirtualHost *
Now you need to tell it which virtual host you want to receive it. go to your vhosts.conf file and add the following lines: 
<VirtualHost *:3000>
    DocumentRoot /www/sites/foobar/site
    ErrorLog /www/logs/foobar/error.log
    CustomLog /www/logs/foobar/access.log common
</VirtualHost>
Now you just stop/start apache so that it reloads with your new configuration. Be aware that the /www/logs/foobar directory needs to exist before you restart Apache, otherwise Apache will not restart successfully and it will fail silently (you wont see an error message). Apache will create the log files if they don’t already exist. On my system, I use /usr/sbin/apachectl stop to shutdown the server, and use /usr/sbin/apachectl start to start it up. Thats it. Now  you see your website in your browser when you load http://localhost:3000 Happy Computing!

Barcamp Seattle 2009 Schedule

Some of you may be wondering what the schedule is for Barcamp. Friday Night there is a kickoff party/book signing at office nomads . Tara Hunt (@missrogue) will be selling and signing copies of her book “The Whuffie Factor“. Saturday morning at 10am the doors open for Barcamp Seattle. People will mingle for a bit and around 10:30 we’ll make announcements and let people signup themselves up for sessions on the board for the day. Everyone who shows up, has the opportunity to run a session. At 5pm, the sessions will wrap up for the day. Afterwards, we’ll head over to the Red Door, which is just a couple of blocks away. On Sunday, another set of session will start at 10am  and will wrap up at 1pm.

Build Your Portfolio With CodeIgniter

You know about web design, and you’ve decided to use a PHP framework to get you started. With the availability of so many great open source software projects out there – like Zend Framework, CakePHP, and Drupal, Wordpress – it’s easy to be overwhelmed. Each of those projects has their merits and drawbacks, but my favorite is CodeIgniter – it’s powerful, lightweight, and flexible. There are several  tutorials on CodeIgniter. Here’s a introductory video tutorial that uses PHP4 syntax. The things this tutorial uses PHP5 syntax.   For the sake of  brevity, I’m going to assume you’ve already installed it. I’m going to explain how to build a portfolio site using CodeIgniter. Lets think about the typical layout of a portfolio – homepage, about, contact, services, work – most of which are probably static pages. The “work” page could be database driven, depending on how comfortable you are using databases. For this post, I’m going to assume its static, and leave it as an exercise for you to make it dynamic. Let’s get started, shall we?! Here’s how CodeIgniter reads it’s urls by default: example.com/class/function/ID You want your URLs to be simple. The homepage should be “/”, contact “/contact”, about  “/about”, and services “/services. For the moment, we’re not going to consider the Work pages. If you create your controllers using the default URL setup, you’ll have 4 controllers to start. In each one of those, you would create a method called index(). This is the method that gets called automatically when you don’t specify a 2nd segment for your URL.  While that will work, there is a better way, that will makes things easier for you. Lets  start by opening your favorite text editor, and create a file called Main.php. In this file we’ll create your controller. it should look like this: 
<?php
class Main extends Controller {
    public function __construct(){
        parent::__construct();
    }

    public function index(){
        echo "Homepage";
   }
}
?>
Save this to your CI_INSTALL/application/controllers directory. To run go to example.com/index.php/main where example.com is your site. But wait, we wanted to call it ‘/home’ . To make this happen we’re going to use a magical feature of CodeIgniter – routes! Ok, maybe it’s not magical, but it sure is great to use. So you’re aware it’s a very bad practice to use echo statements in your controller. This gets fixed shortly. In your CI_INSTALL/application/config is a file called routes.php that we need to edit. The default controller should be set to “main”, like below. 
$route['default_controller'] = "main";
While we’re editing the routes.php file, lets also add the following lines below the default controller and scaffolding settings. 
// Custom routes for my site
$route['about'] = "main/about";
$route['contact'] = "main/contact";
$route['services'] = "main/services";
Now that we’ve made that update, lets go back to our controller main.php. Lets update the index action to use a view script instead of the echo statement. The code below will load the file home.php in the CI_INSTALL/application/views directory. 
public function index(){
    $this->load->view('home');
}
That takes care of how to load the home page. Now lets create the methods for the other routes. 
public function about(){
    $this->load->view('about');
}

public function contact(){
    $this->load->view('contact');
}

public function services(){
    $this->load->view('services');
}
When you call your views scripts this way, you’ll need to have all the page HTML – from DOCTYPE to your closing “html” tag. You can call multiple view scripts, so I suggest you make two more  – header.php and footer.php – as an exercise. For now, create them with all the required HTML. For the about page, run it in your browser like this example.com/index.php/about Now that we’ve done a majority of the pages now, we just need to do the ‘work’ pages. We made this one separate because this one could be more involved than the other pages, depending how you’d like to implement it,  so its best to create a separate controller. Since this will be responsible for displaying pages of our work, we’re gonna want a little more power.  We’ll have two different different URLs – /work (which will be an overview page), and /work/client-name to display each client project on it’s own page. The overview page is easy. It works just like the homepage. In your CI_INSTALL/application/controllers directory, add the following code. 
<?php
class Work extends Controller {

	public function __construct(){
		parent::__construct();

	}

	public function index(){
		$this->load->view('work_index');
	}

}
?>
Now that you’ve created the controller, now create a view script in CI_INSTALL/application/views called work_index.php and add the html you want to display. For the client pages, we’re going to add a little more code. Our goal here is to have one page that we can re-use for every client. The first thing we need in a new method that we’ll call client. In the method we’ll create an array to associate the client id with their information. 
public function client($clientId){

    $data = array(
        'foo' => array('title' => 'Foo Title',
                 'hero' => '/images/foo/hero.jpg',
                 'altText' => 'foo logo')
        ,'bar' => array('title' => 'Bar Title',
                 'hero' => '/images/bar/hero.jpg',
                 'altText' => 'bar logo')
    );

    $this->load->view('work_client', $data[$clientId]);
}
What’s happening above, is the third segment that comes in is passed in as the argument to the method. To paraphrase: the value of $clientId is whatever appears the in the third url segment. $clientId is used to get the corresponding information to send to the page. Below is a simple view file that will process that uses the information for the client. 
<html>
<head>
<title><?php echo $title; ?></title>
</head>

<body>
    <h1><?php echo $altText ?></h1>
        <img id="hero"
             src="<?php echo $hero?>"
             alt="<?php echo $altText ?>" />
	<p>this is some information about the project.
You should update the controller with the information that you would like
 to appear here.</p>
</body>
</html>
Above we mentioned that we want our client urls to be example.com/index.php/work/client-name, but if you’ve been paying attention, you currently need to type example.com/index.php/work/client/client-name for the page to show up. Now I’ll show you how to fix that – by returning to our magical friend routes.php. Add this to the file just below the routes you added earlier. 
$route['work/(:any)'] = "work/client/$1";
At this point everything should be working fine. But you’re probably thinking “how do I get rid of the index.php from my URLs?” To do this you need a .htaccess file in the root of your website. paste the lines below into it on your server. 
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond $1 !^(index\.php|css|js|images|robots\.txt)
# this line adds index.php to the URL so CodeIgniter can process it.
RewriteRule ^(.*)$ index.php?$1 [L]
Throughout your site, now you can write URLs like /about. The Apache web server will use the htaccess file make the URL be index.php/about so CodeIgniter can handle it properly. Ok. That should be enough to get you started. Take the time to write your feedback in the comments below. If this helped you, great! If there’s something you think is missing, that is also good to know.

Orca Card

Life in Seattle and its surrounding cities and counties is about to get a little easier for those who take public transportation. Several transportation agencies have a new project. It will simplify and accelerate the process of paying for transportation. Enter ORCA Card. The ORCA card is a universal access pass that works on multiple agencies’ systems surrounding the Puget Sound. You might say “One pass to rule them all”. In fact, ORCA is an acronym for One Regional Card for All.  It uses RFID to hold your currency and pass information, and accesses it when you tap the sensor.   You can add value in person, over the phone, and online. It’s the last option that likely speed adoption. Being able to add value to your card outside of business hours empowers the customer, increases the usability of the system, and increases the likelihood that the customer will keep using it.

Costs

By now your probably wondering how much it costs. To get the card, it’s currently free. However, this is true for a limited time. Keep in mind that they’ll charge you to replace an existing card. Given that the cards are expected to last “approximately five years with regular use“, the replacement cost is trivial. The cost for your travel is separate. Trying to estimate what you should spend each month can be difficult. I live in Seattle, so I use the King County Metro site. Here’s the basic rule for King County – All of Seattle is 1 zone, Everything else is another. Here’s a chart for the fare information.

Challenges

The first of a few challenges for ORCA is the same as any new project – gaining adoption. My friends and I are early adopters, and we’re already sold on it. However, getting the masses to use it will take a fair amount of effort. The second challenge is their website orcacard.com which is poorly designed, has suspect accessibility, and lots of ugly query string URLs. They need to contact Mastodon Labs to solve these problems with a website redesign.

Tips

  1. Get your card now, while they’re free.
  2. Get two cards – one for you, one for guests. So when you have a friend or family member come to visit you, they can use the second card and not worry about how much to pay and carrying exact change. Also it can be a backup for you, should you misplace your primary card.
  3. You don’t need to ask the driver for a transfer, the ORCA knows if its a transfer the next time you scan your card.

Mobile Edition

This morning I’ve launched the mobile edition of AndrewWoods.net However, it doesn’t include this blog. That’s for a future time. :) In keeping with the One Web idea, I’m using the same url but a different layout. I chose this method, because it complies with the DRY principle, it made it easier/faster to develop, and its more cost effective since i’m not using a separate hosting account for a mobile site. The difficulty to mobile web development is that you need to test a wide variety of devices. Acquiring such devices can get expensive depending on how many you’re developing for. Some developers, and even companies, make sites to cater to iPhone or Blackberry and call it a day. I’m using a Palm Treo 700p, and limiting my development to Palm Devices would be bad, given the small audience. More importantly though, I want everyone to be able to use my websites. So, I have a request. If you have mobile browser on your phone, could you send me some screenshots of what different pages on AndrewWoods.net look like, in the next day or so? Here’s an example of a screenshot from my hiragana project. I’d greatly appreciate it. If you’re a web developer that makes mobile sites, I’d love to hear any tips you might have.

Introducing Mastodon Labs

I’ve been in web development since 1999, when I started at Animated Designs as a contract Perl programmer. I spent 6 years there learning an array of web technologies in the areas of programming, databases, and Linux system administration. I left to seek out new adventures outside of California, which brought me to Seattle. Since arriving in Seattle, I’ve had the opportunity to work with great people at a variety of companies, both as a contractor and as an employee. I think now is time to take my next step. I enjoy the agency environment, and want to return to it. Also, since I was a teenager, it’s been a goal of mine to have my own business one day. I couldn’t imagine what form it might take. Now I can. Without further adieu, I’d like to introduce you to Mastodon Labs. Mastodon Labs is a web development agency whose focus is to serve the needs of American small business. Yes there are many companies that build websites, but what’s different about this one?, you ask. There are 3 key differentiating factors. First, is to design every website to be accessible by all audiences. Companies in the United Kingdom are required to do this. However, it’s largely not done in the United States. The web standards movement has been making some headway in bringing it to the attention of developers, but it’s not pervasive yet in the industry. Secondly, I have a strong interest in the mobile web and want to make that a key component of Mastodon Labs offerings. As mobile device manufacturers catch up, and consumers increasingly use their intelligent mobile devices, it will become essential for small business to participate. Thirdly, but not least, community is important. Within your local community is where you can have the greatest impact. Because we’re located in Seattle,  we’ll serve the needs of small businesses in the Pacific Northwest, but we’re open to helping everyone. This will be a great adventure. The opportunities and challenges that lie ahead will make the journey fantastic, and I can’t wait for it to unfold.  I look forward to working with you.

Mystery In The UK

I’m currently working on a webapp that will allow every country to participate. the content is locally consumed. I’m attempting to build a database to hold all the information, in a structured way. I’m confused by the  country relationships of the UK. I’m in the USA, so I’m not sure what the typical experience is for a UK citizen. There are four countries: England, Wales, Scotland, and North Ireland. These four countries, have formed an entity called “United Kingdom”, or UK for short.  Plain old ‘Ireland’ is a separate country. There is another entity called “Great Britian”, which refers to the countries England, Wales, and Scotland (source: DirectGov).  There’s an organization ISO that maintains global standards. One of the standards is ISO 3166-2, which is a list of country names, and their 2 character abbreviations. Looking at this list of country codes and names, the United Kingdom has the code of ‘GB’. Huh?  More confusingly, the countries England, Wales, Scotland, and North Ireland are all without their own 2 character codes. I guess the real question is “Who’s on first?“. Let’s hold off on that issue for a moment, and look back to my original problem. I’m unclear as to how I should model the relationship between the UK, the individual countries of the UK, and their cities. Let me give you an example. I live the United States, in the state of Washington(WA), in the city of Seattle. So my record would be like this: country=US, state=WA, city=Seattle. Given that, lets do an example for London. Three examples come to mind. The first captures the most information: country=UK, state=England, city=London. This one is appealing as it captures the most information in an existing structure. The second just removes England from the state field: country=UK, state=null, city=London. The third uses England for the country country=England, state=null, city=London. I’m considering this one because I know that England is a country, so it’s technically correct. Do people who live in the UK, look on web forms for UK, then their own specific country? Or do they look for their specific country, then UK? What’s the convention most users expect? Is there another territorial breakdown I’ve missed?  I know of postal codes. I appreciate any feedback you can provide. UPDATE 2009-FEB-21: Everybody’s feedback was very helpful, particularly Gary Gale (@vicchi) who just happens to be Head of UK Engineering at Yahoo Geo Technologies (@yahoogeo). Let’s recap of the things I’ve learned. First ‘United Kingdom’ is what users search for. It’s also the name that appears in the ISO 3166 list. So I can safely use it. Second, people never look for things by their individual country (England, Scotland, etc) – partly because of the previous point, and partly because postcodes are so informative, they can be used to pre-populate other fields like city and county. Third, the ‘county’ is what people typically use to filter things.  There are actually two sets of county information – administrative and postal. The web apps I’m writing are for people and not the government, so I’m going to use the postal counties. In summary, Mr Gale said “if you’re designing a web based mechanism for addresses you’d use the country, the county and the town followed by the street address and our Postal Code, the equivalent of the US ZIP”. Nice! Pragmatic and simple. Thanks again everyone. It’s been illuminating.

Architecting Your Dev Environment

Every web developer has a particular way of working. This can be anything from using particular software applications, to storyboarding with construction paper, to drawing diagrams on paper napkins at their favorite local cafe. Whatever it may be, they learned at some point in their experience as a developer, that their technique works. But if you’re new to the business, you have nothing to draw from. So these next few posts are targeted to the newcomer. However, if you’ve been around for a while, you might learn a trick or two, that you can add to your own tool belt. The following is a list of the upcoming titles in this series
  • Application Architecture on Localhost
  • Source Code Control Architecture
  • Hosting Architecture
Foreach of the items in the list above, I will discuss the technical aspects of setting up your environment. Setting things up the first time will seem like a lot of work. but every additional project will be very easy to set up, once you have the blue print. There are few technical constraints, as most of these concepts apply across environments. I am on a Mac OS X machine, so all command line items will use BSD syntax using the Bash shell. I’m approaching this from the perspective of a LAMP developer. PHP 5 is my language of choice. Application Architecture on Localhost This segment will give you a practical, scalable structure that will keep things organized. Also, you’ll be given some very useful bits for configuring your Apache server, as to how it relates to your day-to-day.  I’ll try to ensure that you get all the essential, plus a couple of cool bits. Source Code Control Architecture If you’re new to web development, you might need an introduction. However, that’s already been covered by many people smarter than myself. What I’ll give you are suggestions/strategies on how you might make the best of organizing your strategies. Hosting Architecture So you’ve got a working a site on your local box. Your next step is to put in on your hosting environment. You’ll need a staging environment, so you can let other people test your code, have clients preview updates that you’ve worked on. the things you learn for the staging environment, can also be applied in your production environment. Stay tuned, as I plan to write a post every few days. NOTE: As each post is written, I’ll update this one to link to it.