I have three different kinds of notes. -There are the notes that I write that serve as little reminders to me. These notes are either blog post ideas, or things that I think of, or just a list of things that I need to get done. They get changed and delete a lot as I’m working through them. -There are the kinds of notes that I write and then share with a few people. These notes tend to be a more fleshed out version of the previous ones, but I’m still not ready to make these public. -There are notes that I consider “completed” these notes will occasionally need some updating, but they are complete thoughts or ideas and there is little that I need to do except maintain them. I don’t mind people seeing SOME of these notes, but some of them will still be private.

Most note taking applications let me manage the first one. They let me create these private notes and maintain them myself. Most times they work like a single folder with many notes in it. Most times the notes are organized by their names or when they were created. Sometimes they even let me “tag” them. Tagging works great for emails, but not for notes. Or at least, not for my notes. For example, there is rarely a note I will ignore, but many emails get ignored for days based on their tags. The notes are something that I actively need to be able to sort and organize – much like a folder/file structure. A lot of note apps don’t allow this level of organization.

A lot fewer note taking applications offer the 2

Rivers

Yesterday I announced that I had put up my river of news publicly. I have been using it quite a bit, even transitioning a lot of my feeds over to it and I’ve realized just how handy something like this is. It’s interesting news that most times I would just “Mark as Read” in Google-Reader, but now I can actually scan it at will.

Dave Winer has been running various Rivers of his own and claims that this is how he most likes to consume news. For me the River is a way to filter noise out of my standard reading lists that I still subscribe to via the old fashioned RSS.

Rarst mentioned to me that to him the SPEED of the river isn’t as important as the content flowing through it. Granted he isn’t a fan of Rivers in general, but the idea is valid. My River is never going to be as interesting as your river, and Dave’s river is probably the most interesting to Dave. So why not a web service that allows users to churn out their own Rivers. So that’s the plan for June. Create a private-beta service that allows users to create their own Rivers.

Notes

I’m in the process of launching a simple web-app that will allow you to create/manage/publish “notes”. Essentially you would open up the app, log in and then you could create notes. You could create “folders” to manage these notes and of course, you can “publish” them to receive a unique url that is publicly accessible. You can also subscribe to a users public feed notifying you of updates.

This web app stemmed from the need for a single interface to manage all the notes/writing I do on the computer. Normally, when I answer the phone, I pop open notepad to take down notes. When I think of a new idea or concept I write it all up and then either forget where I wrote it or delete it so that I can keep thinking about it. To me, notes are very fluid. Sometimes, I need to share the notes I create with other users, to get their input.

So, I created the web app. Hopefully, this month I’ll be able to finish up with branding and add the public notes feature. You’ll know that it’s ready to officially enter private beta when I transition my blog over from Posterous to a new system that is either completely powered by, or consumes the content provided by this new note application.

Last night I published my own river at http://river.xangelo.ca. I’m hoping that soon you’ll be able to subscribe to it via the RSS with eventual support for rss cloud. Maybe I’ll even throw in support for JSON. That way, you can run your own river if you want.

Building was actually a lot simpler than I initially thought. I ended up powering the entire system using limonade-php and SimplePie. For the front end I used Baseline.css, jQuery and a little JavaScript module-based system that I’ve been working on.

The system is simple, a GET run on /river will return the last.. 6 hours worth of river in JSON and a timestamp. Just keep GET‘ing that /river with a query string of last_checked = timestamp and you’ll get a JSON update.

So yes, have fun with river.. I’ll be mucking about with the update frequency over the next few days.

Before I begin I just want to note that this document is a work in progress. It requires version 5.3+ of php as it utilizies anonymous functions and it requires the use of limonade-php v0.5.1

Get caught up

If you haven’t yet, check out Part 1 of this tutorial to get setup. I’m going to assume you did.

Step 1: Setup

1 2 3 4 5 

<?php 

include('lib/limonade.php'); 

?>

Now, rename index.php to api.php

Step 2: Database!

Now we get to setup our database. Since each of us have different ways of doing this (I switch between command line and sqlbuddy) I’m providing the SQL code that will create our database. If you want you can re-create it using your favourite SQL manager.. or you can just copy and paste the SQL code and execute it. It’s nothing too complicated, just a single table called “todo” in a database named “lemondoo”. Each row in this table will have

1. a “todo_id” which is an auto incremented primary key (int)
2. a “todo_title” which is the title of this todo item (varchar(100))
3. a “todo_text” which is the text of the todo item (text)
4. a “completed” flag that is either 0 (not completed) or 1 (completed) (tinyint)

1 2 3 4 5 6 7 8 9 10 11 

CREATE DATABASE `lemondoo` DEFAULT CHARSET utf8;

USE `lemondoo`;

CREATE TABLE `todo` (
   `todo_id` int(11) not null auto_increment,
   `todo_title` varchar(100),
   `todo_text` text,
   `completed` tinyint(4) default '0',
   PRIMARY KEY (`todo_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1;

At this point, I would go ahead and enter a couple sets of data into our new table. Make sure that you set the completed field to 0.

Step 3: Design our API

API design, as far as I am concerned, should be an entire topic of study in itself. Adding REST principles makes it a little easier, but still it is something that should be thought about carefully. Below I’ve outlined the REST header, the associated URL and the function that it will call. Notice that we can have two different headers assigned to the same url and each can map to their own function call. What we’re going to do is define this route for limonade-php so that it knows what to do depending on what URL we try to access. Note below that when I say :id it means that if you access /anything it will call the appropriate method and also assign “anything” to the variable “id”. So if you had /:yes it would assign “anything” to the variable “yes”

When working on the web it often helps to have some kind of database abstraction present. For my Limonade-php projects, I normally end up utilizing a single function that currently ties in to a mysql database. The connection happens before you call the method, but if you pass in a connection resource it will use that resource for the sql statement.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 

<?php
/**
 * A quick little function to interact with a MySQL database.
 *
 * When working with Limonade-php a full-fledged MySQL wrapper seems like
 * overkill. This method instead accepts any mysql statement and if it works
 * returns either the result or the number of rows affected. If neither worked,
 * then it returns false
 *
 * @param   string      $sql    the sql statement you want to execute
 * @param   resource    $c      mysql connect link identifier, if multi-connect
 *                              otheriwse, you can leave it blank
 * @return  MIXED       array   the result set if the sql statement was a SELECT
 *                      integer if the sql statement was INSERT|UPDATE|DELETE
 *                      bool    if anything went wrong with executing your statement
 *
 *
 * [update|insert|delete]
 * if(db('update mytable set myrow = 4 where someotherrow = 3') !== false) {
 *  // worked!
 * }
 *
 * [select]
 * $res = db('select * from mytable');
 */
function db($sql,$c = null) {
    $res = false;
    $q = ($c === null)?@mysql_query($sql):@mysql_query($sql,$c);
    if($q) {
        if(strpos(strtolower($sql),'select') === 0) {
            $res = array();
            while($r = mysql_fetch_assoc($q)) {
                $res[] = $r;
            }
        }
        else {
            $res = ($c === null)?mysql_affected_rows():mysql_affected_rows($c);
        }
    }
    return $res;
}
?>

Line by line explanation:

1-25: Documentation

26: Function declaration, accepts an sql statement and an optional connection resource.

27: We preset $res to false This is so that we can get rid of a bunch of if-statements 28: If there is no connection resource, just execute the sql statement. If there is, use it. (@ surpresses errors)

29: Check to see if our query worked, if it didn’t, we just return res which we preset.

30: Checks to see if we tried to execute a ‘SELECT’ statement.

31: Change $res into an array. Our results will be a nested array since our statement worked!

32-34: Loop through our results and assign them to $res.

36-38: If the sql statement was NOT a ‘SELECT’, return the number of affected rows. If a user passed in a connection resource, use that.

40: return $res, which could either be false, array() or int depending on if the query failed, was a select statement, affected the rows.

Before I begin I just want to note that this document is a work in progress. It requires version 5.3+ of php as it utilizies anonymous functions and it requires the use of limonade-php v0.5.1

Getting started with Limonade-php

Your first step is to simply download Limonade-php from GitHub. Make sure you grab the latest version (v0.5.1 at the time of writing this) and extract it. You’ll want to go into the lib directory and copy limonade.php and the limonade directory. The directory contains some utilities for limonade-php, but is not necessary. Infact, once your application is complete properly, I’d suggest you delete this folder and leave just the limonade.php file behind.

The standard first project

When it comes to programming, your first project is always Hello, World. So let’s not break that tradition. Create a new directory called “hello_world” and in it create a directory called “lib”. You can paste in the file and directory you copied earlier. Now let’s create a file called “index.php” and open it up in an editor of your choice.

Step 1: Setup

1 2 3 4 5 

<?php 

include('lib/limonade.php'); 

?>

Simple enough, but if you visit that page in your browser, you’ll see that it doesn’t really do anything. So we’re going to add a bit more code.

Step 2:

First we’re going to say that whenever a user visits that page using a “GET” header, we’re going to display the text “Hello, World!”. In a nutshell, GET is one of the four recognized header types for REST implementations. GET is for retrieving information about a resource. For more information about REST, check out this post and combine it with this

1 2 3 4 5 6 7 8 9 10 11 

<?php 

include('lib/limonade.php'); 

dispatch_get('/', function() {
    return "Hello, World!";
});

run();

?>

Did you just pass that function a function as an argument?

Why yes. Yes I did. It’s a new feature of PHP 5.3 that allows for anonymous functions. You’ll see the same thing happen in JavaScript all the time, so if you work with that, you should find it familiar. Essentially an anonymous function is just a function without a name. There is no way to call it without assigning it to a variable. So, by passing it to dispatch_get as an argument, it is assigned to a variable within limonade-php.

Finally, on line 9 we add the run(); command. This tells limonade-php to start.

Now if you visit index.php in your browser, you’ll see the text “Hello, World!”

Step 3: Profit

Now that you’ve gotten a taste of how easy it is to build something using limonade-php let me just say, that it really is that easy to build just about anything. Because of limonade-php’s adherence to RESTful principles it becomes ridiculously easy to build an API or a dynamic website, or just about anything in between. It even integrates very well with other libraries and components. It allows for rapid prototyping (I created this ([source])(https://github.com/AngeloR/Lemontrac) in only a few hours – including the time it took to learn limonade-php) and it has become an important part of my php toolbox.

Now what?

Well, it’s all well and good to display “Hello, World!” but it’s kind of useless to everyone who wants to build something useful. It hardly scratches the surface of what is possible with limonade-php. So, to properly show you what you can do with it, let’s build a very simple todo application. But with a twist. First we’re going to build a todo application API. Then we’re going to build a website that consumes this API using JavaScript and jQuery.

Stay tuned for part 2!

Well it’s only been a few days since I released Lemontrac to the public but I’ve already got a slew of updates that I am planning for it.

Roles and ACL

The biggest of these updates is a complete overhaul of the user management system. The plan is to include role-based access control lists which will work pretty well I think. I thought about it and instead of shipping with pre-defined roles, the only role allowed will be an administrator role which will be able to do whatever they want. It’s up to them to create the rest of the roles and assign privileges to other users as they see fit. The more flexible it is, the better.

Sorting and Filters

Any data manipulation application should come with some excellent sorting and filters. The basic (alpha/last updated/created time/priority) will be implemented, but I am open to any other sorting ideas that people may have. Being able to easily get to all of these is a must, and so there will be some slight UI changes coming up.

Bug dependencies ##

Basically, some bugs appear because of a bunch of other bugs. A bug must be able to be marked as “dependent” on another bug. If that’s the case, that bug can’t be closed unless all of its dependencies are resolved.

Merging Bugs

Users are probably going to experience the same bugs. Being able to merge bugs (and notify the bug creator of possible duplicates) is a necessity to preserve the integrity of the application.

Email Notifications ##

This is something I completely overlooked until it was pointed out to me, but the ability to “subscribe” to a bug or project and be notified of it through future emails is a must.

You can count these as the features that absolutely have to be in place before Lemontrac can move to version 0.2 assuming that everything with work and switch to another OS don’t go terribly, you can expect April to feature version 0.2 and also a brief introduction into working with Limonade-php. I’d urge you to check out the website that is currently in place as it does have some great tutorials and examples, but incase you’re waiting for one, it is in the works.

Every year I try and make it my goal to really learn at least one web framework. I don’t need to become a master at working with it, but I need to know it enough to consider it one of the “tools” available to me.

This year I started trying to work with CodeIgniter, but then got sidetracked by various personal projects. That and the fact that most frameworks just feel too bloated to me. They keep trying to add on all these “features” and as nice as they are, they shouldn’t really be part of the CORE framework. They’re modules to enhance it. Not to mention that most frameworks have such a weird learning curve that it takes a long time before you’re comfortable with it.

That’s why I was pleasantly surprised by a new PHP framework I stumbled across called (Limonade-php)[http://limonade-php.net]. Limonade-php is a “micro” framework. It’s more or less one file with a few resources, a LOT smaller than any other framework I’ve seen. But it’s so ridiculously amazing that I knew I just had to work with it. Limonade allows you to build RESTful applications pretty much instantly. There’s almost ZERO learning curve and things just make sense.

For example, adding a new page is as simple as dispatch_get('/page/route','func_name'); But can be made complex by utilizing some handy features to allow for query parameters. dispatch_get('/page/:id/some/:resource','myfunc');

Of course being almost 100% RESTful compliant, you have access to methods such as dispatch_get, dispatch_post, dispatch_put, dispatch_delete all of can be mapped to the same path allowing you to REALLY build RESTful applications.

I was so impressed with Limonade-php that about an hour after playing around with it I started writing a tool that I needed for my daily work. It was a very simple bug-tracker allowing for multiple projects, bugs and users. It allows you to color-code projects, which immediately translate into color-coded bugs. And it was all done in a single file that is under 550 lines of code (not counting primarily HTML views and CSS).

So check out (limonade-php)[http://limonade-php.net] and if you like, take a look at (Lemontrac)[https://github.com/AngeloR/Lemontrac].

After you’ve been programming for a while, one of the first things that you start doing is working out the database. You decide how your data should be stored, and you think about the optimal ways you can do this. You think about what technology would best support your idea, and then you get to work mapping out the back-end. And when that’s all done you start writing your classes. You write the little pieces first, like what the user object should look like. Then you build the classes and objects that would utilize the user object, creating new objects as necessary. And finally, when you’re all done, you start designing the front-facing portion of your application. Whether it’s for the web or for the desktop, as a programmer this is generally the last step.

And you’re doing it all wrong.

Designing an application from the STORAGE point of view is all wrong. Imagine designing a car based on the garage that you were going to put it in. Yes your car will always fit in the garage, but you’re going to run into problems. You’re probably going to have to make some concessions on the size of the car. But when you’re programming, you get to design the garage too. So why not build the car to be the best damn car ever, and then build the garage around that? That way you never need to compromise and you can be damn sure that the car is always going to fit.

Now, lets apply this metaphor to programming.

The first step I take when building an application is to decide its purpose. Is the application meant for non-technical users? Is it meant for children or adults? Is it going to be maintained by me or other developers? What’s the life expectancy of this application? Are there any third party applications that need to talk to it, or vice versa? These questions help us define how we should be building the application. It imposes some features and necessities while still allowing us a lot of freedom.

To me, data is the most restrictive part of our application. It’s the only part that we have no say in. The data will always be the data. We can’t adjust it to suit our needs. As programmers we spend so much time living with things that have no real substance. The code we right can just as easily be re-written a different way. The database we design could have been designed a completely different way. But yet we insist on building our application on things that can shift at will. The Data is concrete. The data is ALWAYS the data and it can never look like anything else. It can never change shape.

So we should start with The Data. We should say “what is the best way to display this data”. Designers think this way (the good ones do at least) and it’s time for programmers to think this way too. I’m not talking about how The Data should look to users, but how The Data should function in our application. Too often we end up having complicated queries simply because we forgot that we need to use The Data in a certain way.

We should model how the data needs to be displayed. Once we have that mapped out our Data will start to fall into some shapes. We simply coral those semi-ambiguous shapes into something concrete and now we have a solid database design that really does model our Data. And because we built our database on REAL Data, we know that we will always have a place for The Data and that things are as simplified as possible.