rocketio-views 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 12d12aece5cc59444351677460242a3b0315b8e1
+  data.tar.gz: 761985a5b8353827fac8895f685172e7c73497c8
+SHA512:
+  metadata.gz: ae3365ec7bc3f4f8088f6985efdf4d49c155099d894a75a16d6e5149267fd0615af23515df7efd723b3b36592770b5d32c0f31cff7456c7de5333c5107483c4e
+  data.tar.gz: 94be982fc21bae4171a79660fa211a29461b1836947183d894de4e303097e512f5acbc7c8f75572301ff31587203fc1313daaa0fc68b89e21aed365b41832bb2

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.DS_Store
+.pryrc

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rocketio.gemspec
+gemspec

data/README.md

@@ -0,0 +1,3 @@
+# RocketIO Views
+
+#### View layer for RocketIO

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'tokyo'
+
+task :test do
+  Tokyo.run
+end
+
+task default: :test

data/lib/rocketio-views.rb

@@ -0,0 +1,50 @@
+# core
+require 'forwardable'
+
+# gems
+require 'rocketio'
+require 'tilt'
+
+module RocketIO
+
+  FOUND_TEMPLATES    = {}
+  READ_TEMPLATES     = {}
+  COMPILED_TEMPLATES = {}
+
+  ENGINE_CONST_FORMAT = '%sTemplate'.freeze
+  TEMPLATE_PATH_FORMAT = '%s/%s.%s'.freeze
+
+  DEFAULT_ENGINE = [Tilt::ERBTemplate, [].freeze].freeze
+
+  INHERITABLE_SETUPS.concat([
+    :engine,
+    :layout,
+    :layouts,
+    :templates,
+    :template_vars,
+  ])
+
+  class TemplateError < RuntimeError;  end
+  class LayoutError < RuntimeError;  end
+
+  # building a constant name for given engine name.
+  # if a class given, return it as is.
+  #
+  # @example
+  #   engine_class(:Slim) #=> :SlimTemplate
+  #
+  # @param engine  name
+  # @return [Symbol, Class]
+  #
+  def engine_class engine
+    return engine if engine.is_a?(Class)
+    (RocketIO::ENGINE_CONST_FORMAT % engine).to_sym
+  end
+
+  def engine_const engine
+    return engine if engine.is_a?(Class)
+    ::Tilt.const_get(engine)
+  end
+end
+
+require 'rocketio-views/controller'

data/lib/rocketio-views/controller.rb

@@ -0,0 +1,170 @@
+module RocketIO
+  class Controller
+    extend Forwardable
+
+    def_delegators RocketIO, :engine_const, :engine_class
+
+    # if called without arguments render a template with lowercased name of current request method, e.g. get for GET, post for POST etc.
+    # at first it will look between defined templates.
+    # then it will search a file.
+    # it will try each extension the effective engine has registered, e.g. .erb, .rhtml for ERB.
+    # it will search in the folder the controller was defined in(NOT in path_to_templates, which is used for defined templates only).
+    # so put each controller in a separate folder to avoid templates clash.
+    #
+    # if no file found a TemplateError will be raised.
+    # if a block given it will use the the string returned by the block as template
+    # and wont search for defined nor file templates.
+    #
+    # by default ERB engine will be used (@see engine).
+    #
+    # for layout it will take one given through options or one defined at class level.
+    # if none given, it will render without layout.
+    # to use a layout path_to_layouts should be defined at class level.
+    #
+    # by default it will use current instance as scope.
+    # to render in a isolated scope, set it via :scope option
+    #
+    # to pass some local variables use :locals option
+    #
+    # @example render ./get.erb without layout
+    #   class Pages < RocketIO::Controller
+    #
+    #     def get
+    #       render
+    #     end
+    #   end
+    #
+    # @example render ./get.erb with :master layout
+    #   class Pages < RocketIO::Controller
+    #     layout :master
+    #
+    #     def get
+    #       render
+    #     end
+    #   end
+    #
+    # @example render ./get.erb with explicit :master layout
+    #   class Pages < RocketIO::Controller
+    #
+    #     def get
+    #       render(layout: :master)
+    #     end
+    #   end
+    #
+    # @example render within isolated scope
+    #   class Pages < RocketIO::Controller
+    #
+    #     def get
+    #       render(scope: Object.new)
+    #     end
+    #   end
+    #
+    # @example render with custom locals
+    #   class Pages < RocketIO::Controller
+    #
+    #     def get
+    #       render(locals: {x: 'y'})
+    #     end
+    #   end
+    #
+    def render template = nil, opts = {}
+      opts, template = template, nil if template.is_a?(::Hash)
+      engine, engine_opts = resolve_engine(opts)
+      template = block_given? ? yield : resolve_template(template, engine)
+      scope    = opts.fetch(:scope, self)
+      locals   = template_vars.merge(opts.fetch(:locals, RocketIO::EMPTY_HASH)).freeze
+      layout   = opts.fetch(:layout, self.layout)
+      template = compile_template(template, engine, engine_opts).render(scope, locals)
+      layout   ? render_layout(layout, opts) {template} : template
+    end
+
+    # render a template that yields the given block.
+    # that's it, a layout is a template that yields given string.
+    #
+    # layout can be specified two ways:
+    #   - as layout name
+    #   - as string
+    #
+    # if both given a ArgumentError error raised.
+    # if :template option given, no layout lookups will occur.
+    #
+    # otherwise...
+    # if no layout name given, it will use the one set at class level.
+    # if no layout set at class level and no layout given, it will raise a RuntimeError.
+    #
+    # then it will search for given layout between defined ones.
+    # if none found, it will search a file in `path_to_layouts` folder.
+    # it will try each extension registered with effective engine.
+    # if no file found it will raise a TemplateError.
+    #
+    # block is required and should return the string to be yielded.
+    #
+    def render_layout template = nil, opts = {}, &block
+      template && opts[:template] && raise(ArgumentError, 'Both layout name and :template option given. Please use either one.')
+
+      opts, template = template, nil if template.is_a?(::Hash)
+      engine, engine_opts = resolve_engine(opts)
+      template = if template
+        resolve_layout(template, engine)
+      else
+        opts[:template] || begin
+          self.layout || raise(RocketIO::LayoutError, 'No default layout set and no explicit layout given')
+          resolve_layout(self.layout, engine)
+        end
+      end
+
+      scope  = opts.fetch(:scope, self)
+      locals = template_vars.merge(opts.fetch(:locals, RocketIO::EMPTY_HASH)).freeze
+      compile_template(template, engine, engine_opts)
+        .render(scope, locals, &(block || RocketIO::EMPTY_STRING_PROC))
+    end
+
+    private
+    def resolve_template template, engine
+      template ||= requested_method
+      return __send__(templates[template]) if templates[template]
+      read_template(find_template(dirname, template, engine))
+    end
+
+    def resolve_layout layout, engine
+      return __send__(layouts[layout]) if layouts[layout]
+      read_template(find_template(dirname, layout, engine))
+    end
+
+    def resolve_engine opts = nil
+      return engine_const(engine_class(opts[:engine])) if opts && opts[:engine]
+      [engine_const(engine[0]), engine[1]]
+    end
+
+    def read_template file
+      RocketIO::READ_TEMPLATES[[file, ::File.mtime(file).to_i]] ||= ::File.read(file)
+    end
+
+    def find_template path, template, engine
+      RocketIO::FOUND_TEMPLATES[[path, template, engine]] ||= begin
+        extensions = ::Tilt.default_mapping.extensions_for(engine)
+        file = nil
+        extensions.each do |ext|
+          try = RocketIO::TEMPLATE_PATH_FORMAT % [path, template, ext]
+          next unless File.exists?(try)
+          file = try
+          break
+        end
+        file || raise(RocketIO::TemplateError, '"%s" template not found in "%s".
+          Tried extensions: %s' % [template, path, extensions.join(', ')])
+      end
+    end
+
+    def compile_template template, engine, engine_opts = nil
+      RocketIO::COMPILED_TEMPLATES[[template.hash, engine, engine_opts]] ||= begin
+        engine.new(0, *engine_opts) { template }
+      end
+    end
+  end
+end
+
+require 'rocketio-views/engine'
+require 'rocketio-views/layout'
+require 'rocketio-views/layouts'
+require 'rocketio-views/templates'
+require 'rocketio-views/template_vars'

data/lib/rocketio-views/engine.rb

@@ -0,0 +1,76 @@
+module RocketIO
+  class Controller
+
+    # if no engine set, templates will be rendered using ERB engine.
+    # any engine supported by [Tilt](github.com/rtomayko/tilt) can be used.
+    # to set engine use symbolized constant name, e.g. :Slim, :Haml
+    # engine name is Case Sensitive and there should be a Tilt::{ENGINE}Template class defined
+    # e.g. `engine :Slim` will look for Tilt::SlimTemplate
+    # and  `engine RDiscount` will look for Tilt::RDiscountTemplate
+    #
+    # @note if a block given it will be executed at instance level
+    #   and result used for engine. To have any options passed at engine initialization
+    #   the block should return an array having engine as first element
+    #   and options as consequent elements.
+    #
+    # @note if given block returns no engine, inherited engine will be used
+    #
+    # @example use static engine
+    #   engine :Slim
+    #
+    # @example use static engine with options
+    #   engine :Slim, pretty_print: true
+    #
+    # @example use dynamically set engine
+    #   engine do
+    #     some_condition ? :SomeEngine : AnotherEngine
+    #   end
+    #
+    # @example use dynamically set engine with options
+    #   engine do
+    #     some_condition ? [:SomeEngine, :opt1, :opt2] : AnotherEngine
+    #   end
+    #
+    # @example Search will use ERB when requested by a bot and Slim otherwise
+    #
+    #   class BaseController < RocketIO::Controller
+    #     engine :Slim
+    #   end
+    #
+    #   class Search < BaseController
+    #     engine do
+    #       if request.user_agent =~ /i'm a bot/
+    #         # requested by a bot, using ERB
+    #         return :ERB
+    #       end
+    #       # requested by a user, returning no engine for inherited engine to be used
+    #     end
+    #   end
+    #
+    # @param engine  engine name.
+    # @param *engine_options  any arguments to be passed at engine initialization
+    # @param block  to be executed at instance level
+    #
+    def self.engine engine = nil, *engine_options, &block
+      @__engine__ = block || [RocketIO.engine_class(engine), engine_options.freeze].freeze
+      define_engine_methods
+    end
+
+    def self.define_engine_methods source = self
+      return unless engine = source.instance_variable_get(:@__engine__)
+      if Proc === engine
+        selfengine = allocate.engine
+        api.delete define_method(:__rocketio_engine__, &engine)
+        api.delete define_method(:engine) {
+          engine, *engine_options = __rocketio_engine__
+          return selfengine unless engine
+          [RocketIO.engine_class(engine), engine_options.freeze].freeze
+        }
+      else
+        api.delete define_method(:engine) {engine}
+      end
+    end
+
+    def engine; RocketIO::DEFAULT_ENGINE end
+  end
+end

data/lib/rocketio-views/layout.rb

@@ -0,0 +1,27 @@
+module RocketIO
+  class Controller
+
+    # by default templates will be rendered without layout.
+    # to make them render inside a layout use `layout :layout_name` at class level.
+    # to use a layout it should be defined at first (@see define_layout)
+    #
+    # @note to disable layout set it to false: `layout false`
+    #
+    # @param layout  name of a defined layout
+    #
+    def self.layout layout
+      @__layout__ = layout
+      define_layout_methods
+    end
+
+    def self.define_layout_methods source = self
+      return unless source.instance_variables.include?(:@__layout__)
+      layout = source.instance_variable_get(:@__layout__)
+      api.delete define_method(:layout) {layout}
+    end
+
+    # by default no layout used, so this method returns nil.
+    # controllers that uses a layout will override this method.
+    def layout; end
+  end
+end

data/lib/rocketio-views/layouts.rb

@@ -0,0 +1,85 @@
+module RocketIO
+  class Controller
+
+    # if only name given it will search for a file with same name in controller's dirname.
+    #
+    # if file name differs from layout name pass it as :file option.
+    # file path should be relative to controller's dirname.
+    # also a block accepted for :file option. the block will be executed at controllers's instance level
+    # and should return path to layout file.
+    # file name should NOT include extension.
+    #
+    # if a block given NO file will be searched and returned value will be used as layout.
+    #
+    # @note files will be searched relative to controller's dirname,
+    #   that's it, the folder controller was defined in and operates from.
+    #
+    # @note when searching for file multiple extensions will be tried,
+    #   that's it, all extensions controller's engine actually supports.
+    #
+    # @note controllers that inherits named layouts will always search for files in own dirname.
+    #   controllers that inherits :file layouts will search files in the original controller's dirname.
+    #
+    # @example define :master layout.
+    #   ./master.erb file will be used
+    #
+    #   define_layout :master
+    #
+    # @example define :master layout.
+    #   ../layouts/master.erb file will be used
+    #
+    #   define_layout :master, file: '../layouts/master'
+    #
+    # @example define :master layout.
+    #   ./admin file to be used when user logged in and ./user otherwise
+    #
+    #   define_layout :master, file: -> {user? ? 'admin' : 'user'}
+    #
+    # @example define :master layout using a block that returns the layout string.
+    #   no file will be used.
+    #
+    #   define_layout(:master) do
+    #     layout = Layouts.find_by(id: params[:layout_id]) || halt(400, 'Template not found')
+    #     layout.source
+    #   end
+    #
+    # @param name
+    # @param file
+    # @param block
+    #
+    def self.define_layout name, file: nil, &block
+      file && block && raise(::ArgumentError, 'both file and block given, please use either one')
+      (@__layouts__ ||= {})[name.to_sym] = {block: block, root: dirname, file: file, name: name}.freeze
+      define_layouts_methods
+    end
+
+    def self.define_layouts_methods source = self
+      return unless source.instance_variables.include?(:@__layouts__)
+      layouts = source.instance_variable_get(:@__layouts__).each_with_object(allocate.layouts.dup) do |(name,setup),o|
+        o[name] = :"__#{name}_layout__"
+        if setup[:block]
+          # block given, do not search for file, use returned value instead
+          api.delete define_method(o[name], &setup[:block])
+        elsif setup[:file]
+          # file given, search the file in original controller dirname
+          meth_name = :"__#{name}_layout_file__"
+          meth_proc = setup[:file].is_a?(::Proc) ? setup[:file] : -> {setup[:file]}
+          api.delete define_method(meth_name, &meth_proc)
+          api.delete define_method(o[name]) {
+            engine, * = resolve_engine
+            read_template(find_template(setup[:root], __send__(meth_name), engine))
+          }
+        else
+          # only name given, search for a file with same name in controller's dirname
+          api.delete define_method(o[name]) {
+            engine, * = resolve_engine
+            read_template(find_template(self.dirname, setup[:name], engine))
+          }
+        end
+      end.freeze
+      api.delete define_method(:layouts) {layouts}
+    end
+
+    def layouts; RocketIO::EMPTY_HASH end
+  end
+end