rubyoshka 0.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcac0e7abbbb0bad4f11b3c3b500ed7c14f506d06c6aa8ecbcec4cfc3503ce16
-  data.tar.gz: 8fd105613444edd272644aff2cb054b4c0a540789f5e63f41a4d9c033fc36577
+  metadata.gz: ff842a3a48141bcef19e1298cb26ff59cd9dbb0a58075efe50b3f73892a75c2f
+  data.tar.gz: 4556f2fc468d48d9a98b4582ab25f0068d814d933e0e0c198d45fce9f692960b
 SHA512:
-  metadata.gz: 4f693a62532ae3235383068ed789cc144fd38ec7723c5ff728ace5b0a5b0ae267e61fc3e8140ac8972420a8c35fa0731b543dbd84016bda049843038ae5bafa4
-  data.tar.gz: 3ca48bcd081c077635cffa99d36823e2f19c1ac832a26426ae510e233d1054880a0e74b3047aeef389dcb88b4905a95339e90145cd131efcd2a8edba23599dea
+  metadata.gz: 79e2fd4e9f970201191e576f1b4bd971bef99cd1a7fbcbaee2102d6be8b8e0ec59e6ad0d26f6770ba756bd2e7b92ab84128a6bded62219417af94e1f9dbce159
+  data.tar.gz: 9d78ee6402ddc3e873d7b47073c655cb6501c46f91e8f4f6bb2041581367ee7cc5c661cc63e6f356e17a8d9cab59f9cf719e4497166f3fa890b4b320c62473c0

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+0.2 2019-01-07
+--------------
+
+* Better documentation
+* Fix #text
+* Add local context
+
 0.1 2019-01-06
 --------------
 

data/README.md

@@ -2,7 +2,8 @@
 
 [INSTALL](#installing-rubyoshka) |
 [TUTORIAL](#getting-started) |
-[EXAMPLES](examples)
+[EXAMPLES](examples) |
+[REFERENCE](reference)
 
 ## What is Rubyoshka
 
@@ -11,14 +12,20 @@ features:
 
 - HTML templating using plain Ruby syntax
 - Minimal boilerplate
+- Mix logic and tags freely
+- Use global and local contexts to pass values to reusable components
 - Automatic HTML escaping
 - Composable nested components
 - Access to a global context from anywhere in the component hierarchy
-- High performance
+- About 4 times faster than ERubis (see [benchmark](examples/perf.rb)).
+
+> **Note** Rubyoshka is a new library and as such may be missing features and
+> contain bugs. Your issue reports and code conributions are most welcome!
 
 With Rubyoshka you can structure your templates like a Russian doll, each
-component containing any number of nested components, in a similar fashion to
-React. The name *Rubyoshka* is a nod to Matryoshka, the Russian nesting doll.
+component containing any number of nested components, in a somewhat similar
+fashion to React. The name *Rubyoshka* is a nod to Matryoshka, the Russian
+nesting doll.
 
 ## Installing Rubyoshka
 
@@ -49,7 +56,9 @@ html = H {
 }
 ```
 
-To render the template use `render`:
+## Rendering a template
+
+To render a Rubyoshka template use the `#render` method:
 
 ```ruby
 H { span 'best span' }.render  #=> "<span>best span</span>"
@@ -102,14 +111,121 @@ H { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
 H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
 ```
 
+## Logic in templates
+
+Since Rubyoshka templates are just a bunch of Ruby, you can easily write your
+view logic right in the template:
+
+```ruby
+def user_message(user)
+  H {
+    if user
+      span "Hello, #{user.name}!"
+    else
+      span "Hello, guest!"
+    end
+  }
+end
+```
+
+## Local context
+
+When writing logic and referring to application values in you templates, there
+are some ground rules to obey. Since the template code is evaluated using
+`#instance_eval` that means that you will not be able to directly use instance
+variables or do unqualified method calls (calls to `self`).
+
+In order to facilitate exposing values to your template logic, Rubyoshka
+provides an API for setting a local context. The local context is simply a set
+of values that are accessible for a given block of code, and to any nested
+blocks within it. The local context is primarily set using the `#with` method:
+
+```ruby
+H {
+  with(name: 'world') {
+    div {
+      span "Hello, #{name}"
+    }
+  }
+}
+```
+
+The local context can alternatively be set by passing hash values to `#H`:
+
+```ruby
+H(name: 'world') {
+  div { span "Hello, #{name}" }
+}
+```
+
+A local context can also be set for a component (see the next section) simply by
+passing arguments to the component call:
+
+```ruby
+Greeting = H { span "Hello, #{name}" }
+
+H {
+  div {
+    Greeting(name: 'world')
+  }
+}
+```
+
+### Tip: accessing `self` and instance variables from a template
+
+In order to be able to access the object in the context of which the template is
+defined or any of its methods, you can pass it in the local context:
+
+```ruby
+class User
+  ...
+  def greeting_template
+    H(user: self) {
+      ...
+      span "Hello, #{user.name}"
+      span "your email: #{user.email}"
+    }
+  end
+end
+```
+
+Instance variables can be passed to the template in a similar fashion:
+
+```ruby
+H(name: @name) { span "Hello, #{name}" }
+```
+
+## Global context
+
+In addition to the local context, Rubyoshka also provides a way to set a global
+context, accessible from anywhere in the template, and also in sub-components 
+used in the template.
+
+The global context is a simple hash that can be accessed from within the
+template with the `#context` method:
+
+```ruby
+greeting = H { span "Hello, #{context[:name]}" }
+```
+
+The global context can be set upon rendering the template:
+
+```ruby
+greeting.render(name: 'world')
+```
+
 ## Templates as components
 
-Rubyoshka makes it easy to compose multiple templates into a whole HTML
+Rubyoshka makes it easy to compose multiple separate templates into a whole HTML
 document. Each template can be defined as a self-contained component that can
 be reused inside other components. Components should be defined as constants,
-either in the global namespace, or on the Rubyoshka namespace:
+either in the global namespace, or on the `Rubyoshka` namespace. Each component
+can be defined as either a Rubyoshka instance (using `#H`) or as a `proc` that
+returns a Rubyoshka instance:
 
 ```ruby
+Title = H { h1 title }
+
 # Item is actually a Proc that returns a template
 Item = ->(id:, text:, checked:) {
   H {
@@ -122,6 +238,7 @@ Item = ->(id:, text:, checked:) {
 
 def render_items(items)
   html = H {
+    Title()
     ul {
       items.each { |id, attributes|
         Item id: id, text: attributes[:text], checked: attributes[:active]
@@ -131,26 +248,45 @@ def render_items(items)
 end
 ```
 
-## Wrapping arbitrary HTML
+Note that a component is invoked as a method, which means that if no arguments
+are passed, you should add an empty pair of parens, as shown in the example
+above.
 
-Components can be used to wrap arbitrary HTML content by defining them as procs
-that accept blocks:
+In addition to using components defined as constants, you can also use
+non-constant components by invoking the `#emit` method:
+
+```ruby
+greeting = H { span "Hello, world" }
+
+H {
+  div {
+    emit greeting
+  }
+}
+```
+
+## Wrapping arbitrary HTML with a component
+
+Components can also be used to wrap arbitrary HTML with addional markup. This is
+done by implementing the component as a `proc` that takes a block:
 
 ```ruby
 Header = ->(&inner_html) {
   header {
-    h1 'title'
+    h1 'This is a title'
     emit inner_html
   }
 }
 
-H { Header { button 'OK'} }.render #=> "<header><h1>title</h1><button>OK</button></header>"
+Greeting = H { span "Hello, #{name}" }
+
+H { Header { Greeting(name: 'world') }.render #=> "<header><h1>This is a title</h1><span>Hello, world</span></header>"
 ```
 
 ## Some interesting use cases
 
 Rubyoshka opens up all kinds of new possibilities when it comes to putting
-together pieces of HTML. Feel free to explore the possibilities!
+together pieces of HTML. Feel free to explore the API!
 
 ### Routing in the view
 
@@ -163,12 +299,7 @@ Router = ->(path) {
   when '/'
     PostIndex()
   when /^posts\/(.+)$/
-    post = get_post($1)
-    if post
-      Post(post)
-    else
-      ErrorPage(404)
-    end
+    Post(get_post($1))
   end
 }
 
@@ -184,4 +315,97 @@ Blog = H {
     }
   }
 }
-```
+```
+
+### A general purpose router
+
+A more flexible, reusable approach could be achieved by implementing a
+higher-order routing component, in a similar fashion to
+[React Router](https://reacttraining.com/react-router/web/guides/quick-start):
+
+```ruby
+Route = ->(path, &block) {
+  match = path.is_a?(Regexp) ?
+    context[:path] =~ path : context[:path] == /^#{path}/
+  emit block if match
+}
+
+Blog = H {
+  html {
+    head {
+      title: 'My blog'
+    }
+    body {
+      Topbar()
+      Sidebar()
+      div id: 'content' {
+        Route '/'             { PostIndex() }
+        Route /^posts\/(.+)$/ { Post(get_post($1)) }
+      }
+    }
+  }
+}
+```
+
+## Reference
+
+#### `Rubyoshka#initialize(**context, &block)` a.k.a. `Kernel#H`
+
+- `context`: local context hash
+- `block`: template block
+
+Initializes a new Rubyoshka instance. This method takes a block of template 
+code, and an optional [local context](#local-context) in the form of a hash.
+The `Kernel#H` method serves as a shortcut for creating Rubyoshka instances.
+
+#### `Rubyoshka#render(**context)`
+
+- `context`: global context hash
+
+Renders the template with an optional [global context](#global-context)
+hash.
+
+#### Methods accessible inside template blocks
+
+#### `#<tag/component>(*args, **props, &block)`
+
+- `args`: tag arguments. For an HTML tag Rubyoshka expects a single `String`
+  argument containing the inner text of the tag.
+- `props`: hash of tag attributes
+- `block`: inner HTML block
+
+Adds a tag or component to the current template. If the method name starts with
+an upper-case letter, it is considered a [component](#templates-as-components).
+
+If a text argument is given for a tag, it will be escaped.
+
+#### `#context`
+
+Accesses the [global context](#global-context).
+
+#### `#emit(object)` a.k.a. `#e(object)`
+
+- `object`: `Proc`, `Rubyoshka` instance or `String`
+
+Adds the given object to the current template. If a `String` is given, it is
+rendered verbatim, i.e. without escaping.
+
+#### `html5(&block)`
+
+- `block`: inner HTML block
+
+Adds an HTML5 `doctype` tag, followed by an `html` tag with the given block.
+
+#### `#text(data)`
+
+- `data` - text to add
+
+Adds text without wrapping it in a tag. The text will be escaped.
+
+#### `#with(**context, &block)`
+
+- `context`: local context hash
+- `block`: HTML block
+
+Sets a [local context](#local-context) for use inside the given block. The
+previous local context will be restored upon exiting the given block.

data/lib/rubyoshka/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Rubyoshka
-  VERSION = '0.1'
+  VERSION = '0.2'
 end

data/lib/rubyoshka.rb

@@ -41,16 +41,22 @@ class Rubyoshka
     # @param block [Proc] block passed to method call
     # @return [void]
     def method_missing(sym, *args, &block)
+      value = @local && @local[sym]
+      return value if value
+
       if sym =~ R_CONST_SYM
         o = instance_eval(sym.to_s) rescue Rubyoshka.const_get(sym) \
             rescue Object.const_get(sym)
         case o
         when ::Proc
-          self.class.define_method(sym) { |*a, &b| emit o.(*a, &b) }
-          emit o.(*args, &block)
+          self.class.define_method(sym) { |*a, &b| emit(o.(*a, &b)) }
+          emit(o.(*args, &block))
         when Rubyoshka
-          self.class.define_method(sym) { emit o }
-          emit(o)
+          self.class.define_method(sym) { |**ctx|
+            ctx.empty? ? emit(o) : with(ctx) { emit(o) }
+          }
+          ctx = args.first
+          Hash === ctx ? with(ctx) { emit(o) } : emit(o)
         when ::String
           @buffer << o
         else
@@ -73,6 +79,7 @@ class Rubyoshka
         instance_eval(&o)
       when Rubyoshka
         instance_eval(&o.block)
+      when nil
       else
         @buffer << o.to_s
       end
@@ -160,30 +167,45 @@ class Rubyoshka
     # Emits text into the rendering buffer
     # @param data [String] text
     def text(data)
-      @buffer << E.escape_html(text)
+      @buffer << E.escape_html(data)
+    end
+
+    # Sets a local context for the given block
+    # @param ctx [Hash] context hash
+    # @param block [Proc] nested HTML block
+    # @return [void]
+    def with(**ctx, &block)
+      old_local, @local = @local, ctx
+      instance_eval(&block)
+    ensure
+      @local = old_local
     end
   end
 
   attr_reader :block
 
   # Initializes a Rubyoshka with the given block
+  # @param ctx [Hash] local context
   # @param block [Proc] nested HTML block
   # @param [void]
-  def initialize(&block)
-    @block = block
+  def initialize(**ctx, &block)
+    @block = ctx.empty? ? block : proc { with(ctx, &block) }
   end
 
   # Renders the associated block and returns the string result
   # @param context [Hash] context
   # @return [String]
-  def render(context = {})
+  def render(**context)
     Rendering.new(context, &block).to_s
   end
 end
 
 module ::Kernel
   # Convenience method for creating a new Rubyoshka
-  def H(&block)
-    Rubyoshka.new(&block)
+  # @param ctx [Hash] local context
+  # @param block [Proc] nested block
+  # @return [Rubyoshka] Rubyoshka template
+  def H(**ctx, &block)
+    Rubyoshka.new(ctx, &block)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubyoshka
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-06 00:00:00.000000000 Z
+date: 2019-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: modulation
@@ -115,8 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: 'Rubyoshka: composable HTML templating for Ruby'