docs/migrate.html

<html>
	<head>
		<title>Express - node web framework</title>
		<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
		<style>
			#tagline {
			  margin-left: 75px;
			  margin-bottom: 30px;
			  color: rgba(255,255,255,0.7); }
			html {
			  background: #1c1c1c url(images/bg.tile.jpg); }

			body {
			  margin: 0;
			  padding-bottom: 30px;
			  font: 14px/1.4 "Helvetica Neue", "Lucida Grande", "Arial";
			  font-size: 14px;
			  line-height: 1.5;
			  -webkit-font-smoothing: antialiased;
			  background: url(images/bg.jpg) 50% 0 no-repeat;
			  color: #8b8b8b; }

			* {
			  outline: none; }

			em {
			  color: white; }

			a img {
			  border: none !important; }

			a {
			  font-weight: bold;
			  text-decoration: none;
			  color: white;
			  -webkit-transition-property: opacity, -webkit-transform, color, background-color, padding, -webkit-box-shadow;
			  -webkit-transition-duration: 0.15s;
			  -webkit-transition-timing-function: ease-out; }
			  a:hover {
			    opacity: 0.8; }

			h1, h2, h3, h4 {
			  margin: 45px 0 0 0;
			  color: white;
			  text-shadow: 1px 2px 2px rgba(0,0,0,0.6); }

			h3 {
			  font-size: 18px; }
			h4 {
			  margin-left: 10px;
			  font-size: 14px;
			}

			pre {
			  margin: 20px 10px;
			  padding: 25px 20px;
			  background: rgba(0,0,0,0.5);
			  border: 1px solid #323232;
			  -webkit-box-shadow: 1px 2px 2px rgba(0,0,0,0.6);
			  -moz-box-shadow: 1px 2px 2px rgba(0,0,0,0.6);
			  -webkit-border-radius: 5px;
			  -moz-border-radius: 5px; }

			code {
			  font-family: "Helvetica Neue", "Lucida Grande", "Arial"; }

			ul {
			  margin: 15px 0;
			  padding: 0 0 0 35px; }
			  ul li {
			    margin: 0;
			    padding: 2px 0;
			    list-style: square; }
          ul li ul {
            margin: 0;
            padding-left: 12px;
          }

      .man-name, #Express { display:none; }

			.sect {
			  margin-left: 40px; }
			img {
			  margin-left: 20px;
			  margin-bottom: 15px;
			}

			#logo {
			  display: block;
			  margin-left: 30%;
			  margin-bottom: 30px;
			  width: 194px;
			  height: 51px;
			  background: url(images/logo.png) 0 0 no-repeat;
			  text-indent: -99999px; }
			  #logo:hover {
			    opacity: 0.7; }
			  #logo:active {
			    opacity: 0.3; }

			#ribbon {
			  position: fixed;
			  top: 0;
			  right: 0;
			  z-index: 2; }

			#wrapper {
			  width: 100%;
			  min-height: 800px;
			  background: url(images/top.png) 0 0 repeat-x; }

			#container {
			  margin: 0 auto;
			  padding-top: 80px;
			  width: 550px; }

			#toc {
				position: fixed;
				top: 0;
				left: 0;
				margin: 0 0 0 15px;
				padding: 15px;
				height: 100%;
				background: rgba(0,0,0,0.2);
				overflow: auto;
				border-right: 1px solid rgba(255,255,255,0.05);
			}
			#toc li {
				padding: 0;
				list-style: none;
			}
			#toc li a {
				font-size: 11px;
			}
			#menu {
			  margin-left: 80px;
			  padding: 0;
			  padding-bottom: 30px; }
			  #menu li {
			    display: inline;
			    list-style: none; }
			    #menu li a {
			      display: block;
			      float: left;
			      margin: 0 2px;
			      padding: 3px 15px;
			      background: rgba(0,0,0,0.2);
			      -webkit-border-radius: 8px;
			      -moz-border-radius: 8px;
			      -webkit-box-shadow: 1px 2px 2px rgba(0,0,0,0.6);
			      -moz-box-shadow: 1px 2px 2px rgba(0,0,0,0.6);
			      -webkit-transition-property: opacity, -webkit-transform, color, background-color, -webkit-box-shadow;
			      -webkit-transition-duration: 0.15s;
			      -webkit-transition-timing-function: ease-out; }
			      #menu li a:hover,
			      #menu li a.active {
			        background: rgba(0,0,0,0.5); }
			      #menu li a:active {
			        background: rgba(0,0,0,0.1);
			        -webkit-box-shadow: 1px 1px 1px rgba(0,0,0,0.4);
			        -moz-box-shadow: 1px 1px 1px rgba(0,0,0,0.4); }
		</style>
		<script>
		  $(function(){
		    $('.section').hide();
		    $('.toggle, a.section-title').toggle(function(){
		      $(this).siblings('ul').fadeIn(300);
		      return false;
		    }, function(){
		      $(this).siblings('ul').fadeOut(300);
		      return false;
		    });
		  });
		</script>
	</head>
	<body>
		<a href='http://github.com/visionmedia/express'> 
		  <img alt='Fork me on GitHub' id='ribbon' src='http://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png' /> 
		</a>
		<div id="wrapper">
			<div id="container">
				<a href='http://github.com/visionmedia/express' id='logo'>Express</a> 
				<p id="tagline">
				   High performance, high class web development for
				  <a href="http://nodejs.org">Node.js</a>
				</p>
				<ul id="menu">
					<li><a href="index.html">Home</a></li>
					<li><a href="guide.html">Guide</a></li>
					<li><a href="screencasts.html">Screencasts</a></li>
					<li><a href="applications.html">Applications</a></li>
				</ul>
<div class='mp'>
<h2 id="Express">Express</h2>
<p class="man-name">
  <code>migrate</code>
</p>
<h3 id="Built-On-Connect">Built On Connect</h3>

<p>Express 1.x is written to run on-top of the <a href="http://extjs.github.com/Connect">Connect</a> middlware
framework, thus the <em>Plugin</em> has been replaced by Connect's middleware. By abstracting our middleware
to Connect we allow additional community frameworks to develop robust, high-level frameworks using
the same technologies as Express.</p>

<h3 id="Creating-Applications">Creating Applications</h3>

<p>Previously due to legacy code implemented in the early days of node,
Express unfortunately had some globals. The DSL would previously be
accessed as shown below:</p>

<pre><code>require('express');

configure(function(){
    // app configuration
});

get('/', function(){
    return 'hello world';
});
</code></pre>

<p>Now we utilize the CommonJS module system appropriately, and
introduce <em>express.createServer()</em> which accepts the same arguments
as <em>http.createServer()</em>:</p>

<pre><code>var express = require('express'),
    app = express.createServer();

app.configure(function(){
    // app configuration
});

app.get('/', function(req, res){
    res.send('hello world');
});
</code></pre>

<p>Express 1.x does <em>not</em> currently allow returning of a string.</p>

<h3 id="Plugins-vs-Middleware">Plugins vs Middleware</h3>

<p>Previously Express was bundled with plugins, which were essentially what
are now Connect middleware. Previously plugins would be utilized in a manor
similar to below:</p>

<pre><code>use(Logger);
use(MethodOverride);
use(Cookie);
</code></pre>

<p>Which we can now <em>use()</em> within our app, or pass to the <em>express.createServer()</em> method:</p>

<pre><code>var app = express.createServer(
    express.logger(),
    express.methodOverride(),
    express.cookieDecoder()
);
</code></pre>

<p>or:</p>

<pre><code>var app = express.createServer();

app.use(express.logger());
app.use(express.methodOverride());
app.use(express.cookieDecoder());
</code></pre>

<p>For documentation on creating Connect middleware visit <a href="http://extjs.github.com/Connect/#Middleware-Authoring">Middleware Authoring</a>.</p>

<h3 id="Running-Applications">Running Applications</h3>

<p>Previously a global function <em>run()</em>, was available:</p>

<pre><code>run();
</code></pre>

<p>The new <em>express.Server</em> has the same API as <em>http.Server</em>,
so we can do things like:</p>

<pre><code>app.listen();
app.listen(3000);
</code></pre>

<h3 id="Route-Parameters">Route Parameters</h3>

<p>Previously we could use <em>this.param()</em> to attempt
fetching a route, query string, or request body parameter:</p>

<pre><code>get('/user/:id', function(){
    this.param('id');
});
</code></pre>

<p>Polymorphic parameter access can be done using <code>req.param()</code>:</p>

<pre><code>app.get('/user/:id', function(req, res){
    req.param('id');
});
</code></pre>

<p>Route parameters are available via <code>req.params</code>:</p>

<pre><code>app.get('/user/:id', function(req, res){
    req.params.id;
});
</code></pre>

<h3 id="Passing-Route-Control">Passing Route Control</h3>

<p>Old express had a weak notion of route passing,
which did not support async, and was never properly
implemented for practical use:</p>

<pre><code>get('/', function(){
    this.pass('/foobar');
});
</code></pre>

<p>Now Express has access to Connect's <em>next()</em> function,
which is passed as the third and final argument. Calling <em>next()</em> will
pass control to the next <em>matching route</em>, or continue down the stack
of Connect middleware.</p>

<pre><code>app.get('/user/:id?', function(req, res, next){
    next();
});

app.get('/user', function(){
    // ... respond
});
</code></pre>

<h3 id="View-Rendering">View Rendering</h3>

<p>View filenames no longer take the form <em>Express</em>.<em>TYPE</em>.<em>ENGINE</em>,
the <em>Content-Type</em> can be set via <em>res.contentType()</em> or
<em>res.header()</em>. For example what was previously <em>layout.html.haml</em>,
should now be <em>layout.haml</em>.</p>

<p>Previously a view render looked something like this:</p>

<pre><code>get('/', function(){
    this.render('index.html.haml', {
        locals: { title: 'My Site' }
    });
});
</code></pre>

<p>We now have <em>res.render()</em>, however the options passed to <a href="http://github.com/visionmedia/haml.js">haml</a>, <a href="http://github.com/visionmedia/jade">jade</a>, and others
remain the same.</p>

<pre><code>app.get('/', function(req, res){
    res.render('index.haml', {
        locals: { title: 'My Site' }
    });
});
</code></pre>

<p>Previously rendering of a collection via <em>partial()</em> would look something like this:</p>

<pre><code>this.partial('comment.html.haml', { collection: comments });
</code></pre>

<p>Although this worked just fine, it was generally to verbose, the similar but new API
looks like this, as <em>partial()</em> is <em>always</em> passed as a local variable:</p>

<pre><code>partial('comment.haml', { collection: comments });
</code></pre>

<p>To make things even less verbose we can assume the extension when omitted:</p>

<pre><code>partial('comment', { collection: comments });
</code></pre>

<p>And once again even further, when rendering a collection we can simply pass
an array, if no other options are desired:</p>

<pre><code>partial('comments', comments);
</code></pre>

<h3 id="Redirecting">Redirecting</h3>

<p>Previously you would</p>

<pre><code>this.redirect('/somewhere');
</code></pre>

<p>However you would now:</p>

<pre><code>res.redirect('/somewhere');
res.redirect('/somewhere', 301);
</code></pre>

<h3 id="HTTP-Client">HTTP Client</h3>

<p>Previously Express provided a high level http client, this library is no more
as it does not belong in Express, however it may be resurrected as a separate module.</p>

<h3 id="Core-Extensions">Core Extensions</h3>

<p>Express is no longer dependent on the <a href="http://github.com/visionmedia/ext.js">JavaScript Extensions</a> library, so those of you using the methods provided by it such as <code>Object.merge(a, b)</code> will need to
roll your own, or install the module via:</p>

<pre><code>$ npm install ext
</code></pre>

</div>
			</div>
		</div>
	</body>
</html>