/docs/tutorial/page-1.md

  1Getting Started with Manos
  2==========================
  3
  4This tutorial will get you writing your first Manos apps in no time.
  5
  6We assume you already have Manos installed on your machine.  If you don't check out
  7the Installation Guide. To ensure you have Manos running try typing the manos --help
  8command in a terminal.
  9
 10    manos --help
 11
 12For this tutorial we are going to create a simple URL shortening service. It will allow
 13users to submit links for shortening and will also keep track of how many times a shortened
 14link has been clicked.
 15
 16
 17Create a Manos Project
 18-------------------------------
 19
 20To create a Manos application all you need to do is run the following command:
 21
 22    manos --init <YourApplicationName>
 23
 24Make sure you don't have any spaces in your application name. An app name should just be letters,
 25digits and underscores. 
 26
 27We'll call our app Shorty;
 28
 29    manos --init Shorty
 30
 31This will create a folder named Shorty with a few files and subfolders:
 32
 33
 34    Shorty/
 35    Shorty/Content/css/handheld.css
 36    Shorty/Content/css/style.css
 37    Shorty/Content/js/plugins.js
 38    Shorty/Content/js/dd_belatedpng.js
 39    Shorty/Content/js/jquery-1.4.2.min.js
 40    Shorty/Content/js/profiling
 41    Shorty/Content/js/profiling/charts.swf
 42    Shorty/Content/js/profiling/config.js
 43    Shorty/Content/js/profiling/yahoo-profiling.css
 44    Shorty/Content/js/profiling/yahoo-profiling.min.js
 45    Shorty/Content/js/script.js
 46    Shorty/Content/js/modernizr-1.5.min.js
 47    Shorty/Shorty.cs
 48    Shorty/StaticContentModule.cs
 49
 50
 51We'll worry more about these files later in the tutorial, but for now here's a
 52quick overview of what we've got:
 53
 54 *    **Content/**: Static content like images, js and css goes here.  The supplied files are based on the HTML5 Boilerplate project.
 55 *    **Shorty.cs**: This is the main entry point for our app.  Its the first thing that will be loaded by Manos.
 56 *    **StaticContentModule.cs**: The static content module is in charge of handling static content, things like css files and images.
 57If you are hosting your static content on a separate server you can remove this module.
 58
 59
 60Exploring Shorty.cs
 61--------------------------
 62
 63The first file we are going to deal with is Shorty.cs.  This file is the main entry point into our application and is where we
 64handle our top level routing. Routes can be added to our app in the constructor or by using method attributes.  If you look at Shorty.cs
 65you'll see there has already been a route to the StaticContentModule added for you:
 66
 67    Route ("/Content/", new StaticContentModule ());
 68
 69The Route method will route all HTTP calls that match the supplied pattern, in this case "/Content/" to the supplied module or action. Here we
 70have routed every url request that starts with "/Content/" to the StaticContentModule.
 71
 72If we just want to handle certain types of HTTP method requests we can use the corresponding Manos routing method. So if we just want to route
 73HTTP GET requests to the StaticContentModule, we could change the above code to look like this:
 74
 75    Get ("/Content/", new StaticContentModule ());
 76
 77We'll talk more about routes later.
 78
 79
 80Hello, Manos World
 81------------------
 82
 83Routes don't necessarily have to go to modules, we can also route them to actions.  An action is any function that accepts a single IManosContext
 84parameter.  So lets create our first action, add this line right above the static content route.
 85
 86    Get ("/", ctx => ctx.Response.End ("Hello, Manos World!"));
 87
 88What we've done here is created a route using the "/" path.
 89
 90Instead of creating an action method to handle the request we've just used a simple lambda expression that takes the IManosContext and sends
 91"Hello, Manos World!" as the response.
 92
 93Routes can be created with simple paths like this or we could create more complex
 94routes with regular expressions. Something like Get ("/d.d", ...) would route "/dad" and "/dfd". There is also support for simple pattern matching
 95on routes, so things like Get ("/Article/{name}", ...).
 96
 97Note that we called a method named End to write our data.  End is overloaded with all the same arguments as Write so you don't have to do things like:
 98
 99    response.Write (<some data>);
100    response.End ();
101
102All Manos actions must have End called when they are finished.  End is not called automatically because many scenarios require the Stream to live longer than the action method.  Think of Actions as a message from the browser saying 'please send me some data', not necessarily a request and response lifecycle.  In comet style applications the response will live much longer than the Action method.
103
104
105Building and Running Manos Apps
106-------------------------------
107
108To test out your application first you'll need to build it. You can build the app with the manos build command.
109
110If you aren't already in the Shorty directory:
111
112    cd Shorty/
113
114and now you can build:
115
116    manos --build
117
118To run this app all we'll use the manos --server command. This command loads the local compiled manos app
119and sets up hosting for it.
120
121    manos --server
122
123Once the application is running you can check it out by navigating your browser to http://localhost:8080/
124
125---
126
127Continue the tutorial in [part two](./page-2.md).
128
129