Xangelo

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

First lets copy our “hello_world” directory and rename it to “lemondoo”. Then open your index.php file and leave delete everything except for the PHP open/close tags and the include statement.

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)

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”

Notice that limonade-php comes with some functions that mimic our Headers. dispatch_get, dispatch_post and dispatch_delete are all built in to limonade-php. Also notice that instead of passing an anonymous function to dispatch__xxx as we did previously, now we are passing a string. This string will be the name of the function that we will be creating. There are many different ways that you can provide “callbacks” to routes, and I would suggest that you read up on them in the readme

Normally, when I create an application the first thing I’ll include is a simple database abstraction class. For the purposes of this application, that is a little overkill, so here’s a function that will do everything we need it to.

I’m not going to explain it in too much detail, but essentially you pass in a SQL statement and it returns either an array-based resultset, or a true/false depending on if the statement succeeded.

Step 4: Configuring limonade

Step 5: Define your functions

get_todo_list():

Limonade-php abstracts away a lot of this work. Basically our db() method returns a two dimensional array containing all our todo’s and then that is converted into JSON using json_encode(). The json() provided by Limonade-php is simply a wrapper for that. Finally we return the JSON that we created. Limonade-php will hold the result until it runs through all it’s steps before printing out the JSON with the appropriate headers. If you save api.php and visit it from your browser, you should see a JSON representation of the todo’s in our

add_todo():

Notice that if the note was successfully inserted we are going to just grab the ID of the note and then return that.

get_todo(): This method will simply return the details of the todo requested. So accessing /1 will return all the details of the todo who’s todo_id is 1.

Notice that in the definition of our function we pass a single argument called $id. Remember how we defined dispatch_get('/:id','get_todo') earlier? Well now the value of :id is going to be passed to our function. We just do a quick check to make sure that the value passed to our function is valid and then we return the results of that dataset.

update_todo(): Update todo is going to accept all the fields in our todo table (todo_id, todo_title, todo_text, completed) and updated the database corresponding to todo_id. Then it returns either true or false depending on if the update worked. Since the end user will already have the updated data, there is no need to send anything else back.

delete_todo(): Finally, this method will delete any todo. We simply pass it an ID, and then BAM. Deleted.

Summary

So far, our API has been very simple. We can perform some basic actions on our database by accessing various URL’s. However, you will notice that you can not access “post”, “put” and “delete” pages through your browser natively. By default, browsers send a “GET” request, since you are trying to get the contents of a page. If you fill out a form, you get to do a “POST” request as well.

In our next section we will be building an HTML/JavaScript/CSS interface to work with our newly created API.

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.

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

As promised, here is the first part of a series of tutorials to get you comfortable with working with a great new framework called Limonade-php. I suggest you read about it here because the original authors do a damn good job of describing it. Once you’ve read a bit about it and have had your curiosity piqued, feel free to follow along with this quick little introduction.

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

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

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 where we will go into greater detail about building applications using limonade-php.

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. 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 and if you like, take a look at the open-source MIT licensed 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.

I've been working with JavaScript a lot lately and with NodeJS garnering so much attention, I figured it was time for a new project.

I decided to start working on a Multi User Dungeon style game. You remember those old games where you would connect via telnet and then execute commands like "walk north" or "attack" by entering them into a prompt? Well over the next few months I'm going to be working on my own version of that.

In order to make to make it REALLY accessible, I have of course gone with using JS client side with jQuery to handle events and ajax, but where this is really different from my normal projects is the backend. I'm opting to run NodeJS with Express and DBSlayer. So this game will really be running on almost 100% pure JavaScript. Of course I'll be running a standard MySQL database since it seems to make the most sense for this. I investigated other non-relational database mechanisms, but to be honest, they're not suited for structured inter-related data. 

As well, this is the first time I'm hoping to use a vcs to handle my source. I was initially looking at GitHub, since that seems to be the standard nowdays, but I find Git... awkward. SVN seems to make more sense to me so I'll probably end up using that. I might sign up at Beanstalk or Assembla that way I still get the option of keeping my source closed during development. I like the idea of open source, but I can't imagine anyone would be interested in my work while it's still being worked on. Things change very frequently, and nothing remains where it is.

I've been working on it for a few days now and here is the current state of the code:

The core only contains a few objects. game, screen and something called Cobra. Cobra acts as a "command manager". Since MUD's are essentially a bunch of commands, Cobra is the object that registers them and calls them when commands are entered. So what this allows us to do is to define separate "commands" that never pollute the global namespace.

Another feature of Cobra is capture, which allows us to temporarily bypass it. Why? Basically we can create temporary commands that exist as long as we want! Huzzah!

Anyways, I shall keep you all informed as to how this proceeds and maybe even do a quick walkthrough of setting up Node/npm/Express/DBSlayer and MySQL (which is ridiculously easy).