Daffs blog

GitHub page generators

Mon, 02 Apr 2012 00:00:00 -0700

GitHub just tweeted about new layouts for the instant page generator. There are some really good looking layouts which I think any developer knows to appreciate. Besides the page generator there are also other tools that can help you set up a nice looking home page for your project.

Paige

Paige does “Super simple project page generation” from your readme.markdown file and Docco annotated source code. You need NodeJS and Pygments and you can easily install it using NPM:

sudo npm install paige –global

Then set up a paige.json configuration file in your project like this:

{
  "title" :             "Paige.js",
  "content_file" :      "readme.markdown",
  "include_index" :     true,
  "docco_files" :       "src/*.coffee",
  "header" :            "Paige.js",
  "subheader" :         "Super simple project page generation",
  "background" :        "diagonal-noise",
  "github" :            "https://github.com/rthauby/Paige"
}

include_index will generate an index of the Docco annotated source files given in docco_files. The github option I implemented (thanks rthauby for pulling it into 0.1.7) adds the “Fork me on GitHub” ribbon if you provide a link to your GitHub project.

To see it in action visit the Paige or the UberProto homepage.

DocumentUp

DocumentUp generates a nice single page documentation with a left menu navigation from your projects readme file. It is dead easy to use. Just go to http://documentup.com/username/repository and you will see the DocumentUp documentation for your project. To regenerate visit http://documentup.com/username/repository/recompile. To use it in your GitHub page create an index.html in the gh-pages branch like this:

<!DOCTYPE html>
<html>
  <head>
    <script src="documentup.min.js"></script>
    <script>
      DocumentUp.document("username/repository");
    </script>
  </head>
  <body></body>
</html>

I am currently working on migrating the jQuery.dForm documentation to DocumentUp and it works really well.

Jekyll

If you want to create your own layout but you still like to use Markdown for documentation pages then Jekyll might be a good choice (also used for this Blog). Jekyll is a static site generator that is supported by GitHub out of the box. That means that it will run as a post commit hook when setting up the basic Jekyll structure in the gh-pages branch. A great place to get started is Jekyll Bootstrap.

JavaScript module compatibility

Wed, 22 Feb 2012 00:00:00 -0800

For my latest project I wanted to make the library to be available as an AMD or NodeJS module and, as a fallback, in a global variable (e.g. when referenced directly as a script in the browser). The following wrapper provides this kind of compatibility when there are no dependencies:

(function(namespace) {
	if(typeof define == "undefined") {
		define = function(fn) {
			var res = fn();
			if(typeof exports == "undefined") {
				window[namespace] = res;
			} else {
				module.exports = res;
			}
		}
	};
	
	define(function() {
		// Return the module api
		return {
			hello : 'World'
		};
	});
})('MyLib');

If there is a module loader (like RequireJS) and the define function is available, it will directly use it. In NodeJS the return value of the function given to define will be used as the module exports and in a browser environment the return value will be declared as a global variable with the name passed to the anonymous wrapper function (here it is called MyLib). Explicitly returning the modules API is also refered to as the revealing module pattern.

Using AMD (e.g. RequireJS)

With the given wrapper in a file called mylib.js in the right folder:

define(['mylib'], function(MyLib) {
	console.log(MyLib.hello); // -> 'World' 
	// Source goes here
});

Straight in the browser

Directly loading mylib.js in the browser

<script type="text/javascript" src="mylib.js"></script>

will make the library available as a global variable with the given name (_MyLib_).

With NodeJS

Require it like any other module:

var MyLib = require('mylib');
console.log(MyLib.hello); // -> 'World'

The main drawback of this method is, that it is not possible to declare dependencies but I found it to be a good solution for small libraries that run in different JavaScript environments.

Dr. Jekyll - please take over

Sat, 11 Feb 2012 00:00:00 -0800

In an attempt to downsize and consolidate, I abandon my long term blog platform, Wordpress, and switch over to Jekyll. Jekyll is a static page generator that uses the Liquid templating language to generate pages and a YAML frontmatter for configuration. Both are really easy to handle and made it interesting even to me as a non Ruby enthusiast.

With great services like Disqus for comments, Feedburner to ship your RSS or Flickr to host your images, it makes only sense to keep the overhead of a personal website/blog as small as possible. Another great feature is the awesome integration into GitHub. As a GitHub user the workflow to write a new post will be quite familiar. Just create a new Markdown (or whatever markup language you feel like) file in the _posts directory, and when finished writing, commit and push to your site repository.

So even though the publishing platform should not be the main reason to keep you motivated and blogging, I hope that publishing more stuff will now become a little easier and more fun again.

Customize jQuery .val() with $.valHooks

Mon, 28 Nov 2011 00:00:00 -0800

When creating custom widgets that should act as form inputs it might be helpful to overwrite the behaviour of the jQuery .val() method. This is where the $.valHooks object can be used but as mentioned on this question on Stackoverflow there is not a lot of documentation. Here is a quick example that creates a custom myedit plugin that reads and sets the value of a div:

$.valHooks['myedit'] = {
    get : function(el) {
        return $(el).html();
    },
    set : function(el, val)
    {
        $(el).html(val);
    }
};

$.fn.myedit = function()
{
    this.each(function() {
        this.type = 'myedit';
    });
    return this;
}

$('#edit').myedit().val(' Hi there!');
$('#value').html('The value is : ' + $('#edit').val());

Mustache views for the Zend framework

Thu, 28 Apr 2011 00:00:00 -0700

Mustache is a language independent templating engine that keeps templates as easy and portable as possible. Combined with anonymus functions the simple collection of tags covers many different use cases.

Using the great Mustache.PHP implementation with the branch for higher order functions (supporting PHP 5.3 anonymus functions) I created a view wrapper and application resource called ZFMustache that enables mustache based views for the Zend Framework. The following post is pretty much the documentation readme but it seemed worth a blog entry as well:

Mustache views for the Zend Framework using the mustache.php implementation.

Installation

You can clone the GIT repository directly in your library folder:

cd myapp

git clone git@github.com:daffl/zfmustache.git -b zfmustache library/Mustache

Or add it as a GIT submodule to your existing repository:

git submodule add git@github.com:daffl/zfmustache.git -b zfmustache library/Mustache

git submodule init

Use it

The application resource will instantiate the view, set the Mustache engine autoloader and update the view renderer (unless enabled is set to false). Add the following to your application.ini to enable mustache views:

pluginpaths.Mustache_Application_Resource = "Mustache/Application/Resource"
resources.mustache.basePath = APPLICATION_PATH "/views/scripts"

You can also use mustache views only in specific controllers or actions. In that case setting the view renderer has to be disabled:

pluginpaths.Mustache_Application_Resource = "Mustache/Application/Resource"
resources.mustache.basePath = APPLICATION_PATH "/views/scripts"
resources.mustache.enabled = false

After that the bootstrapped mustache view can be retrieved in any controller:

<?php
	class IndexController extends Zend_Controller_Action
	{
		public function init()
		{
	    	$bootstrap = $this->getInvokeArg('bootstrap');
			$this->view = $bootstrap->getResource('mustache');
			$viewRenderer = $this->_helper->getHelper('viewRenderer');
			$viewRenderer->setView($this->view)->setViewSuffix('mustache');
		}

		public function indexAction()
		{
	        // action body
	        $this->view->planet = "Mars";
	        // Using a PHP 5.3 lambda function to render bold Text:
	        $engine = $this->view->getEngine();
	        $this->view->bold = function($text) use($engine) {
	        	return "<strong>" . $engine->render($text) . "</strong>";
	        };
		}
	}

A mustache file

Create a file called APPLICATION_PATH/scripts/views/index/index.mustache e.g. like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
		<title>Mustache Test</title>
	</head>
	<body>
		<h1>Hello !</h1>
		Hello bold 
	</body>
</html>

Creating forms in JSON with jQuery

Thu, 06 Jan 2011 00:00:00 -0800

Creating and managing HTML forms is probably one of the most tedious and in many web applications also the most important part of the frontend development process. Forms generated in a web application usually need to contain information on how they bind to domain objects, errors that occurred during processing and the values of different fields. Because maintaining all these information manually is very error prone and requires writing a lot of repetitive markup there are different approaches that support developers in this task:

Declarative: The framework supports custom tags that create form elements with all the information it needs to process that form (e.g. the JSTL Spring Form taglib)
Helper: In a view script the framework offers helper functions you can call which return a new form element (e.g. Ruby on Rails)
Programmatic: Forms are created programatically in the frameworks programming language (e.g. GWT, the Sencha ExtJS Forms or Zend Form)
GUI based: The form is created in a graphical user interface via Drag and Drop (e.g. the just started jQuery Form Builder project or ASP.NET web forms)

With web applications becoming more JavaScript heavy these approaches now not only have to generate HTML, but also have to take care of creating the appropriate JavaScript source code which often leads to an ugly mix of HTML, client side logic and server side logic.

One solution for that problem is the separation of HTML markup generation from the actual form definition, where the definition is available in a more abstract but easy to process format (like JSON). If a web application is already relying on JavaScript, the next step is then to let the client itself create the form from that definition.

Inspired by the programmatic approach and the fact that there doesn’t seem to be any jQuery plugin for this I started the jQuery dForm plugin (currently version 0.1.3). The ideas behind it:

Use JSON (or XML) as the form definition format. Easy to generate (e.g. automatically from your domain model) and flexible enough so that it can still be used to generate forms on the server side.
Easily extensible: Possibility to support other plugins, your own jQuery powered form elements or improving existing ones
Don’t reinvent the wheel: Add support for existing plugins like jQuery UI, the Validation Plugin or the jQuery Form plugin and keep the plugin itself as compact as possible.

The basic example to use the plugin looks like this:

<script type="text/javascript">
var formdata = {
    "action" : "index.html",
    "method" : "get",
    "elements" :
    [
        {
            "type" : "p",
            "html" : "You must login"
        },
        {
            "name" : "username",
            "id" : "txt-username",
            "caption" : "Username",
            "type" : "text",
            "placeholder" : "E.g. user@example.com"
        },
        {
            "name" : "password",
            "caption" : "Password",
            "type" : "password"
        },
        {
            "type" : "submit",
            "value" : "Login"
        }
    ]
};
 
$("#myform").buildForm(formdata);
 
// Or if the content of formdata can be loaded from a URL
// $("#myform").buildForm("http://example.com/myform.json");
</script>
 
<form id="myform"></form>

The advantage is, that the form definition and the configuration of JavaScript functionality can be kept in the same format. Check out the examples page for more complex forms and some jQuery UI and the extension chapter to see how to customize and extend your forms.

Worth mentioning: Since JSON (or XML for that matter) are quite abstract formats and the form generation itself is done by the client, an extension for generating browser specific HTML5 forms is currently under development.

If you have questions or want to contribute (e.g. by adding dForm support to your own form related plugin :) visit the plugin homepage on GitHub.