CrayonCowboy Ranch

The Rails bundle in TextMate does a great job of bringing a most of the Ruby on Rails command line tasks into your coding environment, eliminating a lot of the back & forth trips to Terminal. The few holes that are left aren’t a big deal but something that was just getting on my nerves was starting & stopping Webrick. For that matter, I wasn’t really a fan of having to ‘cd ~/path/to/my/development/directory/’ all the time when I did need to make a trip to the terminal. (Yes, I’m that lazy). I threw together a couple quick TextMate commands that make these things a little faster.

If you feel so inclined, you can download the commands here.

Update: you can download a newer version here that will target Firefox & Safari.

Running Webrick
As far as Webrick goes, I can either start it up from the command line and then ^c to kill it, leaving me with a minimized terminal window and a very unhappy inner neat freak, or I can run it as a daemon and later have to track down the process id to kill it. It’s not that it’s difficult, it’s just that it violates the slothfulness I’ve spent years cultivating.

The first few commands will start, stop, and check the status of a Webrick instance started using ./script/server.

By default the server is started on the default port (3000) but if you like, you can set the CCB_SERVER_PORT project variable to another port number and it will use that instead.

Jumping to Terminal
If I’ve already told TextMate to open my rails application as a project, do I really need to type the path again every time I open a new Terminal window? The last command in the archive will open a new terminal window with the working directory being the TextMate project directory (which is probably your Rails app directory). The only interesting bit in this one is that, in order to help me keep my terminal windows straight, the terminal window is given a custom title. The title will default to the path of your rails app, but you can set the CCB_PROJECT_NAME variable to a custom title and it will use that instead. The command will make a reasonable effort to number your windows as you create them but it’s pretty easy to get it thrown out of whack if you start closing windows while leaving others open. That part can use some improvement.

These are thrown together pretty quickly so, although they work, they lack a bit of polish and eye candy. The Webrick startup command output includes a link to “Open” the application after the server is started up. I’d like that to open in Firefox or Safari, but I’m not quite sure how to get TextMate to do that, and honestly It’s not helpful enough for me to dig into at the moment. If anyone knows how to get TextMate HTML output windows to target the default browser I’d love to know.

Update: Thanks to the TextMate manual (& Henrick N for his comment) the above Safari / Firefox question is answered. An updated version is available for download.

Download Link (If you missed it above)

Today I re-discovered an interesting tool for project planning or, more accurately, for the data modeling part of planning. Concept Maps, something like a cross between a Mind Map and a flow chart, are “maps showing the relationships between concepts” (duh). Interestingly enough, figuring out those relationships is exactly what we, as software developers need to do when we set out to create a data model. What are the key components (objects) in the system we’re trying to represent & do those components interact (methods/properties) with each other? Using a tool like a concept map lets us ignore the technical details of how to model the system and focus on the simple truths of what we’re modeling.

CMap Tools is a free, and feature rich application built not only to create concept maps not only locally, but also collaboratively across the net. It could stand a healthy dose of “user friendliness” before I’d consider trying to use it with some of my clients, but for most developers and development teams, it presents an interesting tool for working out a very high level outline of data relationships.

The thing that caught my attention today was CMap Tools’ “Propositions” feature. “Propositions” are just simple statements of two “Things” described with a relationship. For example:

• Companies own Projects
• Companies own Employees
• Projects contain Tasks
• Employees own Tasks

Each proposition becomes a basic truth of the relationship between items in the system we’re modeling. When you spit out as many “truths” as you can think of, you end up with a remarkably detailed, and remarkably accurate visual model of your data.

For example, lets assume we want to model a simple application for managing projects & tasks within our company. We’ll start with a new empty CMap.

We could double click & begin graphically adding items to our diagram, but that’s not what we’re interested in. We want to end up with a diagram based on a series of simple facts. To do that we’ll open the CMap list sidebar, select the “Propositions” tab and add our first proposition. We’ll state that Companies contain Eployees by entering it in the proposition fields. Pressing return we see the diagram is updated to indicate this relationship.

To complete our model, we just need to spit out as many statements of relationship as we can. We’ll state that Companies contain Teams, Companies contain Projects and Projects contain Tasks. As we go we find that CMap Tools conveniently keeps track of both the objects and the relationship descriptions that we’ve used and offers us auto completion as we go. Entering Employees own Tasks is practially written for us. Also, notice that the map keeps track of each item that the “Company” contains, and reuses the contains node accordingly.

Our full (albeit simple) list of propositions might look something like

• Companies contain Employees
• Companies contain Projects
• Companies contain Teams
• Teams work on Projects
• Projects contain Tasks
• Employees work in Teams
• Employees own Tasks

This gives us a clear definition of the simple relationships and has also built us a nice little diagram in the process. Unfortunately the diagram is a bit ugly.

Cmap Tools gives us an easy way to work around that with it’s “Autolayout” feature. Choosing the Autolayout option from the “Format” menu we’re presented with a few options. We’ll select the “Polylines” line style and press “Generate New Layout”.

If at first you don’t succeed, try, try again. Cmap Tools sometimes gets it wrong the first time but each press of the generate button tries to mix things up & offer you a new variation. Now we have a reasonably decent looking diagram that represents the general real-world information we need to model.

We can go back and add styling if we want, perhaps making key objects larger and in bold font or making propositions that objectA requires objectB use bold red lines. Whatever…

What really interests me about this process is the potential for collaboration over the web with multiple developers adding to and editing the propositions. It’s also interesting how much you learn about the system as you start to notice propositions that aren’t quite true (Employees in a team don’t really own projects… they only own the tasks within a project).

The planning processes will always be changing and no tool will be the perfect one for every situation. But concept maps are, at the very least, an interesting way of approaching the data modeling part of what we do. In a particular stuck project I’m working on, it gave me the sift of focus I needed to really grasp the relationships between some various parties, and even if the project itself is a colossal failure, at least I have a pretty concept diagram to show for it.

JSON (JavaScript Object Notation) is intended to be a generic format for representing the structure and data of an object in text. If you’re not familiar with JSON, you might want to do some googling before reading this. The important part to understand is that JSON is a representation of an object, and not an object or class definition written in any specific language. Any number of languages can read the JSON object representation and build an object modeled on the data it represents. In that way, its sort of like XML.

Recently I came across a post on the Web Dev Bros blog about Generating JSON from VBScript (ASP) datatypes. Along with the info in the post, Michal provided a download for a JSON utility class which will accept some data as an input and return a JSON representation. With a few updates & enhancements (which I drafted into the class and sent to Michal) I think its about all you’d need to produce JSON from your ASP applications. A question came up in the comments however about going the other way around. How do you read JSON from within ASP and build VBScript objects based on the representation?

Believe it or not, ASP has built in support for reading JSON into objects, its called JScript. But given that most asp applications are written in VBScript, the question becomes, how do I parse JSON with JScript, and then translate it into something useful in VBScript? The answer is, we write another utility class (or in this case, a pair of them). We’ll need two classes to make this work easily:

1. (CCBJSONTranslator) A JScript class that simply reads the JSON representation into memory (creates an object) and provides some helper methods to get at the data
2. (CCBJSONParser) A VBScript class that internally uses the CCBJSONTranslator JScript object to convert all the data into something useful for us.

Because VBScript can’t create a new object from a JScript function, we’ll also need a helper function written in JScript that can be called from VBScript which will return an instance of the CCBJSONTranslator object.

Download the class file here

The nice thing about this is tat since the VBScript class uses the JScript class internally, we never have to touch it and can pretend that it doesn’t exist. maybe we’ll get into the guts of the objects some other time. All we have to do for now is create an instance of the CCBJSONParser class, pass it some JSON text, and we’ll have full access to its data in VBScript Dictionary form.

Lets look at a small bit of JSON representing the employee list of “WidgetCo”…

{
    "Jim Morgan" : {
        "email" : "jmorgan@WidgetCo.com",
        "extension" : "111",
        "photo" : "/images/staff/jim.morgan.jpg"
    },
    "Susan Brown" : {
        "email" : "sbrown@WidgetCo.com",
        "extension" : "112",
        "photo" : "/images/staff/susan.brown.jpg"
    },
    "James Black" : {
        "email" : "jblack@WidgetCo.com",
        "extension" : "113",
        "photo" : "/images/staff/james.black.jpg"
    }
}

When all is said and done, we should end up with a dictionary object with three items. The key for each item is an employees name. The value for each item is another dictionary which has the keys “email”, “extension”, and “photo”. To get started, we’ll want to create an instance of our CCBJSONParser class, and feed it some JSON data.

'...    Create instance of the JSON parser object
set JPar = new CCBJsonParser

'...    Read JSON data from the staff.js file
'       and set it to the objects .JSON property
JPar.JSON = readTextFile("staff.js")

You can get the JSON however you want (read a text file, pull from a database, etc…). In this example, we’re reading from a text file. Note that readTextFile() is a custom function and is not built into ASP. You’ll want to use the Scripting.FileSystem object to read a file.

Now we need to get to the Data from VBScript. This is where we need to make some decisions. We can either load the entire JSON representation into memory or we can access individual sub-sections and get at those values. To access the values directly, we would need to know the “path” to the value we are looking up. For example, to get Susan Brown’s email address we can just do this:

email = JPar.valueFor("Susan Brown.email")

This is great for accessing small amounts of data because you don’t need to create additional VBScript objects. The down side however is that there is a performance hit every time VBScript has to talk to JScript. To do this for a great many properties on a great many people might not be the most efficient way of doing things. Also, this method is not going to work if we don’t know the names of the employee we’re looking up. Without the name as a key, we can’t get to the value.

The other option then, is to load the entire representation into a set of nested VBScript Dictionary objects. To do this we just “parse” the JSON, and then get to the dictionary through the object’s .dictionary property.

JPar.parse
set Staff = JPar.dictionary

Now we can list the email addresses for all of the employees by looping through the keys collection in for the Staff object

for each employee in Staff.keys
    Response.Write "<a>" & employee & JPar.item(employee).item("email") & "</a><br />"
neXt

Again, there are drawbacks. Be aware that using this method on a vary large JSON representation with a lot of nested objects will result in the creation of a large number of VBScript Dictionary objects.

The CCBJSONParser class also has a .description property that is somewhat interesting if not always useful. It will return an HTML formatted description of the object instance including the JSON it is is operating on, and a unordered list hierarchy representing the value of the .dictionary method.

The only down-side to the current version of the class is that JSON arrays are returned as VBScript dictionaries. In this case the array index should be used as the dictionary key key. For example to get the array element at index 4 you would use:

set MyObj = JPar.dictionary
x = MyObj.item("4")

If you missed the link above you can download the class file here