Permalink
Browse files

Merge pull request #14 from explainer/gh-pages

First pass of blog .md files
  • Loading branch information...
2 parents c9a26ee + 90a96cc commit 8e30f419ceb7009bed46b0521c101920eb1079e7 @AlexanderPavlenko AlexanderPavlenko committed Dec 14, 2012
@@ -7,7 +7,7 @@ title: "Elements, events and filters"
<div class="info">
<p>
- During this chapter we will add the most stupid and useless feature of our blog. The clocks that will appear when mouse hits the header pane. While you probably will never do something like this in a real life this is a very full example for our case.
+ In this chapter we will add the most stupid and useless feature of our blog, a digital clock. This clock that will appear when the mouse hits the header pane. While you probably will never do something like this in a real life, this is a very full example for our case.
</p>
</div>
@@ -18,14 +18,14 @@ For the start let's add a tiny mock to our layout HAML to inspect the future loo
## Elements, Events
-Inside your page, layout or widget you can define two lists. The list of DOM elements to wrap into jQuery and put into instance variables. And list of events to bind to. The first thing we are about to do is to make our mock hide/appear when the mouse reaches `.navbar`. And since it's a part of a layout, we are going to work within it. Don't forget to explicitly set `style="display:none"` right after you check your mock is in place to make your clocks hidden by default.
+Inside your page, layout or widget you can define two lists. The list of DOM elements to wrap into jQuery and put into instance variables, and the list of events to bind to. The first thing we are about to do is to make our mock hide/appear when the mouse reaches `.navbar`. And since it's a part of a layout, we are going to work within it. Don't forget to explicitly set `style="display:none"` (TODO: which .css.scss file?) right after you check your mock is in place to make your clocks hidden by default.
{% assign gist_file = 'Events.coffee' %}
{% include gist.html %}
-At its keys the `elements` hash contains the names of instance variables to assign. And the values are actual jQuery DOM selectors. As you can see in this example it not only defines instance variables but either allows you to avoid duplications while defining events.
+At its keys the `elements` hash contains the names of instance variables to assign, the values being the actual jQuery DOM selectors. As you can see in this example, it not only defines the instance variables but also allows you to avoid duplication while defining events.
-At events hash you write `event_name selector` as a key and pass in lambdas to call at this event. At the selector position you are allowed to use `$element` notation or simply put the full selector as-is: `click .foo .bar`. The lambdas you define accept two arguments: the first is the actual element event was triggered on. And the second is the full jQuery event object. In our cases we don't need any of them so they are omited.
+In the events hash you write `event_name selector` as a key and pass in lambdas (TODO: Example?) to call at this event. At the selector position you are allowed to use `$element` notation or simply put the full selector as-is: `click .foo .bar`. The lambdas you define accept two arguments: the first is the actual element the event was triggered on, wguke the second is the full jQuery event object. In our case we don't need any of them, so they are omited.
Here is the alternative notation that can help your keep your code readable for the complex cases:
@@ -34,18 +34,18 @@ Here is the alternative notation that can help your keep your code readable for
## Filters
-Now is the time to make our clocks alive. Joosy defines set of `before` and `after` hooks that are similar to Rails controller filters. To make clocks work we need to put actual time on when the pages load and register javascript `interval` to update it every second. Put this code into your `ApplicationLayout`:
+Now is the time to make our clocks alive. Joosy defines set of `before` and `after` hooks that are similar to Rails controller filters. To make clocks work we need to put actual time on when the pages load and register a javascript `interval` to update it every second. Put this code into your `ApplicationLayout`:(TODO: specify file name)
{% assign gist_file = 'Filters.coffee' %}
{% include gist.html %}
-The important thing to note is a `@setInterval` call. Joosy gives you two wrappers for common `setInteval` and `setTimeout` functions. There are two important differences between them and native calls. The first is the arguments order. In Joosy the first argument is the actual timeout/interval delay. Arguments were moved to ease callbacks description for Coffee. And the second difference is the garbage collection. Your interval/timeout will be automatically cleared whenever the container (layout/page/widget) is not active anymore. So you just define the interval and Joosy cares out all the rest.
+The important thing to note is a `@setInterval` call. Joosy gives you two wrappers for common `setInteval` and `setTimeout` functions. There are two important differences between them and native calls. The first is the arguments order. In Joosy the first argument is the actual timeout/interval delay. Arguments were moved to ease callbacks description for Coffee. And the second difference is the garbage collection. Your interval/timeout will be automatically cleared whenever the container (layout/page/widget) is not active anymore. So you just define the interval and Joosy carries out all the rest.
-Together with `afterLoad` Joosy gives you the `beforeLoad` hook. Within beforeLoad you don't have your elements/events assigned nor you have data fetch. But you can controll the page loading flow. As soon as your `beforeLoad` returned false the page load will be aborted. So you can, for example, redirect user to another page.
+Together with `afterLoad` Joosy gives you the `beforeLoad` hook. Within beforeLoad you don't have your elements/events assigned nor you have your data fetched. But you can control the page loading flow. As soon as your `beforeLoad` returned false the page load will be aborted. So you can, for example, redirect user to another page.
{% assign gist_file = 'Flow control.coffee' %}
{% include gist.html %}
-Both `afterLoad` and `beforeLoad` can be chained. They will be called in exact order you define those among your container. Moreover, if you use classes inheritance, Joosy will call parents hooks. The order is still under controll. Joosy will start from the upper parent and step down towards children.
+Both `afterLoad` and `beforeLoad` can be chained. They will be called in the exact order you define those in your container. Moreover, if you use classe inheritance, Joosy will call parents hooks. The order is still under your control. Joosy will start from the upper parent and step down toward the children.
The <a href="/guides/blog/forms.html">next chapter</a> is all about forms. We will finally come up with the way to create and edit blog posts.
View
@@ -21,39 +21,39 @@ As before let's add some routes to ginger our new pages up:
{% assign gist_file = 'Routes.coffee' %}
{% include gist.html %}
-Ensure your `posts/new` route goes _before_ the `posts/:id` one. Routing does always seek for the first match and id matcher will either consume `posts/new` if defined first.
+Ensure your `posts/new` route goes _before_ the `posts/:id` one. Routing always use the first match and id matcher will also consume `posts/new` if defined first.
-Both pages will actually use the same form. So it's a good candidate to be a partial. Put the following haml to something like `templates/pages/posts/_form.jst.hamlc`:
+Both pages will actually use the same form, so it's a good candidate to be a partial. Put the following haml in `templates/pages/posts/_form.jst.hamlc`:
{% assign gist_file = 'Form.haml' %}
{% include gist.html %}
-Joosy has built-in Rails `form_for` analog and we'll get back to this in later chapters. But for now having just two fields hand-writen in HAML is not that bad, so we pass on.
+Joosy has a built-in Rails `form_for` analog and we'll get back to this in later chapters. But for now having just two fields hand-writen in HAML is not that bad, so we will leave it for now.
-Including this partial to both pages is pretty easy task. Here's how both of our pages templates are going to look:
+Including this partial to both pages is a pretty easy task. Here's how both of our pages templates are going to look:
{% assign gist_file = 'Include.haml' %}
{% include gist.html %}
## Basic binding
-We'll work on both pages in parallel since code is going to be pretty similar. In real life you will probably want to refactor it along. But let's keep some duplication to maintain simplicity. We are just learning after all.
+We'll work on both pages in parallel since code is going to be quite similar. In real life you will probably want to refactor it, but let's keep some duplication to maintain simplicity. We are just learning, after all.
-`Joosy.Form` works in conjuction with Resource. So what we need to go forward is to get resources for the both pages. And we'll need to address the form so let's bind actual element.
+`Joosy.Form` works in conjuction with Resource. So what we need to go forward is to get resources for the both pages. And we'll need to address the form so let's bind the actual element (TODO: rewrite this sentence).
{% assign gist_file = 'Fetch.coffee' %}
{% include gist.html %}
-With this code we'll make `@data.post` to contain the resource for the form at both pages. The next code is absolutely identical for either creation and modification so just clone it.
+With this code we'll make a `@data.post` to contain the resource for the form for both pages. The next code is absolutely identical for either creation or modification, so just clone it.
{% assign gist_file = 'Bind.coffee' %}
{% include gist.html %}
-Go and check. Your forms are ready. Everything else will be covered by inner magic. Even the validation. But to make it work we'll have to add proper CSS classes and, khm, actually validate something on the server.
+Go and check. Your forms are ready. Everything else will be covered by inner magic. Even the validation. But to make it work we'll have to add proper CSS classes and, khm, actually validate something on the server. (TODO: Rewrite this paragraph.)
## Invalidation
-In our case we don't really need to modify styles since we use the same CSS rule name with Rails. And therefore proper CSS is already specified at `scaffold.css`. But if you want to give it a better look search for `.field_with_errors`.
+In our case we don't really need to modify styles since we use the same CSS rule name with Rails. And therefore proper CSS is already specified at `scaffold.css.scss`. But if you want to give it a better look search for `.field_with_errors`.(TODO: Either include an example, or drop this paragraph entirely.)
At the server part we'll have to modify our `Post` model:
@@ -64,7 +64,7 @@ And you can go check your forms again. Invalidated fields will get it's class an
<div class="warning">
<p>
- Forms are one of the most important parts of Joosy. You really should finish reading this chapter sooner or later. We won't need more info about forms for the whole blog guide though. But you realy should come back later even if decide to pass on to a <a href="/guides/blog/dynamic-rendering.html">Dynamic rendering</a> chapter.
+ Forms are one of the most important parts of Joosy. You really should finish reading this chapter sooner or later. We won't need more info about forms for the whole blog guide though. But you really should come back later even if decide to pass on to a <a href="/guides/blog/dynamic-rendering.html">Dynamic rendering</a> chapter.
</p>
</div>
@@ -80,16 +80,16 @@ The main goal of `Joosy.Form` is to turn your forms into AJAX to avoid page relo
* If `error` callback was not defined but we got error, try to highlight invalidations
* During form upload call `progress` callback periodically and pass in the upload progress
-So the default basic look of `attach` call is:
+So the default basic look of `attach` call is: (TODO: Please clarify this paragraph)
{% assign gist_file = 'Basic attach.coffee' %}
{% include gist.html %}
-This call will not modify (or set) the method (POST, PUT etc) of form. And will only affect its action if it was explicitly passed as an `action` parameter. So if you have no resource for the form you still can "activate" it and unleash the power of success/error/progress callbacks.
+This call (TODO: what 'call'?) will not modify (or set) the method (POST, PUT etc) of the form, it will only affect its action if it was explicitly passed as an `action` parameter. So if you have no resource for the form you still can "activate" it and unleash the power of success/error/progress callbacks.(TODO: Why?)
-While success and progress events are very straightforward, the `error` hook plays an important role of validation. If this was not specified Joosy will fallback to default invalidation proccess (which is described below). And more, even if it was specified and did return `true` explicitly, Joosy will still run it's invalidation proccess. This is supposed to ease your form validation handling dramatically.
+While success and progress events are very straightforward, the `error` hook plays an important role of validation. If this was not specified Joosy will fallback to default validation proccess (which is described below). And more, even if it was specified and did return `true` explicitly, Joosy will still run it's validation proccess. This is supposed to ease your form validation handling dramatically.
-For the basic form (no resource) invalidation convention is something really easy. `{field: 'error message'}` – this response will make Joosy seek for `input name=field` and mark it as invalid. It matches Rails conventions perfectly.
+For the basic form (no resource) validation convention is something really easy. `{field: 'error message'}` – this response will make Joosy seek for `input name=field` and mark it as invalid. It matches Rails conventions perfectly.
## Resources
@@ -5,9 +5,9 @@ title: "Layouts, pages and routing"
{% assign gist_id = 2785784 %}
-In Rails each page is the action template. It gets wrapped into the layout and includes number of partials. As the result you get your HTML generated.
+In Rails each page is the action template. It gets wrapped into the layout and includes a number of partials. As a result you get your HTML generated.
-Joosy behaves the same way but unlike elder brother it has to deal with events and user interaction logic so it's not just a renderer. Joosy separates the templates layer and a logic level. Logic level consists of the `Page`, the `Layout` which wraps the page and set of `Widget`s that can be included in both, `Page` and `Layout`. Each element of the logic level uses templates to describe rendering.
+Joosy behaves the same way but unlike its elder brother it has to deal with events and user interaction logic so it's not just a renderer. Joosy separates the templates layer from a logic level. Logic level consists of the `Page`, the `Layout` which wraps the page and set of `Widget`s that can be included in both, `Page` and `Layout`. Each element of the logic level uses templates to describe rendering.
![](http://f.cl.ly/items/1S130q3C0n1s2R1I1T0S/pages.png)
@@ -26,7 +26,7 @@ With your first app you got your first page and layout generated. They are situa
layouts/application.js.coffee</pre>
</div>
-We'll start from the Layout. The only option it sets makes Joosy seek for a template for this layout at `templates/layouts/application.jst.hamlc`. Since we don't really need any logic at our Layout for now let's just modify the HAML. Using twitter bootstrap we can come up with something like this:
+We'll start from the Layout. The only option it sets makes Joosy look for a template for this layout at `templates/layouts/application.jst.hamlc`. Since we don't really need any logic at our Layout for now let's just modify the HAML. Using twitter bootstrap we can come up with something like this:
{% assign gist_file = 'Layout.haml' %}
{% include gist.html %}
@@ -41,7 +41,7 @@ Take a look at the last tricky line. Using `{:id => @yield()}` we mark the `.con
## Pages
-Let's move on to the pages. To structure application better we will not use the default pregenerated page (we'll remove it later) but create a set of new ones! We'll need three pages: the list of posts, single post view and two forms – to create the post and edit it. We'll get to modification while working with forms and now let's generate list and view pages:
+Let's move on to the pages. To structure application better we will not use the default pregenerated page (we'll remove it later) but create a set of new ones! We'll need three pages: the list of posts, single post view and two forms – to create the post and edit it. We'll get to modification while working with forms, so now let's generate the list and view pages:
{% assign gist_file = 'Generate.sh' %}
{% include gist.html %}
@@ -67,7 +67,7 @@ Open your browser and go to:
## Fetching
-The only thing left to do is to get the real data from server and put it into the template. Joosy defines `fetch` hook that should be used to load required data. Page, Layout and Widget will expect `@data` to contain hash of template's local variable. So this is how it's supposed to look:
+The only thing left to do is to get the real data from the server and put it into the template. Joosy defines `fetch` hook that should be used to load the required data. Page, Layout and Widget will expect `@data` to contain a hash of the template's local variables. So this is how it's supposed to look:
{% assign gist_file = 'Fetch.coffee' %}
{% include gist.html %}
@@ -77,12 +77,12 @@ Now insert the proper variables into your templates:
{% assign gist_file = 'Pages.haml' %}
{% include gist.html %}
-That's it, your pages now contain real data from server.
+That's it, your pages now contain real data from the server.
<div class="info">
<p>
- We did not replaced the blog post date field. Moreover we don't even have such a field inside our model. That's a good chance to practice a bit: try to add this field to your model and templates to consolidate your knowledges.
+ We did not replace the blog post date field. Moreover we don't even have such a field inside our model. This is a good opportunity to practice a bit: try to add this field to your model and templates to consolidate your knowledge.
</p>
</div>
-At this stage we got our Rails backend, Resources and two pages with actual data from server. And further we go with [elements, events and filters](/guides/blog/elements-events-and-filters.html).
+At this stage we got our Rails backend, Resources and two pages with actual data from server. Now, we go further with [elements, events and filters](/guides/blog/elements-events-and-filters.html).
Oops, something went wrong.

0 comments on commit 8e30f41

Please sign in to comment.