viu 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f24b77a5e5a5ada196406705ac4ff02102f7915321f0b22cc946f8a9fc27040
-  data.tar.gz: 2648be1eec444b862d8c7c40f4ccf557011be42784a9ab29b0944f8251d8fff7
+  metadata.gz: a20c56c9d9d9efc2b46ed24d46628f24e671e28f5601cdd475939df6b2162974
+  data.tar.gz: 2b940845dd9fc93fc8af36c7341581b2c37d2cf28649d17f156b7f56666191c2
 SHA512:
-  metadata.gz: fb6709c1bf1b41bf7cd451fc20683fcb6e98e7aa4bfe107a21bea21e8a0d0ece7277f6de65e75c385eb545498306bd75a148e497ce5e3799d6d8f875238ed6ce
-  data.tar.gz: 6b75da7d7c59928851d230ed0b1f4dcb527cf3f0d8b3bbef93c6c87d1ecd8f023155d1ab5026b75b64223c45301c6e7b8fbc70c415401ecfb4ab2984401a323f
+  metadata.gz: 2864b1ecae62628434db59ea5256914b826c42305b66fa0bf6437319e16fa898e828fdea020b87c5d19e8537261f112732d7fbf90ef092e809e5369aa487f2e9
+  data.tar.gz: 1c0cb834d20c499808007b04a3c993a08a6858bb56bd03ac699ee27f047386f585b63075823f4d6cad84c714fefb71b714942865a2335500083f4954bedb53e6

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.0.3 2020-09-02
+
+- Added Viu::Json
+- Added Viu::Xml
+- Allow Viu::Html template! to receive a proc
+
 ## 0.0.2 2020-08-16
 
 ### Added

data/Gemfile

@@ -7,3 +7,4 @@ gemspec
 rails_version = "#{ENV['RAILS_VERSION'] || '~> 5.2'}"
 
 gem "rails", rails_version == "master" ? { github: "rails/rails" } : rails_version
+gem "oj"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    viu (0.0.2)
+    viu (0.0.3)
 
 GEM
   remote: https://rubygems.org/
@@ -48,6 +48,7 @@ GEM
       minitest (~> 5.1)
       tzinfo (~> 1.1)
     arel (9.0.0)
+    bigdecimal (2.0.0)
     builder (3.2.4)
     concurrent-ruby (1.1.7)
     crass (1.0.6)
@@ -75,6 +76,8 @@ GEM
     nio4r (2.5.2)
     nokogiri (1.10.10)
       mini_portile2 (~> 2.4.0)
+    oj (3.10.12)
+      bigdecimal (>= 1.0, < 3)
     rack (2.2.3)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
@@ -134,6 +137,7 @@ DEPENDENCIES
   bundler (~> 1.17)
   haml (~> 5)
   minitest (~> 5.0)
+  oj
   rails (~> 5.2)
   rake (~> 12.3)
   simplecov (~> 0.18.0)

data/README.md

@@ -1,26 +1,382 @@
 # Viu
 
-Currently this is a POC (proof of concept), on the usage of `ActionView` as a "real" view layer. Inspired on
-`view_component`, `cells` and others, `viu` is just a small wrapper around `AV`. It aims to work with the least amount
-of surprise with Rails, but with a few boundaries, like a View won't be able to automatically access `@ivars` defined
-in the controller, those have to explicitly be passed to them.
+Rails' missing View layer.
 
-The project is already been tested on a small scale in our production environment.
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "viu"
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install viu
+```
+
+## Rails Setup
+
+Add this to your `config/application.rb` file:
+
+```ruby
+config.eager_load_paths << Rails.root.join("app/views")
+```
+
+This will add the `app/views` folder to the eager load paths, as it is not loaded there by default.
+
+## Viu::Html
+
+Probably the most common view type of the wild web lands.
+
+### Usage
+
+`app/views/awesome_view.rb`:
+```ruby
+class AwesomeView < Viu::Html
+
+  layout! Layouts::ApplicationLayout
+
+  def initialize(posts:)
+    @posts = posts
+  end
+
+  private
+
+  def power_level_class(power)
+    return "over-9000" if power > 9000
+
+    "not-awesome-enough"
+  end
+end
+```
+
+`app/views/awesome_view.html.erb`:
+```erb
+<h1>Awesomesauce</h1>
+<%- @posts.each do |post| %>
+  <article class="<%= power_level_class(post.awesomeness) %>">
+    <h1><%= link_to post.title, post, class: "awesome-title" %></h1>
+    <p><%= post.summary %></p>
+  </article>
+<%- end %>
+```
+
+`app/controllers/home_controller.rb`:
+```ruby
+# GET /awesome
+def awesome
+  posts = Post.order(awesomeness: :desc)
+  render_view AwesomeView.new(posts: posts)
+end
+```
 
-## Your first View
+Unless a template is given directly (using the `template! "file"` option inside the view), a view will try to find a
+template with it's name.
+
+As seen in the example above a view's template has access to all instance variables, public and private methods defined
+in the view, as well as all `ActionView` helpers.
+
+Also, the view won't have access to any variables or instance variables defined in the controller, those have to be
+passed in directly, as shown in `AwesomeView.new(posts: posts)`.
+
+### ApplicationView
+
+Usually it's a common practice in rails projects to define an `ApplicationController` or `ApplicationRecord` base class
+that can be inherited from. The same can be done with views, an `ApplicationView` class is a good place to put some
+basic functionalities that should be available to all views.
+
+### Callable templates
+
+A view's template can be overridden with a `proc`. __Attention:__ currently using a callable template doesn't work with
+layouts, they will be ignored.
+
+```ruby
+# defining the view
+class HeaderView < ApplicationView
+
+  template! proc { tag.h1 @title }
+
+  def initialize(title:)
+    @title = title
+  end
+end
+
+# rendering the view
+render_view HeaderView.new(title: "Mas Gente!") # => "<h1>Mas Gente!</h1>"
+```
+
+### Layouts
+
+By default a view won't be rendered inside a layout. To use a layout, one has to be declared, either directly on the
+view or passed to the `render_view` method.
+
+#### Defining a layout template
 
 `app/views/my_view.rb`:
 ```ruby
-class MyView < Viu::Html
-  def initialize(name)
-    @name = name
+class MyView < ApplicationView
+  # This will look for an application template inside app/views/layouts,
+  # it can be a html.erb or any other template language defined in your application.
+  layout! 'layouts/application'
+end
+```
+
+`app/views/layouts/application.html.erb`:
+```erb
+<html>
+  <head>
+    <title>A view view a Layout</title>
+    <%= stylesheet_link_tag "application" %>
+    <%= javascript_include_tag "application" %>
+  </head>
+  <body>
+    <header>Header from the layout</header>
+    <%= yield %>
+  </body>
+</html>
+```
+
+#### Defining a layout view
+
+A layout can also be a `Viu::Layout` class, in this case it will work pretty much like a `Viu::Html`.
+
+`app/views/my_view.rb`:
+```ruby
+class MyView < ApplicationView
+  layout! Layouts::ApplicationLayout
+end
+```
+
+`app/views/layouts/application_layout.rb`:
+```ruby
+module Layouts
+
+  # a layout needs to inherit from Viu::Layout
+  class ApplicationLayout < Viu::Layout
+
+    def header_text
+      "This is a Viu::Layout"
+    end
   end
 end
 ```
 
-`app/views/my_view.html.erb`:
+`app/views/layouts/application_layout.html.erb`:
 ```erb
-<h1><%= @name %></h1>
+<html>
+  <head>
+    <title>A Viu::Layout</title>
+    <%= stylesheet_link_tag "application" %>
+    <%= javascript_include_tag "application" %>
+  </head>
+  <body>
+    <header><%= header_text %></header>
+    <%= yield %>
+  </body>
+</html>
 ```
 
-Unless a template is given directly, a view will try to find a template with it's name.
+Similar as the `Viu::Html` a layout will search for a template with it's name, if none is given directly.
+
+#### Defining a layout `proc`
+
+A layout can also be declared as a `proc`, this is useful when the view wants to override the layout parameters.
+The `proc` will be executed in the context of the view and the result must respond to `render_in`.
+
+`app/views/my_view.rb`:
+```ruby
+class MyView < ApplicationView
+
+  layout! proc { Layouts::ApplicationLayout.new(header_text: text) }
+
+  private
+
+  def text
+    "Text from the view"
+  end
+end
+```
+
+`app/views/layouts/application_layout.rb`:
+```ruby
+module Layouts
+  class ApplicationLayout < Viu::Layout
+
+    attr_reader :header_text
+
+    def initialize(header_text: 'The header text')
+      @header_text = header_text
+    end
+  end
+end
+```
+
+`app/views/layouts/application_layout.html.erb`:
+```erb
+<html>
+  <head>
+    <title>A Viu::Layout</title>
+    <%= stylesheet_link_tag "application" %>
+    <%= javascript_include_tag "application" %>
+  </head>
+  <body>
+    <header>
+      <!-- it will render "Text from the view" here -->
+      <%= header_text %>
+    </header>
+    <%= yield %>
+  </body>
+</html>
+```
+
+#### Overriding layout on `render_view`
+
+Usually a `layout` is defined directly in the view, as most of the times a view will be used in a single "context",
+but if needed it can be overridden on the `render_view` with the `layout:` option, like so:
+
+```ruby
+# it accepts a template
+render_view MyView.new, layout: 'layouts/admin'
+
+# a Viu::Layout
+render_view MyView.new, layout: Layouts::OtherLayout
+
+# or a proc
+render_view MyView.new, layout: proc { Layouts::OtherLayout.new(title: 'Dashboard') }
+```
+
+## Viu::Json
+
+This is a simple module that can be included in your views, it will add a `to_json` method, this is called by default
+when rendering in a Rails env. The value returned from `json_output` will be the output of the view.
+
+`app/views/api/posts/resource_view.rb`:
+```ruby
+module Api
+  module Posts
+    class ResourceView
+      include Viu::Json
+
+      def initialize(post:)
+        @post = post
+      end
+
+      private
+
+      def author
+        @author ||= @post.author
+      end
+
+      def json_output
+        {
+          title: @post.title,
+          published_on: @post.published_on.to_s(:iso8601),
+          author: {
+            name: author.name,
+            avatar: author.avatar.url
+          }
+        }
+      end
+    end
+  end
+end
+```
+
+`app/controllers/api/posts_controller.rb`:
+```ruby
+def show
+  post = Post.find(params[:id])
+  render json: Api::Posts::ResourceView.new(post: post)
+end
+```
+
+The default `JSON` encoder can be overridden like so:
+
+```ruby
+class MyJsonView
+  include Viu::Json
+
+  json_encoder ->(input) { Oj.dump(input) }
+
+end
+```
+
+## Viu::Xml
+
+Similar to `Viu::Json` this is a simple module that can be included in your views, it will add a `to_xml` method,
+this is called by default when rendering in a Rails env. The value returned from `xml_output` will be the output
+of the view.
+
+`app/views/api/posts/resource_view.rb`:
+```ruby
+module Api
+  module Posts
+    class ResourceView
+      include Viu::Xml
+
+      def initialize(post:)
+        @post = post
+      end
+
+      private
+
+      def author
+        @author ||= @post.author
+      end
+
+      def xml_output
+        {
+          title: @post.title,
+          published_on: @post.published_on.to_s(:iso8601),
+          author: {
+            name: author.name,
+            avatar: author.avatar.url
+          }
+        }
+      end
+    end
+  end
+end
+```
+
+`app/controllers/api/posts_controller.rb`:
+```ruby
+def show
+  post = Post.find(params[:id])
+  render xml Api::Posts::ResourceView.new(post: post)
+end
+```
+
+The default `XML` encoder can be overridden like so:
+
+```ruby
+class MyXmlView
+  include Viu::Xml
+
+  xml_encoder ->(input) { Ox.dump(input) }
+
+end
+```
+
+## Known Issues
+
+* A `Viu::Layout` doesn't work with `content_for` blocks, it's only available on a regular layout template for now;
+* Templates and partials require the "full" path, eg: `layouts/application` or `posts/index`;
+* Currently layout inheritance isn't working correctly.
+
+## About
+
+Inspired by `view_component`, `cells` and others, currently this is a POC (proof of concept) to create a View layer
+for Rails, it uses `ActionView` as the base for HTML views and it aims to work with the least amount of surprises on a
+Rails application, but with a few boundaries, like a View won't be able to automatically access `@ivars` defined
+in a controller, those have to explicitly be passed to them.
+
+The project is already been tested on a small scale in our production environment.

data/lib/viu.rb

@@ -4,6 +4,8 @@ require "viu/version"
 
 require "viu/html"
 require "viu/layout"
+require "viu/json"
+require "viu/xml"
 require "viu/test_case"
 
 require 'viu/railtie' if defined?(Rails)

data/lib/viu/html.rb

@@ -10,6 +10,8 @@ module Viu
     def render_in(view_context, options = EMPTY_HASH)
       __setup!(view_context)
 
+      return __render_template_proc if __fetch_template!.is_a?(Proc)
+
       layout = options.fetch(:layout, self.class.layout)
 
       if layout.is_a?(Class)
@@ -48,6 +50,10 @@ module Viu
       self.class.template!(self.class.name.underscore)
     end
 
+    def __render_template_proc
+      self.instance_exec(&__fetch_template!)
+    end
+
     def __render_layout_class(layout)
       layout.new.render_in(@view_context) do
         @view_renderer.render(self, template: __fetch_template!, layout: nil)

data/lib/viu/json.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+
+module Viu
+  module Json
+    extend ActiveSupport::Concern
+
+    DEFAULT_JSON_ENCODER = ->(input) { input.to_json }.freeze
+
+    included do
+      class_attribute :__json_encoder, instance_accessor: false, instance_predicate: false,
+        default: DEFAULT_JSON_ENCODER
+
+      attr_reader :rendering_options
+
+      def to_json(options = EMPTY_HASH)
+        @rendering_options = options
+        self.class.__json_encoder.call(json_output)
+      end
+    end
+
+    class_methods do
+
+      def json_encoder(value)
+        self.__json_encoder = value
+      end
+    end
+  end
+end

data/lib/viu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Viu
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/viu/xml.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+
+module Viu
+  module Xml
+    extend ActiveSupport::Concern
+
+    DEFAULT_XML_ENCODER = ->(input) { input.to_xml }.freeze
+
+    included do
+      class_attribute :__xml_encoder, instance_accessor: false, instance_predicate: false,
+        default: DEFAULT_XML_ENCODER
+
+      attr_reader :rendering_options
+
+      def to_xml(options = EMPTY_HASH)
+        @rendering_options = options
+        self.class.__xml_encoder.call(xml_output)
+      end
+    end
+
+    class_methods do
+
+      def xml_encoder(value)
+        self.__xml_encoder = value
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: viu
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Ralf Schmitz Bongiolo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-16 00:00:00.000000000 Z
+date: 2020-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,12 +114,14 @@ files:
 - bin/setup
 - lib/viu.rb
 - lib/viu/html.rb
+- lib/viu/json.rb
 - lib/viu/layout.rb
 - lib/viu/railtie.rb
 - lib/viu/rendering_helpers.rb
 - lib/viu/test_case.rb
 - lib/viu/test_helpers.rb
 - lib/viu/version.rb
+- lib/viu/xml.rb
 - viu.gemspec
 homepage: https://github.com/mrbongiolo/viu
 licenses: