Redmine Consulting Services Open

My company, Little Stream Software has re-opened its Redmine and ChiliProject consulting services.

If your Redmine or ChiliProject installation needs help, I’m here for you.

  • Maybe your team needs to change the workflows.
  • Maybe you need some expert training on customizations and plugin development.
  • Or maybe you want to extend it to better fit your business processes.

Whatever the reason, if you’re interested you can learn more about how I can help you:

Learn more about my Redmine services

riot.js, minimal MVP – Weekly Tech Learning

This post is part of my weekly tech learning series, where I take one hour each week to try out a piece of technology that I’d like to learn.

Last week I started my tech learning series back up. I’ve been feeling a bit behind with client-side JavaScript libraries so I’m planning a few around them.

To start off, I decided to try out riot.js. Billed as a minimal MVP library that is under 1kb, it felt like a good introduction before getting into the larger Angular or Ember.

Also with my pleasant experiences with knockout.js in the past, I wanted to see if riot.js would be easy add in for an existing server-side application.

Documentation

The approach riot.js takes is to add a small layer on top of regular JavaScript. The benefit here is that if you know JavaScript, its API is so small that you will barely notice it.

One thing that tripped me up was how the documentation and demo applications were built modularity. Once I understood how they plugged together it made sense, but most of my experience has been in monolithic applications.

(I’ve tried to steer client projects to a more modular structure but I’ve never been able to build one from scratch. It’s one thing to refactor towards modularity, another to start with it in mind.)

Todo list application with riot.js

Like my previous articles, the base application I’m building is the vulnerable todo list. It’s a project I’ve done many times and know the scope by heart, so I can explore how the technology side works.

This time I spent a bunch of time to really finalize my Grunt configuration. I’ve been experimenting with it over the past few months and I decided to codify those experiments into a configuration the suited me. While it was great, it did burn up a lot of my time.

Features

Being a todo list, I kept the feature-set short.

  1. Single page app without refreshes
  2. List all open todo items
  3. Add a new todo item
  4. Complete a todo item
  5. Delete a todo item

Nothing crazy.

I also didn’t want to deal with the data storage at this time. For something client-side using localStorage is probably enough but I’ve already built something using it so I didn’t need to explore how it works.

(Also riot.js is supposed to make this quite easy due to its modularity. Design your models with a simple backend API and you can swap them in or out as needed.)

The Single Page App

Since this was a single page app, I needed a base skeleton to hold the app. There’s a list (ol), a form for adding new todos, and a embedded JavaScript template for each todo item.

The final piece was to initialize and start riot.js. Initialize was easily done by calling my application’s function (todo()) with its initial configuration. As you’ll see later, this created a singleton instance of my TodoList object (a model).

One area that threw me for a few nested loops was the SPA module I copied from a demo program. This module did several things:

  • it created a singleton instance for the app
  • it would return than instance when the function was called (todo())
  • when passed a function, it would layer that function on the instance. Thereby making this new function act as a presenter layer.
  • it would initialize my TodoList model to hold the TodoItems
  • finally it would trigger the “ready” event, which presenters could listen for

All this is about 16 lines of code. Three different ways to call it (todo(), todo({..}), todo(function())). As you can imagine, this took a bit of time to understand and figure out.

Mixed with the fact that I forgot to trigger the ‘ready’ action myself, meant that I was doing some deep debugging before I understand what was happening. Once I added that, it worked exactly how I was described. Basically when the DOM is ready (from jQuery), my application is told that, and it runs any functions that were waiting on the DOM (e.g. rendering the list).

Models

Once I got everything hooked up, development started going really well. The model development in particular was easy. Models in riot.js are just basic objects that have the ability to trigger and listen for events (Observers, using riot.observable).

In this case my models didn’t use any events, they were just data stores operating on a single data structure, the todo items. Adding meant adding the TodoItem to the end of the list, completing wrapped the name in <strike>, and deleting removed the item from the list.

The real magic happened in the presenter.

Presenter

As explained above, the presenter function is layer on top of my application’s API which was just a model in this simple case.

The presenter does five different things (originally, it was actually five different presenters layered on top but it made sense to combine them into one. This is where the modularly can be handy, if you need to split up or combine presenters you can and they’d end up working the same)

  1. Listen for the form submission for adding a new todo item
  2. Listen for any clicks to complete a todo item
  3. Listen for any clicks to delete a todo item
  4. Listen for any events to redraw the list
  5. Initialize the first loaded view

If you look at the code below for the presenter’s Add, Complete, and Delete areas they are basic JavaScript/jQuery event logic. Bind on an event, run a function. Complete and Delete are ultra simple, just call the app’s function for each and then trigger a ‘list’ event to redraw the list. (app.trigger('name') is how riot.js creates new events that objects are listening for).

Add is a bit more complex because it’s working with the form. Instead of just calling the add() function, it has to pull the value out of the field, check that it’s not empty, and then clear the field when done. Nothing really out-of-the-ordinary with jQuery but it’s worth pointing out that all of this UI logic is contained in the presenter (unlike many other applications I’ve been brought in to help with).

Now the fun parts. Instead of using jQuery bindings, list is using riot’s on() function to setup a callback function when the “list” event is triggered. When this happens, the list is cleared and each item in the todo items from the model is added to the todo list. I used riot’s template rendering using the render() function and passing in each todo item. This meant my todo template (in the HTML) could access every property and riot would substitute the values before returning the final string.

The final part of the presenter is listening for the “ready” event. When this happens, the presenter knows the DOM is done and renders the first version of the page. In this case, the only dynamic thing needed is the list. Instead of duplicating how the list is rendered, the ‘list’ event is triggered which uses the list code.

Entire flow

It can be hard to see how this all goes together so here is the basic application flow from start to finish.

  1. Page loads.
  2. When the JavaScript is parsed, the presenter is added. This happens because the presenter is using todo(function()) which executes immediately. This hits the 2nd section of the todo function (labeled as SPA) which listens for the “ready” event.
  3. todo({..}) is called with a few initial, hard-coded todo items (which would be where I’d get them from the backend if I used one)
  4. That hit the 3rd section of the todo function in SPA
  5. A new TodoList was created with the todo items, which due to TodoList’s extend populated the items with the initial data
  6. Then back in todo() the instance of TodoList starts listening for the “ready” event.
  7. Sometime later the DOM finishes loading so the jQuery ready block in the HTML runs and triggers the ‘ready’ event
  8. The instance gets this ready event (3rd part of SPA) and triggers its own ready event passing in the instance as a parameter (the TodoList aka the application).
  9. This executes the presenter which sets up its own event observers (riot and jQuery) as described above.
  10. Finally the application is fully booted.

Adding a new todo item would flow like this:

  1. You enter the item into the field and click submit
  2. The presenter receives the submit event in Add, blocks it, and calls TodoList.add()
  3. add() create a random-ish id and appends the new TodoItem to the list of items
  4. Flow falls back to the presenter which resets the field, clearing it
  5. A ‘list’ event is triggered
  6. The presenter’s List observer receives the event, empties the list, and re-renders it based on the current list of items.

(As you might have noticed, I’ve had to refer to each section of the presenter by the section name given in the comments. This makes a good case for having multiple presenters which you can name separately. Even if it causes a bit more code, communication would be much easier which is a net win for any team)

Summary

All said and done, experimenting with riot.js was fun and productive. This entire process took a few of hours, some of which included reading documentation and demo code (and configuring grunt). There was more code here than in my knockout.js version but I didn’t have to embed logic into the template like I did in knockout.js (my main complaint with knockout). Instead, riot.js used custom events to handle behavior which has always been something I found useful for structuring JavaScript applications (and something I’ve done manually).

One thing I didn’t get to do was to really tease apart the model and application layers more. Right now my model and application are pretty much the same thing, which happens with such a simple concept. I’d imagine a larger application with more models would have a clearer separation between each layer.

All in all, I’m going to add riot.js to my regular toolbox. I feel it’s useful when you need a lightweight MVP library but don’t want a lot of overhead with it. Also since it’s mostly vanilla JavaScript, it should be easy to adapt to a heavier library later on should the need arise.

If you’d like to use a demo version of the application, you can find a copy running at http://riot-js.apps.littlestreamsoftware.com/ with the unminified version of the JavaScript.

Would you like to hire me?

Code

Basic HTML page with the skeleton structure and the todo item template.

<!-- www/index.html -->
<!DOCTYPE html>
<!--[if lt IE 7]>      <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]>         <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]>         <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]-->
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
        <title></title>
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width">
 
        <!-- Place favicon.ico and apple-touch-icon.png in the root directory -->
 
        <link rel="stylesheet" href="css/normalize.css">
        <link rel="stylesheet" href="css/main.css">
        <link rel="stylesheet" href="css/app.css">
    </head>
    <body>
      <h1>Todos</h1>
 
      <ol id="todos">
      </ol>
 
      <form id="addNewTodo">
        <p>
          <input id="todoName" name="name" />
          <button type="submit">Add</button>
        </p>
      </form>
 
 
        <!-- JS -->
        <script type="text/tmpl" id="todo-item-tmpl">
          <li data-key="{item.id}">
            <a class="todo-complete" href="#">[ ]</a>
            <span>{item.name}</span> 
            <a class="todo-delete" href="#">(X)</a>
          </li>
        </script>
 
        <script type='text/javascript' src='js/jquery-2.1.0.min.js'></script>
        <script type='text/javascript' src='js/riot.min.js'></script>
        <script type='text/javascript' src='js/tech-learning-riot-js.js'></script>
        <script>
          // Initialize
          todo({items: [
            {name: "This is a test", id: 1},
            {name: "Need to do this too", id: 2},
            {name: "<strike>Done</strike>", id: 3}
          ] });
          // DOM ready so start the app
          $(function() { todo().trigger('ready'); });
        </script>
    </body>
</html>

The riot.js application. Normally you’d put each model in its own file in a directory and separate the presenters from the application API. But since this was a small app, they are combined into one file with comments to separate them.

// www/js/tech-learning-riot-js.js
function TodoList(configuration) {
  var self = riot.observable(this);
 
  // Requires an array of TodoItems
  $.extend(self, configuration);
 
  self.add = function(name) {
    var id = Math.random() * 1000000;
    var data = {name: name, id: id};
    var todo = new TodoItem(self, data);
    self.items.push(todo);
  }
 
  self.complete = function(id) {
    var itemAsArray = $.grep(self.items, function(item) { return item.id == id});
    if (itemAsArray.length > 0) {
      var item = itemAsArray[0]; // Assume only one
 
      if (item.name.match(/<strike>/)) { return false; }
      var index = $.inArray(item, self.items);
      item.name = "<strike>" + item.name + "</strike>"
      self.items[index] = item;
    }
  }
 
  self.delete = function(id) {
    self.items = $.grep(self.items, function(item) { return item.id != id});
  }
}
 
function TodoItem(app, data) {
  var self = riot.observable(this);
 
  $.extend(self, data);
}
 
// SPA
var instance;
 
window.todo = riot.observable(function(arg) {
  // todo()
  if (!arg) return instance;
 
  // todo(fn) to add a new module
  if ($.isFunction(arg)) {
      console.log('spa2'); 
    window.todo.on("ready", arg);
  } else {
    // todo(conf) to initialize the application
    instance = new TodoList(arg);
      console.log('spa3'); 
 
    instance.on("ready", function() {
      console.log('spa3-ready'); 
      window.todo.trigger("ready", instance);
    });
  }
});
 
// Presenters
todo(function(app) {
      console.log('pres-parse'); 
 
  var root = $("#todos");
  var template = $("#todo-item-tmpl").html();
 
  // Ready
  app.on("ready", function(view) {
      console.log('pres-ready'); 
    app.trigger('list');
  });
 
  /// Add
  $("#addNewTodo").submit(function(e) {
 
    e.preventDefault();
    var name = $("#todoName").val();
    if (name) {
      app.add(name);
    }
 
    this.reset();
 
    app.trigger('list');
  });
 
  /// List
  app.on("list", function(view) {
    root.empty();
 
    $.each(app.items, function(i, item) {
      root.append(
        riot.render(template, { item: item }));
    });
  });
 
  /// Complete
  $('body').on('click', '.todo-complete', function(e) {
    e.preventDefault();
 
    app.complete($(this).parent().data('key'));
 
    app.trigger('list');
  });
 
  /// Delete
  $('body').on('click', '.todo-delete', function(e) {
    e.preventDefault();
 
    app.delete($(this).parent().data('key'));
 
    app.trigger('list');
  });
});
tEREUy1vSfuSu8LzTop3_IMG_2538

Should you bill by the hour, week, day, or month?

The topic of changing your billing frequency comes up often.

Most freelancers I know bill by the partial hour, with a few billing in units larger than that (and some freelancers bill by the minute using stopwatch timers). I can understand the feeling that you too need to bill by the same units as everyone else in the industry but that doesn’t mean you have to copy everyone’s billing method.

Value trumps how you bill

Once you’ve gained the trust of a client and started building a relationship with them, your rates don’t matter as much as we freelancers tend to think. As long as the client is getting above a specific amount of value for what they are paying for and we aren’t charging them more than they expect, most don’t worry about our rates.

If a client has a budget of $5,000 allocated for you, it doesn’t matter much if you charge $4,500 or $4,415, or even $4,000. The larger the organization, the more you can see this indifference to the per-unit cost.

Fit the billing to the project

So the question of which per-unit price to use comes back to what makes sense for the project and what you’re comfortable using.

For a monthly retainer contract, a per-month price would be best because the client isn’t getting X hours of your time, they are getting access to you for the “month of June”.

For more of a contracting project, where you’re expected to be around and working for a set number of hours, an hourly rate makes sense. A daily rate could also work if you limit the total time worked (e.g. overtime).

On an on/off contract schedule, it’s best to pick a unit that matches your schedule. If the client is scheduled for a week at a time, per-week billing is best. If it’s three days at a time, per-day billing is best.

Tracking your time (optional)

Now even if you aren’t billing a client by the hour or minute, tracking that data still could be valuable for your business. I’ve been tracking my billable and non-billable time since I started freelancing in 2007 so I can run reports to see where I’m spending my time.

In the past I noticed that I was spending up to two hours in email everyday, so I used those metrics to make a decision to cut way back on email. Now it’s more like an hour or two per week.

Setting your new unit rate

Setting your rate is a pretty huge topic, with entire books written on how to calculate or figure out what rate you should charge.

If you’re a new freelancer, I cover setting your rates in 30 Days to Become a Freelancer. You can also use an online calculator but those have their own set of problems. Primarily, they are too cost-focused.

If you’re an experienced freelancer who already has a set rate, taking a first guess at what your different per-unit rates is easy. Remember, you have clients who are paying your existing rate already. Some clients might already be getting your time in large chunks like full days or weeks so you’re already charging per-unit rates now but you haven’t formalized it yet.

Since most freelancers I know state their rate in terms of per-hour, I’m going to start with that as the base.

per-hour rate

The rate you charge now.

per-day rate

Based on a busy but not an excessively long day, how many hours did you work? Times this by the hourly rate to get your per-day rate.

When I focus get around 6 hours of productive work each day for a client. Anymore than 6 and it affects my productivity the next day. So my daily rate is around 6x my hourly rate.

per-week rate

If you go on the assumption that you are working a full 5 day workweek, just multiply your per-day rate by 5. If you have a shorter week, lets say you take a three day weekend every week or maybe you have an administration day each week, adjust as needed.

I work 5 days a week so my per-week rate is 30x my hourly rate.

per-month rate

Finally we get to your per-month rate. I found multiplying your per-week rate by 4 is a good estimate, you can get closer but you’ll have to adjust for holidays and other oddities. As you’ll see in a minute, we are just looking for ballpark numbers right now.

So my per-month rate would be 120x my hourly rate.

I know 120x is a good estimate for me because I used to plan out every month to figure out the number of billable days and calculate to the hour how much availability I could sell. More often than not, each month came out to 20 billable days, which based on 6 hours of working per day would be 120x my hourly rate.

NOTE: You’ll notice I didn’t put calculations in for per-quarter or per-year rates. I think these are so rare that you don’t need to calculate them upfront. You can always use the per-month rate if you needed to.

Review for confusion

The next step is to look at each of your per-unit rates and see how they feel to you. You’ll want to round some of them, or maybe adjust them so they feel more comfortable to you. Just don’t adjust them down to make them too comfortable, you don’t want to give a discount just because your per-month rate is large. You would be billing that much if you had a month-long project at your hourly rate.

Let’s put these calculations through a few examples. With the base hourly rate of $85/hour and a 6 billable hour day, the per unit rates would look like this:

  • per-hour: $85
  • per-day: $510
  • per-week: $2,550
  • per-month: $10,200

Now these numbers look a bit odd so let’s round them up a bit. Remember that the per-day rate is based on an estimated amount of time you can bill in a day, so if we are rounding up a lot we can counter that by working a bit longer as needed (e.g. 6.5 hours, 7 hours).

  • per-hour: $85
  • per-day: $550
  • per-week: $2,750
  • per-month: $11,000

Now lets look at what a $150/hour rate looks like:

  • per-hour: $150
  • per-day: $900
  • per-week: $4,500
  • per-month: $18,000

Part-time freelancers

This process can be done by part-time freelancers too. Just adjust the number of hours per day and the days per week to fit your schedule.

Hopefully this gives you some ideas to break away from the per-hour and per-minute billing rut. Not only will you feel less pressure but your billing will become clearer to your clients.

Want weekly freelancer training like this?

Lessons on how to write more

Writing is my primary focus for a lot of my business.

How I communicate with client. How I market. How I create products.

But I couldn’t do any of that if I was afraid of writing or bad at writing.

If you’re starting to get into writing, here are a few lessons I learned.

Write in a plain format

Writing in a plain format makes it much easier to change how you work later. I mean plain as in plain text. Not Word. Not HTML.

With plain text you can copy and paste it into any program. You can leave it alone and email it directly. You can process it automatically into a richer format.

But always write in plain text.

You’ll probably want to use some basic formatting though. Stuff like headers, bold, or italics. For this you can use a plain text markup like Markdown or Textile. With these your writing is still in plain text so you get all of the benefits from that. But you can also easily define headers or similar basic formatting.

I wrote all of The Freelancer’s Guide to Long-Term Contracts and 30 Days to Become a Freelancer in Markdown. They’re converted automatically into HTML, PDF, and the mobile formats. But I can easily take them and use a different set of tools to convert it later on.

Get the words on the page

When writing it can be tempting to edit as you go. The idea is that if you can think of a better word or phrase while you’re writing, then taking a second or two to edit won’t hurt.

But in my experience any kind of editing while you’re writing prevents you from getting into the flow. You’re constantly jumping back and forth between writing a side of your brain and the editing side. This causes you to lose your train of thought more often which causes writers block.

Instead, if you can cultivate the habit of just writing you can really hammer though things. What I found that works best is a combination of free writing, and writing without looking at the screen.

Free writing

When free writing your goal is to just keep writing. Even if you come to a stopping point or can’t think about what you should write next, keep writing. Even if it’s random things like what you want to cook for dinner or just typing ‘blah, blah, blah’ over and over again. The point is to keep your hands moving so when the ideas and words do come back to you can easily jump right back in.

Blank screen

When I free write I also try to avoid looking at my screen. I’ll leave it on but I’ll glance around my room or look at the keyboard every few seconds. This way I’m not re-reading what I just typed. Some people recommend turning your monitor off but I found lost a few sessions of free writing when a window would pop up and steal my focus from my editor. I’m considering doing more free writing on my ipad to get more into this distraction-free writing.

The most important thing to remember is that it’s the most important part of writing is to get the words on the page. Once they are there you can change or rearrange them. The faster you write, the faster you can move onto the next stage.

Make it a habit

The final tip and one that I’ve been working on is to make writing a habit. Set of goal to write daily, even if you have no intention of publishing it anywhere. The act of writing, putting your thoughts and ideas into words over and over again will make you a better writer. You’ll be more clear. You’ll learn what topics you have a passion about.

Years ago I started on a daily writing habit. At first it was 200 words per day (less than a printed page). Then I bumped it up to 300 and then 400 words per day. The exact word count wasn’t important. What was important was that having a fixed goal to strive for each day gave me a way to measure my progress.

When I need to produce a lot of writing, say for another book or a blog series, I shoot for 1,000 words per day. 1,000 words per day can fell like an extreme amount but with some focus and a solid block of time its doable. Using the 1,000 word goal I write The Freelancer’s Guide to Long-Term Contracts in 6 days and 30 Days to Become a Freelancer in 9 days. One day I wrote over 6,000 words in 3 hours. Sure this type of writing needs a lot of editing but as I explained earlier, once the first draft was written I had plenty of material to work with in my edits.

Start now

If you do nothing else from this article, start writing now. Build that habit today and you’ll thank yourself later.

Eric Davis

Want weekly freelancer training?

Sale on all of my training and ebooks (Ends June 20th)

I’ve decided to have a summer sale. Summertime is a great time to start thinking about freelancing.

The bright sun means you can get out more.

Vacations with your family lets you spend quality time with them and become closer.

And most of all, you start to see the how things can be different. After a cold winter, seeing the flowers in bloom and fresh produce at the market can really make you think about your place in the world. The impact you can make.

If your future includes finally starting your freelance business or signing multi-year clients, for the next two days (until Friday June 20th) you can get 20% off on all of my training.

Get your training here, no sunglasses required.

Enjoy.

Eric Davis

P.S. This sale also includes Refactoring Redmine (learn how to refactor Ruby code), Authoring Ebooks (write and sell your technical ebook), and Redmine Tips (become a Redmine power user).

Helping new entrepreneurs build a successful software business.

Need more freelance clients?