fortitude 0.9.1 → 0.9.2

data/doc/source/why/a_simple_helper.html.rb

@@ -0,0 +1,332 @@
+require 'source/why/example_page'
+
+module Views
+  module Why
+    class ASimpleHelper < Views::Why::ExamplePage
+      def example_intro
+        p %{Fortitude expresses your view code as Ruby itself, using a simple DSL patterned
+after HTML. One big benefit of this approach is its consistency: views, helpers,
+and partials are all written in the exact same language, Ruby.}
+
+        p %{Ruby is a great deal nicer to
+work with than either an HTML templating language or the string interpolation of traditional
+helper methods. We’ll see the difference this can make in the following example.}
+      end
+
+      def example_description
+        p %{The following ERb code was extracted from a real-world application, and is a great, simple
+example of where Fortitude can help the most.}
+
+        erb <<-EOS
+...
+<a href='<%= conditional_refresh_url(:user => @user) %>'
+   class="button icon refresh" onclick="javascript:handleRefreshClick();">
+  <div class="button_text">
+    <p>Refresh this page if:</p>
+    <ul>
+      <li>Content has changed</li>
+      <li>Local data is <%= @out_of_date_condition %></li>
+    </ul>
+  </div>
+</a>
+...
+EOS
+
+        p %{Combined with appropriate CSS, this code creates an “icon button” — a small icon, with a tooltip available:}
+
+        featured_image 'why/icon_button.png'
+
+        p {
+          text %{Unsurprisingly, this button gets used in }; em "many"; text %{ places throughout the application. }
+          text %{Using ERb, let’s see what we can do to factor out this common pattern.}
+        }
+      end
+
+      def using_standard_engines
+        refactoring_choices
+        using_a_helper
+        using_a_partial
+      end
+
+      def refactoring_choices
+        p %{Using traditional templating engines, we have two choices:}
+
+        ul {
+          li {
+            text "We can create a "; em "helper"; text ", which is written using Ruby string interpolation and called "
+            text "like a traditional Ruby method;"
+          }
+          li {
+            text "Or we can create a "; em "partial"; text ", which is written using our templating language of choice "
+            text "and called using "; code "render :partial => ..."; text "."
+          }
+        }
+
+        p %{In either case, we’ll need to make sure we allow for several variations in our desired output:}
+
+        ul {
+          li {
+            text "The URL (the "; code "href"; text " parameter) is, of course, different in almost every case."
+          }
+          li {
+            text %{Sometimes we need to add additional attributes }; em "(e.g."; text ", "; code "onclick"; text ", "
+            code "data-*"; text ", "; em "etc."; text ") to the "; code "a"; text " element, and sometimes not."
+          }
+          li {
+            text %{What’s inside the tooltip varies: it can be plain text or HTML, it can have variable substitutions —
+really, it can be anything at all.}
+          }
+        }
+
+        p %{Given these constraints, let’s see how each of these looks.}
+      end
+
+      def using_a_helper
+        h5 "Using a Helper"
+
+        p %{Here’s what our new helper method looks like:}
+
+        ruby "application_helper.rb", <<-EOS
+def icon_button(icon_name, target, tooltip_html, additional_attributes_string = "")
+  "<a href=\"\#{target}\" class="button icon \#{icon_name}" \#{additional_attributes_string}><div class="button_text">\#{tooltip_html}</div></a>"
+end
+EOS
+
+        p %{And here’s how we’d call it for the example above:}
+
+        erb <<-EOS
+...
+<%= icon_button(:refresh, conditional_refresh_url(:user => @user), "<p>Refresh this page if:</p><ul><li>Content has changed</li><li>Local data is \#{h(@out_of_date_condition)}</li></ul>", "onclick=\"javascript:handleRefreshClick();\"")
+EOS
+
+        p "What’s good and what’s bad about this?"
+
+        ul {
+          li {
+            strong "Concise"; text ": Both the caller and helper are quite short; but:"
+          }
+          li {
+            strong "Inconsistent"; text ": Suddenly, we’re forced to write both the helper method "; em "and"
+            text " the HTML for the interior of the button using Ruby string interpolation, rather than ERb — "
+            text "which leads to:"
+          }
+          li {
+            strong "Messy"; text ": We have significant stretches of HTML sitting around in Ruby strings, "
+            text "which is quite hard to read;"
+          }
+          li {
+            strong "Bad Formatting"; text ": Because of this, the generated HTML will be quite poorly formatted, "
+            text "with the HTML in those strings all run-together. But, most importantly:"
+          }
+          li {
+            strong { em "Dangerous (XSS Potential)" }; text ": We’re now responsible for worrying about HTML escaping "
+            text "in a way we weren’t before: "; em "every single caller"; text " needs to make sure that any user "
+            text "data in the "; code "additional_attributes_string"; text " is escaped "; em "before"; text " being "
+            text "passed. Similarly, we need to remember to call "; code "h()"; text " on the variable being "
+            text "interpolated into the "; code "tooltip_html"; text " string before passing it, or else we’ll be "
+            text "vulnerable to XSS attacks again."
+          }
+        }
+
+        p {
+          text "Yikes. We’ve factored out this helper method, which cleans up our calling code, but at a rather significant "
+          text "expense. Perhaps we can do better by creating an actual partial, instead?"
+        }
+      end
+
+      def using_a_partial
+        h5 "Using a Partial"
+
+        p %{Here’s what our new partial looks like:}
+
+        erb <<-EOS
+<a href="<%= target %>" class="button icon <%= icon_name %>"
+   <%= (defined?(additional_attributes) ? additional_attributes || '') %>">
+  <div class="button_text">
+    <%= tooltip_html %>
+  </div>
+</a>
+EOS
+
+        p %{And here’s how we’d call it for the example above:}
+
+        erb <<-EOS
+<%= render :partial => '/shared/buttons/icon_button', :locals => {
+  :target => conditional_refresh_url(:user => @user),
+  :icon_name => 'refresh',
+  :additional_attributes => 'onclick="javascript:handleRefreshClick();"'.html_safe,
+  :tooltip_html => %{<p>Refresh this page if:</p>
+    <ul>
+      <li>Content has changed</li>
+      <li>Local data is \#{h(@out_of_date_condition)}</li>
+    </ul>}.html_safe
+} %>
+EOS
+
+        p "Again, what’s good and what’s bad about this?"
+
+        ul {
+          li {
+            strong "Consistency/Inconsistency"; text ": on one hand, at least now the partial itself is expressed using "
+            code "ERb"; text ", not a Ruby string. On the other hand, we still have to use a Ruby string for the HTML we’re "
+            text "passing in to it."
+          }
+          li {
+            strong "Verbose and Messy"; text ": we’ve actually managed to create a caller that is 33% "
+            em "longer"; text " than the original code it replaced, and is actually quite a lot harder to read at "
+            text "first glance. (The helper method was a lot better here.)"
+          }
+          li {
+            strong "Formatting"; text ": the resulting HTML will at least look a lot better than in our earlier example;"
+          }
+          li {
+            strong "Method Signature"; text ": when reading the new "; code "_icon_button.html.erb"; text "partial, "
+            text "how can you easily tell which variables you need to pass in, and which of those are optional? "
+            em "You can’t"; text " — except by reading through the entire text of the partial and thinking about "
+            text "each use carefully, which is really painful. (In this, the helper method was certainly "
+            text "a lot cleaner, too.)"
+          }
+          li {
+            strong { em "Dangerous (XSS Potential)" }; text ": Once again, we’re now responsible for worrying about "
+            text "HTML escaping in a way we weren’t before: "; em "every single caller"; text " needs to make sure that "
+            text "any user data in the "; code "tooltip_html"; text " string is correctly escaped using "; code "h()"
+            text " before being passed in. (We also need to make sure we call "; code "#html_safe"; text " on the "
+            text "value we pass to "; code "additional_attributes"; text ", too; this is less dangerous, but also very "
+            text "easy to forget, and will cause corrupt HTML if we forget about it.)"
+          }
+        }
+      end
+
+      def standard_engine_issues
+        p {
+          text "Both cases above are far from perfect. Helper methods are more succinct to call, yet also a lot "
+          text "messier to both write and call when passing around HTML, and have serious XSS risks. Partials mitigate "
+          text "some of those problems, but introduce others, and are "; em "really"; text " verbose and messy to call."
+        }
+
+        p {
+          text "Ironically, some of the issues above may feel a little unfamiliar, and it’s probably because of this: "
+          em "nobody does this"; text " — because both these approaches have such serious tradeoffs, most teams, "
+          text "developers, or designers just leave well enough alone for small(ish) examples like this, and "
+          text "repeat the original HTML everywhere, over "
+          text "and over. And when it comes time to change the "
+          text "HTML structure of this “icon button” element that’s been repeated all over the site, we either just "
+          text "bite the bullet and do a really painful global search and repeated manual modificaftion, or give up, "
+          text "hack on CSS to make it do sort of what we want it to do, and then leave "; em "that"
+          text " mess in place."
+        }
+
+        p {
+          text "We imagine that this is "; em "just the way views are"; text ". "
+          text "In fact, these problems are all because we generally don’t have the right tools to do a better job. "
+          text "Views don’t need to be like this, any more than "; em "any"; text " code needs to be like this."
+        }
+      end
+
+      def using_fortitude
+        p %{To see what Fortitude brings to this example, let’s start by looking at Fortitude code for the original
+example, before we try to refactor it:}
+
+        fortitude <<-EOS
+...
+a(:href => conditional_refresh_url(:user => @user),
+  :class => 'button icon refresh') {
+  div(:class => 'button_text') {
+    p "Refresh this page if:"
+    ul {
+      li "Content has changed"
+      li "Local data is \#{@out_of_date_condition}"
+    }
+  }
+}
+...
+EOS
+
+        p {
+          text %{We won’t delve more deeply into Fortitude’s syntax immediately, but it should be clear that
+Fortitude expresses HTML using a very simple Ruby DSL that’s easy to grasp.}
+        }
+
+        p {
+text %{Using this syntax, we can now factor out this shared code as a “helper method” that
+we can easily make available on any view that needs it.}
+        }
+
+        p {
+          text "(We put “helper method” in quotes because "
+          text "this isn’t a traditional helper that we’d put into something like "
+          code "app/helpers/application_helper.rb"; text " and write using Ruby string interpolation. Rather, it’s a "
+          text "method we define in a module, and mix into any view class that needs it — Fortitude views are actually "
+          text "just normal Ruby classes — or into our base view class to make it magically available everywhere.)"
+        }
+
+        p {
+          text "Using this strategy, we can create the following “helper method”:"
+        }
+
+        fortitude <<-EOS
+def icon_button(icon_name, target, additional_attributes = { })
+  a(additional_attributes.merge(
+    :href => target, :class => "button icon \#{icon_name}")) {
+    div(:class => :button_text) {
+      yield
+    }
+  }
+end
+EOS
+
+        p "And the calling code for the example above now looks like this:"
+
+        fortitude <<-EOS
+...
+icon_button('refresh', conditional_refresh_url(:user => @user),
+  :onclick => 'javascript:handleRefreshClick();') {
+  p "Refresh this page if:"
+  ul {
+    li "Content has changed"
+    li "Local data is \#{@out_of_date_condition}"
+  }
+}
+...
+EOS
+      end
+
+      def fortitude_benefits
+        p %{Let’s take a look at how much cleaner this is. A few of the most obvious improvements:}
+
+        ul {
+          li {
+            strong "Concise"; text %{: The calling code is now actually both much }; em "shorter"; text " and "
+            em "more expressive"; text " than the code it replaced."
+          }
+          li {
+            strong "Consistent"; text ": both the new “helper method” and its caller are written in the same "
+            text "language — which is the same language you use for all Fortitude code and the entire rest of your "
+            text "application, Ruby."
+          }
+          li {
+            strong "Well-Formatted"; text ": Because Fortitude is not interpolating strings, but, rather, understands the "
+            text "structure of the HTML, all output is perfectly formatted. (In development, it’s indented correctly, "
+            text "no matter how the code is written; in production, it is automatically produced with minimal spacing, "
+            text "to reduce the size of the HTML transmitted across the network.)"
+          }
+          li {
+            strong "Clean and Clear"; text ": Because it’s a Ruby method, any Ruby programmer will instantly understand "
+            text "what needs to be passed to it; because all of the code is Ruby, it all reads cleanly and clearly."
+          }
+          li {
+            strong { em "Safe" }; text ": at no point does any caller, nor the method itself, need to worry about HTML "
+            text "escaping; all data will be escaped properly without worrying about it."
+          }
+        }
+
+        p {
+          text "However, one of the biggest improvements we’ve made is slightly more subtle: by creating this new "
+          code "icon_button"; text " method, we’ve started slowly building up a "; em "customized view language"
+          text " that is specific to our needs and our application. As we proceed through further examples, we’ll see "
+          text "how powerful this can be in creating clean, concise, maintainable views that are a joy to use."
+        }
+      end
+    end
+  end
+end

data/doc/source/why/building_a_rich_modal_dialog.html.rb

@@ -0,0 +1,156 @@
+require 'source/why/example_page'
+
+module Views
+  module Why
+    class BuildingARichModalDialog < Views::Why::ExamplePage
+      def example_intro
+        p {
+          text "In our last example, we saw how using inheritance lets you easily solve view-factoring problems "
+          text "with Fortitude that remain painful in traditional templating engines. In this example, we’ll see "
+          text "how Fortitude’s widget classes let us create specialized contexts for rendering views that are "
+          text "very powerful. In effect, they become little mini-languages, introducing view primitives exactly "
+          text "when you need them and providing an elegant language for you to describe what your view should "
+          text "look like."
+        }
+      end
+
+      def example_description
+        p {
+          text "Almost everybody knows the concept of a "; em "modal dialog"; text " — a “layer” of HTML that "
+          text "requests some kind of input or confirmation from the user before proceeding, and which obscures "
+          text "the rest of the web page so that the user is forced to provide this input or confirmation before "
+          text "proceeding. They’re often also known as a "; em "lightbox"; text ", "; em "modal window"; text ", or "
+          em "heavy window"; text ", and have become a staple of modern Web design."
+        }
+
+        p {
+          text "Here’s an example of a modal dialog that appears in Google Docs when you choose “Make a Copy”: "
+        }
+
+        featured_image 'why/modal_dialog.png'
+
+        p {
+          text "This simple example has a number of features that modal dialogs tend to share:"
+        }
+
+        ul {
+          li "A clear border, often with a drop shadow, around the entire dialog."
+          li "A large layer that dims or otherwise obscures the rest of the page behind the dialog."
+          li "Some kind of “close” or “dismiss” control, often in the upper-right-hand corner."
+          li "A title of some kind at the top — sometimes styled, sometimes not."
+          li "Primary content, which can be more-or-less arbitraily complex."
+          li "At the bottom, at least one button (“OK”), and often more than one."
+        }
+
+        p {
+          text "These simple dialogs present an interesting challenge for view builders. Even the frame of the dialog "
+          text "will consist of multiple elements (usually "; code "div"; text "s), with some important CSS classes "
+          text "applied. There will be a standard way of creating tht title, and likely a container that the primary "
+          text "content needs to go into. The buttons at the bottom will typically have their own container and styles, "
+          text "and standard ways of rendering them."
+        }
+
+        p {
+          text "Let’s look at an example modal dialog in completely non-refactored (one-off) HTML:"
+        }
+
+        erb 'app/views/docs/copy_document.html.erb', <<-EOS
+<div class="modal-background">
+  <div class="modal-dialog">
+    <div class="window-controls"><span class="dialog-control">X</span></div>
+    <div class="modal-title">
+      <h3>Copy document</h3>
+    </div>
+
+    <div class="modal-contents">
+      <form class="modal-form">
+        <label for="document_name">Enter a new document name:</label>
+        <input type="text" name="document_name">Copy of Untitled document</input>
+        <span class="form-input-footnote">Comments will not be copied to the new document.</span>
+
+        <input type="checkbox" name="copy_sharing"></input>
+        <label for="copy_sharing">Share it with the same people</label>
+      </form>
+    </div>
+
+    <div class="modal-actions">
+      <button name="OK" value="ok" class="modal-button">OK</button>
+      <button name="Cancel" value="cancel" class="modal-button">Cancel</button>
+    </div>
+  </div>
+</div>
+EOS
+      end
+
+      def using_standard_engines
+        p {
+          text "Using traditional templating engines, what’s the best we can do with this? In many ways, it’s similar "
+          text "to our previous example: we can either use partials/helpers for shared structural elements and count "
+          text "on calling them in the right order, or use "; code "capture"; text " to construct blocks of HTML and "
+          text "pass them into a shared view."
+        }
+
+        p {
+          text "One of the big differences here is that the chunks of HTML we pass in themselves need certain "
+          text "predefined structure. For example, the modal title may need to be in a certain format (at least most "
+          text "of the time), and the set of buttons at the bottom may need certain classes, and so on."
+        }
+
+        p {
+          text "Without further ado, let’s see what the end result looks like:"
+        }
+
+
+        erb 'app/views/docs/copy_document.html.erb', <<-EOS
+<% the_modal_title = capture do %>
+  <%= modal_title("Copy document") %>
+<% end %>
+
+<% the_modal_contents = capture do %>
+  <%= modal_form do %>
+    <label for="document_name">Enter a new document name:</label>
+    <input type="text" name="document_name">Copy of Untitled document</input>
+    <span class="form-input-footnote">Comments will not be copied to the new document.</span>
+
+    <input type="checkbox" name="copy_sharing"></input>
+    <label for="copy_sharing">Share it with the same people</label>
+  <% end %>
+<% end %>
+    <div class="modal-title">
+      <h3 class="modal-title">Copy document</h3>
+    </div>
+
+    <div class="modal-contents">
+      <form class="modal-form">
+        <label for="document_name">Enter a new document name:</label>
+        <input type="text" name="document_name">Copy of Untitled document</input>
+        <span class="form-input-footnote">Comments will not be copied to the new document.</span>
+
+        <input type="checkbox" name="copy_sharing"></input>
+        <label for="copy_sharing">Share it with the same people</label>
+      </form>
+    </div>
+
+    <div class="modal-actions">
+      <button name="OK" value="ok" class="modal-button">OK</button>
+      <button name="Cancel" value="cancel" class="modal-button">Cancel</button>
+    </div>
+  </div>
+</div>
+EOS
+      end
+
+      def standard_engine_issues
+
+      end
+
+      def using_fortitude
+
+      end
+
+      def fortitude_benefits
+
+      end
+    end
+  end
+end