How to make you (technical) blog irritating

I am going to have a little rant, mainly because it I was trying to work out how to enable markdown in wordpress and pretty much everything I googled was pretty unhelpful.

There is no date on the blog post

This can be especially irritating when I am looking up something technical as I need to know how relevant it is. Sometimes you can find out whether the information is relevant. There are clues like screenshots of ancient looking user interfaces, it is mentioning older operating systems or if the code looks ancient. I don’t mind if the information is out of date if I know when it was written.

There is no version number listed

When looking to enable markdown for the editor on my blog I did the usual, I googled what I wanted to do using keywords and saw if anything was listed in my results. I found the wordpress support site which seemed like a winner. Except the steps aren’t correct for my version of wordpress (I am running latest), so I went to check what in what versions it is relevant and there is nothing mentioned at all! So I have to assume the documentation is out of date :(

I would mind less if it wasn’t a big project, but I expect a higher level of professionalism on such a large project that probably has millions of installations.

Lazy blog posts

To compound matters, there were hundreds of blog entries that could be split into following categories.

  1. Article which mentioned 3rd party plugins which I wanted to avoid, almost all of these were identical. Also all the information for installation, configuration and usage could be found on actual plug-in’s homepage.
  2. Word for word rewrites of the wordpress support site (which I know to be out of date). This really pisses me off because it doesn’t add any value.
  3. Markdown tutorials, these have been written already don’t write another one.

I am a complete sucker for clickbait on facebook and I’ve spent plenty of hours procrastinating on the likes of lamebook, diply and cracked and those sites are a guilty pleasure. But this is technical content and not “10 pictures of the cutest dogs with babies” or whatever George Takei’s press team will post on his facebook feed next. It needs to be accurate and it needs to be useful.

Tutorials that don’t work

Slightly aside from my markdown woes, The reason why I’ve written only two tutorials so far is for two reasons:

  1. It is really hard writing a tutorial properly. I make a big effort to make sure that what I am writing is 100% accurate and reproducible at the time of writing. These days I go the lengths of firing up clean VM image and manually do each step in the virtual machine to see if it works, I also have a friend that is kind enough to go through it and correct any obvious errors or point out bits that are vague.
  2. Sometimes I don’t feel like I am adding any value. I haven’t done second of my Silex tutorial because I feel like I am just rehashing the docs. I have been writing follow ups but I am being very careful to make sure I am not just rehashing the docs.

Removing perfectly good information

I’ve done a lot of work in ASP.NET Webforms for my sins and the number of times I have written a custom User Control that contains a repeater must be somewhere in the hundreds. Webforms, being Web Forms is pretty poorly understood for numerous reasons that I won’t go into here. Repeaters are one of those things that hasn’t really changed since the first versions of ASP.NET.

There was a page on MSDN that explained everything you could possibly want to do with a repeater and explained exactly how to find controls, manipulate them, add controls dynamically etc. It was an excellent reference and when explaining to a newbie you could point them to it as a good reference. It was old, there was no code highlighting but it was correct and it was complete. When they revamped MSDN it disappeared, I expect it is still around somewhere but my bookmark doesn’t work anymore.

 

Building a web application with Silex: (Part 1)

I’ve been writing a small web application in Silex. It is a nice framework for making web applications in PHP.

This is going to be a small tutorial to get it a basic web layout working and I will also show you how to use bower for installing client side dependencies.

Pre-requisites

I am going to be assuming that you are using a modern version of Windows (7 or above) and that you have PHP installed. I installed the latest version of PHP that is supported via the Web Platform Installer (WPI). This is the easiest way for you to install PHP and other tools you are likely to want if you are developing web applications on Windows.

Once you have the web platform installer install, you can install PHP by simply searching for it in the search box to the right:

Web platform installer php search results

Web platform installer php search results

I already have PHP 5.5.1.1 installed and PHP 5.6.0 is available for installation. Simply press add and then install. The web platform installer will start downloading and installing PHP on your machine.

If I were you I would take a short break if you are installing everything for the first time.

Installation

You are going to want to have composer installed. Installation is trivial on Windows so I won’t be covering that.

Create a directory called “samplewebapp”. This is your working directory.

The first thing we are going to do is create a composer.json file. This is composers configuration file. It is essentially a dependency management system (among other things) for PHP. If you have used similar systems like npm, NuGet or Pip much of this will look familiar to you.

  1. {
  2.     “require”: {
  3.         “silex/silex”: “~1.2″
  4.     }
  5. }

You will need to now use composer via the command prompt to install Silex. I’ve been using Git Bash as it is a little nicer to work with than the plain command prompt that Windows provides.

  1. composer update

You should see the following:

Silex initial install via composer

Silex being downloaded and installed in our application directory via composer

Silex is now installed. If you inspect the contents of your web application folder you should see that it has created a folder called vendor. This is where composer will put all the components that it will install.

Now we don’t have anything that can actually be run yet, but we have set up the initial environment and we are ready to start!

Hello World

So we are going to start with baby steps and echo some text to the browser for now. Create a file called index.php and copy and paste the following in:

  1. <?php
  2. require_once __DIR__.‘/vendor/autoload.php’; 
  3.  
  4. $app = new Silex\Application(); 
  5.  
  6. $app->get(‘/hello/{name}’, function($name) use($app) { 
  7.     return ‘Hello ‘.$app->escape($name); 
  8. }); 
  9.  
  10. $app->run(); 

This probably looks familiar because it is directly from the Silex homepage. I tend to start out by getting something basic working to ensure that I have everything setup correctly before moving on.

With newer versions of PHP you can run development web server straight from the command line. To do this simply run the following in the “samplewebapp” directory:

  1. php -S localhost:5000

Now if you open up localhost:5000/hello/<your name> in your favourite web browser you should see the following happen:

hello_world_silex

Silex is now up and running on our development server

At this point we know our environment is working correctly and we can start building a web application.

Setting up Twig

As Silex is a micro-framework built from Symphony components, it may come to no surprise to you that integrating Twig is very easy. Twig is a templating engine for PHP.

You will need to change your composer file to the following:

  1. {
  2.     “require”: {
  3.         “silex/silex”: “~1.2″,
  4.         “twig/twig”: “>=1.8,<2.0-dev”
  5.     }
  6. }

Then we run composer update again in out samplewebapp directory, You should see this happen:

composer_installing_twig

At this point we have twig installed. We now need to tell Silex where to look for our views. We need to change our index.php to the following:

  1. <?php
  2.  
  3. require_once __DIR__.‘/vendor/autoload.php’; 
  4.  
  5. $app = new Silex\Application();
  6.  
  7. $app[‘debug’] = true;
  8.  
  9. $app->register(new Silex\Provider\TwigServiceProvider(),
  10.     array(
  11.         ‘twig.path’ => __DIR__.‘/views’
  12.     )
  13. );
  14.  
  15. $app->get(‘/’, function() use($app) { 
  16.     return $app[‘twig’]->render(‘home/index.twig’);
  17. }); 
  18.  
  19. $app->run();

You will notice that a quite a few things have changed.

We have put Silex into “debug” mode by simply putting:

  1. $app[‘debug’] = true;

This will give up a nice stack trace in our browser when the code falls over.

Silex stack trace in our browser.

Silex stack trace in our browser.

Obviously this wants only wants to be set as true for development environments.

  1. $app->register(new Silex\Provider\TwigServiceProvider(),
  2.     array(
  3.         ‘twig.path’ => __DIR__.‘/views’
  4.     )
  5. );

This sets up a twig service provider, and tell it that our view templates are going to be in the ‘views’ directory. When rendering, including or extending templates our paths are relative to our view directory, this becomes important when your are creating more complicated page layouts using Twig.

  1. $app->get(‘/’, function() use($app) { 
  2.     return $app[‘twig’]->render(‘home/index.twig’);
  3. }); 

I’ve setup a new application route which is the route of the website. I have told the Silex to render the twig template index.twig. Remember that the home directory is relative to the views directory.

You can see in explorer that the home directory is inside our views directory.

You can see in explorer that the home directory is inside our views directory.

Our view template contains the following for now:

  1. <!DOCTYPE html>
  2. <html>
  3.     <head>
  4.         <title>Sample Home Page App</title>
  5.     </head>
  6.     <body>
  7.         <h1>HELLO TWIG</h1>
  8.     </body>
  9. </html>

This is just some simple html for now. If you fire up the development server again you should see the following.

The web server is rendering our twig template correctly.

The web server is rendering our twig template correctly.

Conclusion

We have setup an environment up on Windows for PHP development. Installed and configured Silex with Twig. We are rendering a basic HTML template in our web app.

The full source (there isn’t much so far) can be found on github.

Node.js Tutorial: Part 1 – Basics

I’ve been learning node at work and to be honest it is the most fun I’ve had in a while learning. I am going to cover the basics, using Windows. I am going to assume that you have written JavaScript before in the browser.

Installation

Installation on Windows is pretty straight-forward. You download the executable for your platform (32-bit Windows or 64-bit Windows). If you are on Windows 8 like me you should see the following in your start screen.

node-start-screen

If you have Windows 7 you will have a start menu folder with the same items in it. If you choose the highlighted item “Node.js” you will have a command window open with empty prompt.

nodes-repl-interface

This is node’s REPL interface, this stands for read-eval-print loop. It simply evaluates each line you type into the interface.

  1. ‘Hello World’;

This prints off “Hello  World” in the REPL interface. Also, if I do the following in the REPL interface I get the following output.

  1. > var a = 0
  2. undefined
  3. > a
  4. 0

The interface evaluates the expression that you have just entered. Assigning the variable a to zero, returned undefined as any other return type doesn’t make sense. When evaluating the variable a the return type is 0 since, we previously set a to 0. The REPL interface in node is very similar to the console in Chrome.

chrome-console

Running Scripts

Obviously the usefulness of REPL interface is limited to simpler tasks. For more complicated tasks you’re going to need to be able to run a script file. This is thankfully quite easy. When installing node, node is added to your path. This means you will be able to run node by simply opening up a command window and typing.

  1. node <my script>.js

And the script will execute. I have the following script “count-down.js” and it does exactly as you expect.

  1. var i = 10;
  2.  
  3. do {
  4.     console.log(i);
  5. whilei-- );

Output:

  1. C:\Users\Luke\Desktop>node count-down.js
  2. 10
  3. 9
  4. 8
  5. 7
  6. 6
  7. 5
  8. 4
  9. 3
  10. 2
  11. 1
  12. 0

Note: You’ll notice the while conditional is evaluated as false once our variable gets to zero. Those familiar with JavaScript and other dyanmically typed languages, will know that zero evaluates to false in our while clause.

Setting up a simple development environment

So far the examples I have given are quite trivial so far if you have studied programming before. Now I want to get into the real stuff that node is capable of, but before we do that we really need to set-up a basic development environment.

Installing node-dev

At the moment if you modify your script you need to run node again This becomes somewhat tedious. This is easily rectified:

install-node-dev

What exactly have I done there?

  1. I have invoked the node package manager using the command “npm”.
  2. The install keyword tells node that I wish to install the package “node-dev”.
  3. Finally the “-g” flag tells npm to install this globally throughout the environment.

More on this later.

If I use node-dev to start my script once the script has finished executing, it won’t fall back to the command prompt. If I edit the script when node-dev is running, it will detect that I have changed the script and restart the execution.

Installing node-inspector

For debugging purposes you could put various print statements throughout the code, but we all know this isn’t ideal. Node-inspector lets us hook chrome debugger up to node. Again we use npm install the node-inspector.

  1. npm install node-inspector -g

It installs far too many dependencies to list here.

Once node inspector is installed we can start node inspector. I usually have it running in another command windows.  To start it simply type.

  1. node-inspector

You should see the following output.

 

node-inspector

Now you need to start your script.

  1. nodedebug-brk count-down.js

The “debug-brk” option stops the script execution on the first line of code. To use the chrome debugger, you simply open chrome and type in the url localhost:8080/debug?port=5858. You can see from the screenshot below, that you can use the chrome debugger as you normally do in the browser.

chrome-debugging

Note: I know the first screen shot says that the debugger was opened on  http://0.0.0.0:8080/debug?port=5858, this doesn’t work but putting localhost does. I don’t know why this is and it hasn’t worried me enough to research the underlying reason.

Node’s Package Manager

Node has included with it a package manager called “npm”. Just above we installed some tools to help us with development.

NPM will install and manage 3rd party code libraries that you specify and the libraries which they rely on. If you have used tools like NuGet, Gems, PEAR or are familiar with using Linux package managers you will be familiar with the concept. For now we will be downloading them from npm repository. Usage of the package manager when installing is pretty straightforward.

  1. npm install <package name>

NPM will install the package to a folder in your working directory called node_modules. You will only be able to include those libraries in node scripts that exist in that working directory. If you want to install it globally, you need to use the “-g” flag as we did before.

Note: NPM sometimes has to compile some libraries that are native i.e. they are C++ libraries. You will need a C++ compiler otherwise the package installation will fail. Node-gyp is the component that builds these C++ libraries, there are instructions here on what you need to get node-gyp (and ultimately npm) working.

On Windows 8 I found it simplest to install VS Express For Desktop and Active Python (use the 2.7.2.5 version). Then use the “VS2012 x64 Cross Tools Command Prompt” when you are using npm install.

bind() and older browsers

Had this error today from IE7 & 8 from a script that I got given to fix.

SCRIPT438: Object doesn’t support property or method ‘bind’

I have never come across bind() before, I discovered it was part of the ECMAScript 5 specification, and is only supported by newer browsers (IE9+, FF 4.0, Chrome 7.0, Opera 11.60) it not supported in earlier browser or in Safari.

I found the solution on MDN. It appears the bind() is a new property that overrides the ‘this‘ keyword in a function. A bit of copy and pasta of some code on MDN into my own script, and I had bind working again.