Getting started guide

_includes/gist.html

@@ -0,0 +1 @@
+<script src="http://gist.github.com/{{ gist_id }}.js?file={{ gist_file }}">// Gist is loading...</script>

_layouts/default.html

@@ -7,6 +7,7 @@
     <link rel="stylesheet" href="/css/base.css">
     <link rel="stylesheet" href="/css/skeleton.css">
     <link rel="stylesheet" href="/css/styles.css">
+    <link rel="stylesheet" href="http://yandex.st/highlightjs/6.2/styles/default.min.css">
     <script src="http://cachedcommons.org/cache/modernizr/1.5.0/javascripts/modernizr-min.js"></script>
     <script src="/js/prefixfree.min.js"></script>
   </head>

guides/basics/getting-started.md

@@ -3,42 +3,54 @@ layout: index
 title: "Getting started"
 ---
 
+{% assign gist_id = 2731308 %}
+
 ## Getting started
 
-### The most important thing to know
+### ZOMG! Another MVC Framework...
 
-Joosy is not an MVC framework. It addresses the same problems but it's not based clearly on a popular MVC paradigm. Nor it is an MVVM. Joosy is an active view for your server-side framework (mainly the Rails). It was created to complement and cooperate with backend. Not to be an abstraction. Therefore you'll probably like it if you are:
+Joosy is not an MVC framework. It addresses the same problems but it's not based clearly on a popular MVC paradigm. Nor it is an MVVM. Joosy is an active view for your server-side framework (mainly the [Rails](http://rubyonrails.org/)). It was created to complement and cooperate with backend. Not to be an abstraction. Therefore you'll probably like it if you are:
 
 * Rails developer
 * Use CoffeeScript heavily
 * Like HAML (not really required)
 
 The first point is required to fill Joosy the right way. It was greatly inspired by the approach Rails promotes. Unlike most of alternatives we don't stay away from a real-life troubles. Nor we expect the community to decide on it's own. We try to give some kind of convention for each of them. Just like in Rails you should concetrate on what you do. Not how you do it.
 
-CoffeeScript is an alma-mater of Joosy. In theory you can use Joosy with a plain JS but you won't be happy. We use the Coffee meta posibilities heavily. Joosy is class-based and relays on CoffeeScript static methods prototype magic. Without having requirement to stay JS-compatible we created an interface that is as clear as possible.
+[CoffeeScript](http://rubyonrails.org/) is an alma-mater of Joosy. In theory you can use Joosy with a plain JS but you won't be happy. We use the Coffee meta posibilities heavily. Joosy is class-based and relays on CoffeeScript static methods prototype magic. Without having requirement to stay JS-compatible we created an interface that is as clear as possible.
 
-We've added some spice to the Rails+Coffee combo. Applause, the Sugar.js. This incredible library extends the JS the way you are used to with an ActiveSupport. All the comfortable features are here: `[].first`, `'foo'.camelize`, `'fluffy'.pluralize` and many-many more. This sause really make the Coffee feel just like Ruby.
+We've added some spice to the Rails+Coffee combo. Applause, the [Sugar.js](http://sugarjs.com/). This incredible library extends the JS the way you are used to with an ActiveSupport. All the comfortable features are here: `[].first`, `'foo'.camelize`, `'fluffy'.pluralize` and many-many more. This sause really make the Coffee feel just like Ruby.
 
-And last but no the least: viva la HAML! Joosy uses templaters abstraction so in theory you can use anything you are used to. But if you ever tried HAML and fell in love like we did, Joosy is shipped with amazing HAML-Coffee template engine.
+And last but no the least: viva la [HAML](http://haml.info/)! Joosy uses templaters abstraction so in theory you can use anything you are used to. But if you ever tried HAML and fell in love like we did, Joosy is shipped with amazing HAML-Coffee template engine.
 
 ### Not am MVC? But...
 
-The idea is simple. REST in not an SQL. Application Server is not an RDBMS. You can't have real logic inside your models. Therefore you don't have models. Inside your browser you don't need to be linked to REST structure since your only goal is an interaction with user. That's why you don't need controller. Joosy operates with View terms. It has pages, layouts, widgets, forms. Everything you are used to but with a Rails flavor.
+The idea is simple. REST in not an SQL. Application Server is not an RDBMS. You can't have real logic inside your models. Therefore you don't have models. Inside your browser you don't need to be linked to REST structure since your only goal is an interaction with user. That's why you don't need controllers. Joosy operates with View terms. It has pages, layouts and widgets. Each of them works with templates, resources (doh... models) and forms. That's pretty much it, the typical separation for the View part.
 
-With Rails you pass your data to your templates through controller and then get it back from forms or AJAX-queries. That's exactly how Joosy works. It has a layer of slim `Resources` (just like `@foo` that was sent to your view). Yes, they are pulled from REST controllers and not otherwise but does it change anything? As soon as you got your data from your controller you operate with a `Layout` and `Pages`. Each of them is a entity that hold interaction with users. It's connected to a template, JS events and all that stuff you expect from your browser application. To avoid redundancy you can group typical code into something that is called `Widget`. Joosy controls your DOM so it only reloads layout when the new page requires another one.
+![Scheme](http://cl.ly/301c0G0K300C011U3701/Joosy%20Basics.png)
 
-To send data back Joosy has a `Form`. It wraps your basic HTML form and turns it into AJAXified thing. It works without page reload and interacts with your code using events. It even has an event for the "upload progress". `Forms` are magically linked to `Resources` so you don't write your code twice. Wait, even more! You have the `formFor` helper. Just like in Rails.
+Inside Rails you pass your data to your templates through controller and then get it back from forms or AJAX-queries. That's exactly how Joosy works. 
+The central entity is a `Page`. Each time URL changes new page gets loaded. Joosy loads the layout for the first page or if the requested page requires another layout. After the container is prepared, you request your Resources and render the templates using it. Remeber, your templates are HAML with inline Coffee support. They even have mature helpers support.
+
+{% assign gist_file = 'Page Sample.coffee' %}
+{% include gist.html %}
 
-As mentioned before Joosy uses HAML-Coffee template engine. Joosy supports helpers we love so much. Again, just like Rails.
+{% assign gist_file = 'Template Sample.haml' %}
+{% include gist.html %}
 
-Offcourse we have other stuff like `Router` and `Preloader`. Everything out of box.
+To send data back Joosy has a `Form`. It wraps your basic HTML form and turns it into AJAXified thing. It works without page reload and interacts with your code using events. It even has an event for the "upload progress". `Forms` are magically linked to `Resources` so you don't write your code twice. Wait, even more! You have the `formFor` helper. Just like in Rails.
 
-### Okay, it's Rails. Anything else?
+### Okay, it's like Rails. Anything else?
 
 Unlike Rails server application it has a state. For example if you use the only `Layout` for every page it will never get reloaded. Unlike the data it holds. To ease the DOM updates Joosy has `dynamic rendering` feature. It allows you to bind your resource to a template to automatically update DOM whenever resource changes. No manual events handling and rerendering. You just call `@renderDynamic` for a partial and it always stays actual.
 
+{% assign gist_file = 'Partial Sample.haml' %}
+{% include gist.html %}
+
 Besides that Joosy offers built-in Identity Map implementation. You don't have to care about `Resources` instances. Even if you reload your `Resource` from a new Page your dynamic rendering will work from your Layout. Or any other place.
 
+And to ensure you won't have problems with really large applications, Joosy comes with a set of preloaders implementing set of strategies.
+
 ### Total highlights
 
 Just to make sure you get it right here's the full list of functionality highlights we have to offer:

guides/basics/joosy-vs-x.md

@@ -5,12 +5,16 @@ title: "Joosy vs X"
 
 ## How is Joosy different from X
 
-We share quite different goals and totally differ in ways to achieve it. While existing MVC frameworks define basic entities for you and leave you alone with application basic patterns and solutions, Joosy tries to give convention for each of them.
+Joosy was created to be a foundation of a large browser applications. Since large applications are always tightly bound to a server implementation Joosy is not trying to achieve abstraction and independency. It uses Rails as an Application Server and lives among Views terms.
+
+Talking about an MVC paradigm, Joosy is a View part while Controllers and Models are still in Rails. The great description of Joosy paradigm can be met at [Getting Started](/guides/basics/getting-started.html) guide. Please read it before passing on to direct comparison parts so you are sure to understand it correctly.
+
+The another thing we inherit from Rails is a passion to have a nice set of ready conventions to solve common problems you meet day to day. Real-life orientation is a great Joosy feature. Most of conventions are shamelessly copied from Rails to ease adaptation and cooperation.
 
 #### [Backbone](http://documentcloud.github.com/backbone/)
 
-In Backbone or Spine you only have abstract Views, Models and "Packs of …" and you should even decide on your own what's Controller for you. Joosy gives you the ready plan on how to move on to the success. If you ever used Rails you know that feeling: you concentrate on _what_ you create and not on _how_ to structure it.
+TODO: Write this part.
 
 #### [Ember](http://emberjs.com/)
 
-Ember is the closest framework by spirit. But it still doesn't give you enough conventions and is even more abstract than Backbone in several parts. It either limits you to Handlebars. Joosy rendering system is built on top of same solution, Morpher. That said you can bind your variables dynamically just like in Ember. But it allows you to any templates syntax.
+TODO: Write this part.

guides/blog/rails-preparations.md

@@ -3,83 +3,6 @@ layout: guide
 title: "Joosy Basics"
 ---
 
-## Assumptions
-
-The guide is designed for people who want to empower their apps with a web UI that rocks. It relies on you having basic understanding of Rails, REST, ActiveRecord, and common Rails patterns.
-
-Joosy is a JS framework and doesn't strictly depend on Rails nor Ruby. However to boost your development speed at unreachable level and skip all that boring setups Joosy comes as a Gem (with nifty generators and all). Because of Asset Pipeline, it's required to have at least Rails 3.1 installed.
-
-## What is Joosy
-
-Joosy is a full-featured javascript MVC framework, which mostly follows Rails philosophy, particularly in preferring conventions over configuration. It helps you to avoid boilerplate and makes it easy to maintain and extend the app.
-
-Joosy allows you to create web apps which work completely in the browser. So that, it helps you to relocate all your Rails Views to the client side. It also helps you with managing the growing quantity of JS code. On another hand, it makes your backend to have exactly one function --  to be a simple REST provider. That leads to easier development support and improves the scalability greatly.
-
-Joosy doesn't compete with jQuery. It is built on the top of [jQuery](http://jquery.com/), and utilizes [CoffeeScript](http://coffeescript.org/). It either includes [Sugar.js](http://sugarjs.com/) in role of ActiveSupport to make your life even better.
-
-Finally, Joosy boosts your development drastically.
-
-### How is Joosy different from X
-
-We share quite different goals and totally differ in ways to achieve them. While existing MVC frameworks define basic entities for you and leave you alone with application basic patterns and solutions, Joosy tries to give convention for each of them.
-
-#### [Backbone](http://documentcloud.github.com/backbone/)
-
-In Backbone or Spine you only have abstract Views, Models and "Packs of …" and you should even decide on your own what's Controller for you. Joosy gives you the ready plan on how to move on to the success. If you ever used Rails you know that feeling: you concentrate on _what_ you create and not on _how_ to structure it.
-
-#### [Ember](http://emberjs.com/)
-
-Ember is the closest framework by spirit. But it still doesn't give you enough conventions and is even more abstract than Backbone in several parts. It either limits you to Handlebars. Joosy rendering system is built on top of same solution, Morpher. That said you can bind your variables dynamically just like in Ember. But it allows you to use any templates syntax.
-
-### The Joosy MVC Interpretation
-
-You probably are familiar with the concept of MVC. It's a pattern to keep code DRY, isolate business logic from the UI. However the concept of Model-View-Controller just doesn't work for browser applications. There are numerous reasons for that that can't be fit into this introduction. Instead we'll tell you what we propose.
-
-#### Views
-
-In Joosy views are just views. Set of files (in `templates/` folder). They do not differ from Rails and give you quite the same abilities (including helpers!). Besides that Joosy has `renderDynamic` which allows you to bind your variables to HTML representation tightly. You change variable value, Joosy changes HTML.
-
-By default Joosy comes with Coffee-Haml (which looks and works pretty much like usual Haml). Combined with Sugar.js it will feel very similar to Ruby and server-side and will provide you the easiest migration.
-
-#### Controllers
-
-Unlike server-side, client-side has a state. At server-side you only have incoming data and you convert it to output data. At client-side you work with events. To handle correct bootstrap and help you organize your code well, we have 3 entities which play the role of controller. Their organizing functions are similar but they behavior dramatically different at bootstrap.
-
-They are:
-
-###### Pages
-Pages are the heart of the entire application. They are used to fetch data, bind events, setup widgets, trig visual effects, and pass the data to the templates.
-
-###### Layouts 
-Layouts are mainly used to set a part of your page that won't be reloaded often. Pages are wrapped into Layouts. Just like pages Layouts can bind events and setup widgets. Consider layouts as a bit extended version of what you have in Rails.
-
-###### Widgets 
-Widgets are needed to keep your code DRY. They help you organize it in reusable modules.
-
-#### Models
-
-There are some facts that should be noted to explain it how we understand browser-side models.
-
-* In most cases you will want to leave your logic on server-side. In real models. 
-* You rarely want to make 5 HTTP requests instead of 1.
-* In most cases you will have to give user a Form as a way to change anything.
-* You'll get different possible set of fields depending on case you use your model at.
-
-With all that in mind we came up to the fact: you can not reproduce real models in browser nor you should try to. What you need is a comfortable channel between browser and server-side to get structured data, work with that and send it back. That's mainly a transport and interface task while models are MUCH more than that. To solve this task Joosy offers you two things:
-
-###### Resources
-Resource is wrapper on top of JSON dump which will help you to get data from server, parse it and structure it. It will trigger 'changed' if you change resource, will map inline hashes in other resources if possible and do all other magic stuff you expect from your model when you read data. Resources either define Collections. In most cases you can say Resources are fully-functional read part of what you get used to as model.
-
-###### Forms
-After you got your data as resources and used it to display something, you'll need to change it. While resource defines modification methods like _save_ and _destroy_ most of complex modifications should go through Joosy.Form. It turns your form into AJAX and binds the resource to it. It handles file uploads, it gives you upload progress callback and makes it a dream to handle. Joosy.Form will either understand standard Rails invalidation response and will mark invalidated fields with ".field_with_errors" out of box.
-
-
-## What is Joosy good for
-
-Joosy is intended to ease building of modern medium and large-sized browser-based applications, minimize code base while providing more features and what's most important, giving you ready conventions for typical tasks.
-
-Compare Joosy to Backbone like Rails to Sinatra. While Rails engine is much more powerful, Sinatra still has a lot of cases to be used at. If all you need is to enable some RICHness on one of your pages, Joosy can handle that. But Backbone will do the trick with lesser dependencies. If you need to move complete web-resource to browser Joosy will do the task at its Best.
-
 ## Creating basic Rails blog app
 
 Assuming you already have Ruby & Rails installed, let's proceed to creating a new rails project.
@@ -105,7 +28,7 @@ Don't forget to run migrations after that
 Let's fill our database with sample data. Put the following into
 `db/seeds.rb`
 
-{% highlight ruby lineno %}
+{% highlight ruby %}
 posts = Post.create([{ title: 'Welcome there', body: 'Hey, welcome to the joosy blog example' }, { title: 'Test post', body: 'Nothing there. Really' }])
 Comment.create(body: 'Great article!', post: posts.first)
 {% endhighlight %}

index.md

@@ -37,7 +37,7 @@ Finally, Joosy boosts your development drastically. Just like the Rails do.
 
   This chapter describes HTML elements and events binding. We'll add simple events to show number of comments next to blog's title. We'll also discuss Filters, the powerful system of interaction with layouts/pages bootstrap.
 
-* ### [Resources](guides/blog/resources.md)
+* ### [Resources](guides/blog/resources.html)
 
   With help of Resources we'll improve our pages' fetch process, will add ability to delete posts. We'll either learn how to do inline resources mapping (like when you have `has_many` in Rails).