camping 2.1.531 → 3.0.0

data/book/03_more_about_controllers.md

@@ -0,0 +1,124 @@
+# Controllers
+
+What are these _controllers_? This is a good question for a Camping newb. In the [MVC
+paradigm](http://en.wikipedia.org/wiki/Model%E2%80%93View%E2%80%93Controller#Overview)
+a Models could be described as a very weird and hard to understand thing.
+
+When you look in the browser's navigation bar, you will see something like:
+
+`http://localhost:3301/welcome/to/my/site`
+
+The Universal Resource Locator (URL) is showing you a "structured" web site
+running inside a server that listening in the `3301` port. The site's internal
+routes are "drawing" the path: Inside the `root_dir/` is the directory `/welcome/`
+and it recursively adds the names of the deeper directories: "to", "my", and "site" (`./to/my/site`).
+
+But that is virtual, the site doesn't really have a directory structure like that...
+That would be useless. The site uses a "route drawing system" to get _control_
+of that route; this is what *the controller* does.
+
+## Camping Routes and Controllers
+
+In camping, each _capitalized_ word in a camel-cased contoller declaration is like the
+words between each slash in a URL. For example:
+
+```ruby
+WelcomeToMySite
+```
+will draw the route:
+
+```
+/welcome/to/my/site
+```
+
+Or you could instead use the weird R helper to get more specific control of your routes:
+
+```ruby
+Welcome < R '/welcome/to/my/site'
+```
+
+All of this will be declared inside the Nuts::Controllers module.
+
+## Controller Parameters
+
+Controllers can also handle your application's parameters. For example,
+when the client asks for a route like `/post/1`, a static web server would
+look out for the directory named "1" and serve the content in that directory.
+It would need a lot of "number-named" directories to do that simple job.
+
+But in our case, the controller draws a dynamic path for every asked post. We just need
+to tell him about the size of the flock.
+
+In camping, adding `N` or `X` to a controller's declaration tells it to expect a parameter.
+The `N` suffix, which will match a numbered route, is declared like this:
+
+```ruby
+class PostN
+```
+
+With this controller, adding a number to the simple `/post` route in your browser will trigger this route. For example,
+either of these will work:
+
+```
+/post/1
+/post/99
+```
+
+But this `N` route will not match against a word. For example, a request for `/pots/mypost`
+will return 404 (Not Found). Because the `PostN` declaration will only match _Numeric_ parameters.
+
+If you would like to match something other than a number, you should use the `X` suffix:
+
+```ruby
+class PostX
+```
+
+The _X_ tells the controller to match anything, including number and words. For example, it will match:
+
+```
+/post/1
+/post/99
+/post/mypost
+```
+
+But it will NOT match: `/post/mypost/1` (or anything that has "/" in the name). Since slashes signify
+deeper directories, you would need to tell the controller to recognize the deeper directory before using a parameter.
+You can do this using camel case, followed by the "X" or "N":
+
+```ruby
+class PostMypostX
+```
+
+## Getting parameters from the controller
+
+Ok, we have the controller that match parameters; and now what?
+
+Say that you want to show the post number N requested in the controller. You'll need the
+number.
+
+```ruby
+class PostN
+    def get number
+        p "the parameter was: #{number}"
+    end
+end
+```
+
+Please, do not try that at home. It's very dirty to use a _view_ inside the controller (more on that soon).
+
+The method `get`, for the `/post/N route`, will take a parameter. That number will by
+inside the "number parameter". From now, if you want to route something to your
+post route, you can write a link 100% pragmatically like this:
+
+```ruby
+@post=rand 1..9
+a "See the post number: #{@post}",:href=>R(PostN,@post)
+```
+
+For that example, we just choose a random post and then displayed a link to its path.
+
+> but you told me that I shouldn't write that in the controller...
+
+Yep...I said that. These things are called "views" because they will
+be in the user's face. Our client will not see the controllers; they will be hidden from them when they visit our site.
+Our client will only see the [views](04_more_about_views.md).

data/book/04_more_about_views.md

@@ -0,0 +1,118 @@
+# Views
+
+The view is the scene for our show. The user is sitting in his chair
+(the browser) and see on screen actors (the view). Enjoy the show
+without think that behind the scenes there is a whole team. The team
+behind the cameras is our controller but the user don't care about
+that.
+
+The user only see their browser and our application is just and HTML document.
+
+
+## Camping Views
+
+Inside the Nut::Views module, we will write methods. That method shall called
+with the render sentence. The views do not use class.
+
+```ruby
+module Nust::Views
+
+   def post_number
+      p "you asked the post number @postn"
+   end
+
+end
+```
+
+Well, well, that was a views, but now: How we show it to the user? We will call
+the view from the controller. And we pass to the view all the parameters that we
+want to show.
+
+```ruby
+ module Nuts::Controller
+   class PostN
+       def get number
+         @postn=number
+         render :post_number
+       end
+    end
+ end
+```
+
+We just declared a controller for the route /post/(number here). When the browser
+ask for the route /post/1 the controller will be trigged and the get
+method defined inside the class, will respond to the "get" request in
+the web server.
+
+The first instruction in our controller, will by write the number in the @postn
+variable and then "render"
+
+But what is `render`? This sentence is not from ruby, this is a camping's
+sentence and mean: -show now the view named (:symbol). It take a symbol
+as parameter, and the symbol's name, shall be one of these methods
+declared in the views. Now we have only a view named post_number.
+
+You could "associate" it MENTALLY as a hash like this:
+
+```ruby
+def my_view => render :my_view
+```
+
+But that will happen in your mind. In camping these will be happening in
+the modules, not in a hash, therefore, their are very associated too.
+
+Imagine your applications as a big building. The controller as the
+corridors and the views as the offices. Where are the offices and we do
+in each office?
+
+## Views and Controllers
+
+Model View and Controller, are joined but not scrambled. The views use
+R(ControllerName) for call the controllers and "move". The controller
+will use "render" for call the view.
+
+-And now... what do you think we have behind the curtains?
+
+```ruby
+module Why::Controllers
+   class CircusCourtains
+      def get
+         require 'endertromb'
+         @monkey=Endertromb::Animals::StartMonkey.new :frog=>true,:place=>:hand
+         render :behind_curtain
+      end
+   end
+end
+```
+
+-OMG! It's a monkey with a start in the hand!
+
+-yes, ladies and gentleman, we have it just here for you
+
+```ruby
+module Views
+   def behind_curtain
+      p @monkey
+   end
+end
+```
+
+No, we don't have it behind the curtains, but the user believe it. There
+is the view, enjoy the show.
+
+## Template engine
+
+We spoke about the views, and HTML, but we are not using html's tags for
+our view...
+
+How happening this?
+
+The rubyist have not necessary to write HTML code. Exists some options
+named template. That the "p" before the `@monkey` in the view. A template
+engine is a kind of "pseudo-language" for handle HTML code. In some
+template engines you will also write HTML in a more easy way. Their also
+handle ruby data inside HTML. Templates engine are the wheels of the
+views.
+
+In camping, you will write views using a template engine named
+[Markaby](05_more_about_markaby.md) and you will write HTML pragmatically.

data/book/05_more_about_markaby.md

@@ -0,0 +1,173 @@
+## Where Markaby's come from
+
+A great musician, writer and programmer (and a bit crazy) named
+[_why](http://en.wikipedia.org/wiki/Why_the_lucky_stiff) wrote camping.  Before
+banish himself to the dimension from where him come (a place named "the
+keyhole"); hi also wanted, that the developers, should have not write pure HTML
+code. Him dream with a world were the programmer write html in their
+programming language.
+
+Rails users are very hard guys. Their eat the soup using a fork and generate
+HTML views in a template engine named Erb. Their use a long set of weird tools
+for generate that Embedded Ruby (erb), their call it "scaffolding". The basic
+idea is: "let me rails write html code for you" Many framework have in the
+README a line that say: "support more populars template engines" but normally
+peoples uses the default in the framework.
+
+"Mab" is the template engine used by default in camping. _why Wrote the first
+implementation named Markaby and then, judofyr and Jenna, power-up markaby
+writing a more compact version of it.
+
+While you are writing with mab, will see ruby code front you are eyes, but your
+mind, will be seen pure HTML without tags. We will be "metaprograming HTML
+code". In order to show a Header-1 tag, we just call a method named h1 and send
+the content as parameter. It will make the dirty work writing all the tags just
+like this:
+
+```ruby
+h1 'This is a header one'
+```
+
+"Write HTML pragmatically" mean: -write html using not html tags.
+Markaby is a way for write Hyper Text Markup Language (HTML) using Ruby.
+That do not mean "html knowledge unneeded"
+
+But that is only the beginning, we can do more wild things.
+
+## Writing HTML pragmatically
+
+For example: if we want show a table for show users and their real
+names:
+
+```ruby
+# call me using render :users
+# from a get in the controllers
+def users
+table do
+th 'User'
+th 'Realname'
+   @users.each do |user,realname|
+      tr do
+           td user
+           td realname
+      end # tr
+   end # each
+end # table
+end # def
+```
+
+Take a look better [here](https://github.com/camping/mab/blob/master/README.md)
+
+## Markaby and the layout
+
+There is a special view named "layout". The layout, is view that will be
+rendered each time any other view are rendered. In fact, the layout will take
+the other views for compose himself. The layout is rendered before anything.
+
+Each time you use the "render" sentence, you will be rendering the
+layout and the desired view. Because that, wee need some "special"
+tweaks in the layout. It must have a door with a poster that say:
+"other view will enter using this door"
+
+The layout will be rendered, and in some place you will put the other view.
+This will be done with the "yield" sentence. Put the yield sentence whenever
+you want rendering all the other views.
+
+This is very useful, for example: We wan to write a footer in ALL the
+pages that we are rendering. You can write the footer in every views
+definition, or just write the footer in the layout.
+
+Without a layout, if you render the table's views. Camping will drop out the
+table just like that to the browser's render. It will not draw any body or head
+tag. Writing body and head in every page could be a very bored task. But do not
+worry, the layout is here.
+
+Lets write our layout, with all the HTML shape and including a footer
+
+```ruby
+def layout
+
+  html do
+    head do
+      title 'My Blog'
+    end
+
+     body do
+
+      div.wrapper! do
+        self << yield
+     end
+
+      p.footer! do
+        text 'Powered by Camping'
+     end
+    end
+  end
+
+end # layout
+```
+Well, that was wild. Let's see: First we have everything inside a block, the
+html's block. At the next level, the first block is head, that is rendering
+something like:
+
+```html
+<html>
+   <head>
+      <title> My Blog </title>
+   </head>
+</html>
+```
+
+If you look at the HTML's source of camping, you will see a VERY LOOOONG
+line with every the HTML code, better do not look it.
+
+Then, come the more weird thing. A div with a estrange sentence:
+
+```ruby
+self << yield
+```
+That mean: -put just right here, the other view called.
+
+In that place, in the center of the div.wrapper, will be placed all our
+views called using render's sentence.
+
+When you call:
+
+```ruby
+render :someview
+```
+
+Camping will rendering before, the layout view, and put all the content
+of "someview" inside div.wrapper! You shall not write a lot of tag like
+head or title.
+
+Finally, it will be rendering a "p" named footer. That will be the footer in
+all our pages.
+
+## Tip
+
+What would happen? If you do this in the layout:
+
+```ruby
+head do
+    title "#{@title}"
+end
+```
+
+Hummm... You could "rewrite" the titles of each pages. In the
+controller, you just need to declare the variable @title, and that will
+be the title for that page.
+
+Remember:
+
+* Views take @variables from the controller
+* Layout is rendered before any called view.
+* Markaby is ruby code and it can be embedded
+* View's modules use not `class` declarations
+
+In the table example, we used a hash named @users. But. Where come from all
+thats data?
+
+It come from the controller, but the controller took it from the
+[model](06_more_about_models.md). The M of the MVC, the layer who stare
+the whole bunch of persistent data.

data/book/06_more_about_models.md

@@ -0,0 +1,58 @@
+## More about Models
+
+Models are used to persist data. That data could be anything. The balance in a bank account, A list of your favorite restaurants, your blog posts, you name it. Camping uses the *ActiveRecord* Gem, an ORM (object-relational mapper), that maps Database tables to objects.
+
+We define models by inheriting from a base model named Base:
+
+```ruby
+class User < Base end
+```
+
+Very creative. Base is really just an alias for ActiveRecord, nothing fancy. We put our models into a namespaced module named after our App:
+
+```ruby
+Camping.goes :Nuts
+
+module Nuts::Models
+    class User < Base end
+end
+```
+
+Remember from earlier that Models need to be defined before our controllers, otherwise we can't use em. So keep them close to the top.
+
+The new User model we've defined has a small problem, it's completely empty, it doesn't have any data that can be stored in it. Camping models map Database tables to objects automatically, but this model doesn't have a database table yet. To fix that we'll create a migration:
+
+```ruby
+Camping.goes :Nuts
+
+module Nuts::Models
+    class User < Base; end
+
+    # Define a migration to add users
+    class AddUser < V 1.2
+        def self.up
+            create_table User.table_name do |t|
+                t.string :username
+                t.string :email
+                t.timestamps
+            end
+        end
+
+        def self.down
+            drop_table User.table_name
+        end
+    end
+end
+```
+
+Databases, like birds, migrate. Migrations move our database from one configuration to another. In our case we're adding users. So cool. User's should be able to log in, sign up, maybe make some pages. We could make the next myspace. To get our database to make a users table we need force our app to create the schema.
+
+```ruby
+def Nuts.create
+    Nuts::Models.create_schema
+end
+```
+
+Now that puppy will migrate when we launch our app.
+
+Our Users now have greater hope to survive. So great. I love it.

data/book/06_rules_of_thumb.md

@@ -0,0 +1,143 @@
+# Keep it in one file
+
+Generally, the idea is keep your app small and store in a single file. Your app will end up with four sections:
+
+1. Camping setup
+
+```ruby
+do
+  require 'rubygems'
+  require 'camping'
+  Camping.goes :Blog
+end
+```
+
+2. Models
+
+```ruby
+do
+  module Blog::Models
+    class User < Base; end
+    class Post < Base; belongs_to :user end
+  end
+end
+```
+
+3. Controllers
+
+```ruby
+do
+  module Blog::Controllers
+    class Index < R '/'
+      def get; render :index end
+    end
+  end
+end
+```
+
+4. Views
+
+```ruby
+do
+  module Blog::Views
+    def layout
+      html { body { self << yield } }
+    end
+    def index
+      div.page "Welcome!"
+    end
+  end
+end
+```
+
+# What if things get out of hand?
+
+If you’re piling up models and controllers, your file may begin to exceed 200 lines, which means lots of paging up and down. Go ahead and store your models, controllers and views in three separate files. Your directory structure should end up like this:
+
+```
+blog.rb
+blog/
+  models.rb
+  controllers.rb
+  views.rb
+```
+
+(Note, for the development reloading to work, your required files (models.rb etc.) must be in a subdirectory named after your app.)
+
+Your blog.rb would still contain the setup (No. 1):
+
+```ruby
+do
+  require 'rubygems'
+  require 'camping'
+  Camping.goes :Blog
+  require 'blog/helpers'  # if needed
+  require 'blog/models'
+  require 'blog/views'
+  require 'blog/controllers'
+end
+```
+
+# Small apps, many mounts
+
+Rather than building huge Camping apps, the idea here is to write small apps which can each be mounted at directories on your web server. One restriction: these apps will share a database. However, this allows applications to access each other’s tables and simplifies setup and configuration.
+
+To mount multiple camping apps, you can `require` the app files. When you mount more than one app they won't be mounted according to their parent directory, routing is explicit. If you'd like to give one of your apps a prefix, set the `url_prefix` option in your app:
+
+```ruby
+# camp.rb
+require 'camping'
+Camping.goes :Blog
+require 'blog.rb'
+
+Camping.goes :Wiki
+require 'wiki.rb'
+Wiki.set :url_prefix, 'tepee/'
+
+Camping.goes :Charty
+require 'charty.rb'
+Charty.set :url_prefix, 'charts/'
+
+```
+
+By default Camping will look for a file called `camp.rb` in the root where Camping is executed. You can also supply a ruby filename to load your apps from there.
+
+You’ll end up with:
+```
+http://localhost:3301/blog, a blogging app.
+http://localhost:3301/tepee, a wiki app.
+http://localhost:3301/charts, a charting app.
+```
+
+In your app, if you’re using the R() method to build your links, Camping will make sure the mount is added properly to links.
+
+For example, if R(View, 1) is used in the blogging app mounted at /blog, the link will be written as /blog/view/1. If later you mount the blog at /articles instead, Camping will write the link as /articles/view/1.
+
+# Give us a create method
+
+```ruby
+do
+  def Blog.create
+    # Code in here will run when the app starts, or reloads, but not when requests happen.
+    # You can use it to create database bits and pieces, files, folders, and so on.
+  end
+end
+```
+
+# The camping server
+
+The Camping Server is basically a set of rules. At the very least, The Camping Server must:
+
+- Load all Camping apps in a directory.
+- Load new apps that appear in that directory.
+- Mount those apps according to their filename. (e.g. blog.rb is mounted at /blog.)
+- Run each app’s create method upon startup.
+- Reload the app if its modification time changes.
+- Reload the app if it requires any files under the same directory and one of their modification times changes.
+- Support the X-Sendfile header.
+
+# Bin/camping
+
+Camping comes with a very simple version of The Camping Server. bin/camping uses either WEBrick or Mongrel (if you have it installed.)
+
+Run it like this: `camping /var/www/camping/*.` It will follow all of the rules above.

data/book/07_philosophy.md

@@ -0,0 +1,23 @@
+# Why's origin story
+
+The philosophy of Camping is a long and winding tail of origin, met by the ideals for the future of many mad hackers. The story of camping begins in 2006 on a cool winters night in Pittsburgh, where we find a hacker hunched over his computer, typing ruby code with his right hand and playing a laser theremin with his left. To the spooky sounds of his own left hand, he hacked through the night. This night, camping was born.
+
+Lets step back though time for a minute though, to the origins of this man. Once an upstanding PHP developer, he grew weary and tired of his day job, writing endless login pages and checkouts. He dreamt of a world free of his C-flavoured prison. Tales of promised lands, where snake powered ponies run wild, dancing around campfires full of rubies glowing red as blood. They worked him to the bone, until one day his bones just up and left. He couldn't do it any longer! He was on a mission to find that fire which fueled his dreams.
+
+In seclusion, there isn't much known about this odd man's life. Some say he went crazy. Others say he became a well respected professor. Still others suggest both of these are true. But what we do know, is that it is here, that he developed his love of chunky bacon, foxes, and children shaped like keyholes.
+
+And so he went on, crafting his mad writings, scribblings of foxes explaining ruby symbols, and making strange music. Soon this man found himself concerned that children had no good way to make their own eBay competitors. For this reason, he created Camping.
+
+The End.
+
+# Actual philosophy
+
+Why The Lucky Stiff is no longer around, so those of us who contributed early on to Camping have since become its caretakers. We continue to push the framework foward, to be more compact, to be faster, easier, more fun. These are our guiding principals:
+
+- Camping is for everyone. It sure is great to turn an idea in to a single ruby file which creates a website. It's also great to organise an app in to several files sometimes. You can plug bits together all in a row, and grow your evil monkey in to an entire army of evil circus animals!
+- Camping isn't for making money. You can make money using camping. Nobody will stop you. But we don't have any buzzwords to offer, we won't make your unit tests easier, nor help you do market research. Our main contributors certainly aren't using camping in large scale deployments, and while camping is blazingly fast, we have no idea how well it would work if you ran it on lots of servers!
+- Camping is really simple. You don't need to know much, to make nifty things with it, and you can really easily add more detailed bits as needed. Your brain will thank you.
+- Camping apps are easy to automatically reload. Because most of them are just one ruby file.
+- Camping encourages experimentation. The whole thing is an experiment.
+- If you're new to ruby, there are heaps of quirky hacks in here which will teach you all sorts of obscure, nifty, and outright strange things about the Ruby language.
+- Camping doesn't take itself too seriously. We're a fun bunch, living on the edge of zany!