templet_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e7deaf8989e6c551f2a2a43643b4a9cf0cc869f6
+  data.tar.gz: d36afba37dfd38b61d462d812df24ec821413265
+SHA512:
+  metadata.gz: f717307ac491b39041177dcaa47bc3939e7bfa746829759f77a2963ac1a58263a521fca4e7a537e482fa3f7278b7d4526afe18bec17490681978f1414f8fd4e9
+  data.tar.gz: 5144a6c2c625b587c55c263a42943503f6c1ac01ced1220aa833aa6c6fca5129a936c6fab38c14c7c9b7668b23cbedc70d926e5ef169ca89d982822dcbe3cab3

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.0
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in templet_rails.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,1059 @@
+# Templet
+
+## Sections
+
+[Forward](#forward)
+a quick run through and info on learning resources.
+
+[Introduction](#intro)
+a short summary.
+
+[FAQ](#faq)
+frequently asked questions.
+
+[Generators](#gen)
+where you get started.
+
+[Notes](#notes)
+a wider summary.
+
+<a name="forward"></a> 
+## Forward
+
+### Outline
+
+This is a framework to render views in Rails.
+
+It replaces ERb (or HAML, etc.) scripts with a single class
+that, by default, renders (Bootstrap) HTML for the standard REST actions.
+
+It facilitates a more object oriented approach to coding up views,
+yet remains compatible with existing view scripts and Helper methods.
+
+If you're familiar with Rails,
+getting to grips with this framework should cause little difficulty,
+or take much time.
+
+### Example Application
+
+To learn it practically, there is an example Rails app,
+[questionable](https://github.com/srycyk/questionable),
+which is a small administrative front-end of just three models.
+
+This small app has lots of examples that illustrate
+how to customise views using the framework.
+
+By itself, this app should provide enough information
+for you to write code in the framework effectively.
+It demonstrates most of the finer points involved in
+adapting it for particular requirements.
+
+### Documentation Sources
+
+For a broad, more theoretical, overview of the framework,
+there is this guide.
+
+Although it's quite wordy, short of examples, not exhaustive,
+and a lot to take in at one sitting,
+nevertheless, it does explain why you may want to use it,
+where you begin,
+how it works,
+what it contains,
+and its internal organisation.
+
+In addition, there is another guide found at,
+[templet](https://github.com/srycyk/templet),
+that describes the DSL that renders HTML tags.
+This DSL, which is heavily used by the higher-level framework,
+is so straightforward and succinct
+that you may only need a passing acquaintance with it.
+_You may well pick it up as you go along._
+
+For hard-core punishment gluttons, there is yet more documentation -
+the source code carries comments in the harder bits,
+and the purpose of each class is spelled out.
+
+<a name="intro"></a> 
+## Introduction
+
+### Packaging
+
+These facilities come in two gems,
+[templet](https://github.com/srycyk/templet)
+and
+[templet\_rails](https://github.com/srycyk/templet_rails).
+
+The first is a self-contained DSL for rendering markup, i.e. HTML pages.
+
+The second, which relies on the first,
+is a Rails framework that has similar functionality to
+the the Rails scaffold generator.
+And it is as easy to get working, but more modular and extensible.
+
+> Naturally, these gems need to be declared in your *Gemfile*.
+> Please see the *Configuration* section below for further details.
+
+### Basic Design
+
+The framework is small and simple.
+So much so that *framework* may be too grand a term,
+as it could equally be described as a pattern,
+with an attached API.
+
+The framework follows many of Rails' conventions,
+notably it provides default behaviour
+that can be easily overridden or supplanted.
+
+### Benefits
+
+It allows the DRY principle to be more easily applied to the views
+than with the usual templates, (like ERb &amp; HAML),
+which are essentially a single block of in-line code,
+which can quickly become long and repetitive.
+
+The framework promotes productivity
+as the views can be written in idiomatic Ruby,
+thus allowing more standardisation, concision and encapsulation.
+
+The framework does *not*, in any way, *monkey-patch* the Rails core,
+and should work with just about any version of Rails, even future ones!
+Though it requires a fairly recent (i.e. supported) version of Ruby.
+
+### Installing
+
+An installation involves issuing a few commands, and, almost certainly,
+will have no knock-on effects elsewhere.
+Likewise, a de-installation is even less trouble.
+
+### Twitter Bootstrap Dependency
+
+In the framework, as it stands,
+you do really need to use *Twitter Bootstrap 3.3*.
+_Without it, the HTML will look awful!_
+
+If you don't currently use this particular Bootstrap (3.3) version,
+it won't be difficult, or take too long, to update the source yourself.
+
+But if you don't use Bootstrap, it'll take some time
+to modify the source to accommodate some other CSS library.
+ 
+### Main Sections
+
+The framework introduces the following code divisions:
+
+1. The framework's core code,
+   which is directly copied into your application's file system,
+   in a few separate sub-directories.
+   This shouldn't need much changing - if any.
+
+2. Application code, consisting of your own
+   modules that cater for specific use-cases.
+   _As a part of the initial installation,
+   there are general-purpose classes pre-installed in this area,
+   most of which are for a prototype layout._
+
+3. A declarative testing sub-system in Rspec, which is optional.
+
+### Usage
+
+#### Two Basic Steps
+
+To build individual application modules with the framework,
+you create a controller and a *Viewer* class,
+both of which can be generated.
+
+##### The Controller
+
+The controller looks pretty much the same as usual,
+except for the way the view is invoked.
+
+You render a view by calling, from the controller,
+a method on an instance of a *Viewer* class.
+
+However, you shouldn't need to refer to this *Viewer* class directly,
+as there are controller utilities that provide shortcuts
+to launch the view rendering.
+
+##### The Viewer
+
+This *Viewer* class carries out all of the HTML rendering,
+letting you diverge from default functionality
+that is provided by its superclasses.
+
+Normally, there is just one of these classes per controller,
+and they have (public) method names in common.
+
+Inside this *Viewer* class, you're able to override a hatful of methods,
+for either fine, or coarse, grained modifications.
+
+Among other things, this class offers the following features:
+
+1. Adding, or excluding, one or two surrounding Layouts which are
+   shared by a group of pages.
+
+2. An ability to use Partials that let you split the whole
+   into discrete parts.
+   Like the Layouts above, they are similar (in intent) to
+   their correlates in Rails, but here they are Ruby subclasses
+   that render HTML by means of a rudimentary DSL.
+
+3. An API to render composite HTML components,
+   like forms, tables and lists.
+
+4. Utility classes that build collections of REST links for actions
+   on any type of model - with or without a corresponding parent model.
+   These links can be wrapped in HTML lists, or in any markup you like.
+   By subclaassing, you can add extra links to these menus.
+
+5. Access all of the Rails *ActionView* methods,
+   such as *link_to*, *text\_field\_tag* &amp; *render*,
+   as well as those you may have added yourself in the traditional
+   Rails-generated Helper modules -
+   but with this framework, you won't need these anymore!
+
+### Getting Started
+
+#### Generators
+
+The gem for the framework consists of several generators,
+which are your starting point.
+
+A few are to do with the installation of the framework,
+and are to be run just once.
+
+The others are for producing application code,
+and are to be run multiple times with varying arguments.
+
+Principally, there is a scaffold generator that creates, at once,
+a controller, a *Viewer* class to customise the HTML output,
+some RSpec tests, and a Rails routing entry.
+
+The generated code code should work without intervention,
+providing default behaviour that can be easily modified,
+
+More information on using the generators is given below.
+
+#### Environment Setup
+
+Be aware that you'll need to add some simple configuration directives,
+which are mentioned in the *Configuration* section at the end.
+
+<a name="faq"></a> 
+## Frequently Asked Questions
+
+### What is it?
+
+It is a Ruby framework, with associated libraries,
+that provide an object oriented (pure Ruby) approach to
+the rendering of markup, i.e. HTML and XML.
+
+The framework is sparse, has few dependencies
+and is not particularly complicated.
+
+### Why use it?
+
+Primarily, it's to boost development efficiency.
+
+But you may also find it more comfortable to code in,
+as it gives you more of a free rein than, say, ERb scripts.
+
+#### *It's quick*
+
+Using the supplied generators,
+(which work like Rails' scaffolding),
+you can have a viable fully-functional REST interface up and running
+in next to no time.
+
+And when you need to augment or alter the default functionality,
+it lets you do so easily and briefly.
+
+#### *It's flexible*
+
+In Rails, object oriented support stops at the view stage.
+
+When you use scripts like ERb or HAML or SLIM,
+you're constrained by their in-line procedural design.
+
+These scripts often end up being monolithic and painful to maintain.
+Code sharing is too verbose,
+as it usually results in a proliferation of tiny files and
+complex helper methods, which, since they are global in scope,
+need to be named with care.
+
+In contrast, within this framework everything can be written in
+pure unrestrained Ruby,
+allowing you to use the language's object oriented (and functional)
+features as you see fit.
+
+For example, using this framework, it's much easier
+to implement general-purpose components,
+to fine-tune small variations,
+to enforce site-wide uniformity in presentation,
+and to rearrange the page sections.
+
+### How easy is to learn?
+
+For a Rails developer its workings should be intuitive.
+Also, the API is relatively small, and what you need to know
+to get started is even smaller.
+
+### Is it compatible with traditional view rendering?
+
+In this framework, you're still able to use the
+(convenient and well known) Rails helper methods,
+like *render*, *link\_to* and *options\_from\_collection\_for\_select*.
+
+This allows you to *mix 'n' match* the two approaches,
+which lays out a path should you require to switch
+from from one methodology to the other.
+
+### How is this facility used?
+
+You can use it as a framework
+that performs the entire view rendering process,
+or you can just use it as a library (toolkit) to render view segments.
+
+#### *As a framework*
+
+To use it as a framework there are generally just two classes to create,
+(though in the very simplest cases there is only one).
+
+1. A *Controller* class, which is almost the same as usual,
+   the only major difference is in the way the view handling is executed,
+   which is by the class described directly below.
+
+2. A *Viewer* class, which renders complete HTML pages
+   for (the actions of) its corresponding controller,
+   with which it has a similarly named public API.
+   For example, both may share the public method names, *index* and *show*.
+
+#### *As a library*
+
+If, instead, you want to use it as library for rendering components such
+as forms, tables, lists, navigation buttons, Bootstrap menus, etc..
+There are a several *mixin* Ruby modules, and utility classes,
+included that facilitate this.
+
+At present, you'll have to dip into the source yourself to learn this API,
+though it is covered briefly later on.
+
+### Will using it have any unwanted side-effects?
+
+Highly unlikely, as it doesn't alter anything in any existing classes,
+and there aren't too many calls to the Rails API.
+
+It has only one run-time dependency on a third-party gem,
+as it uses *Twitter Bootstrap 3.3*, (for the HTML presentation).
+
+### What does it contain?
+
+The package consists of two relatively small gems,
+firstly, a rendering DSL,
+and secondly, a gem that is for use with Rails and Bootstrap (3.3).
+
+The first is a run-time dependency.
+The second contains several generators
+that add files in your application's file system.
+
+### Where does it add its code?
+
+The framework, by default, is copied into two
+directories: *app/helpers/templet/* and *app/controllers/templet/*,
+and two Ruby modules in *app/helpers/*.
+
+Your application view's code is put under *app/helpers/app/*.
+
+### Is it easy to deinstall?
+
+If you try it out, and then decide to ditch it,
+a rollback will almost certainly be effortless.
+
+It will just involve deleting a number of files,
+for which there's a generator, *templet:destroy*.
+
+This generator deletes all of the framework
+and the nearly all of the application files,
+apart from any controllers that you may have generated,
+and entries in *config/routes.rb*.
+
+### What does it depend on?
+
+Apart from Rails itself, there is a dependency on *Twitter Bootstrap 3.3*.
+
+This is not strictly compulsory, (it'll spit out the HTML regardless)
+but, right now, you'll have to change the source code yourself
+to disentangle this dependency,
+
+It's currently for Bootstrap 3.3, but if you
+fork the code for compatibility with, say, Bootstrap 4,
+you should only be occupied for a few hours,
+and you'll only need to edit a half-dozen files at most.
+
+However, if you don't use Bootstrap,
+and you choose to adapt this framework
+to work with some other styling (CSS) API,
+it'll likely take you a good while.
+
+### Will it be supported?
+
+No guarantee!
+But will you need long-term external support? Probably not.
+
+The code-base so small that taking responsibility
+for its upkeep should not be too onerous.
+There is little to go wrong.
+
+### Are there tests?
+
+It comes supplied with a rudimentary testing system.
+
+This consists of Rspec *shared\_examples* that
+test the controller's JSON output,
+and other *shared\_examples* that test the output of the *Viewer* classes,
+using (Nokogiri) CSS selectors on the resultant HTML.
+
+Although limited in scope, these tests can be written in 
+a very small chunk of declarative code.
+Nonetheless, in their present form, they are not a viable substitute
+for the usual model and feature tests.
+
+When running the tests, it needs the gems:
+*rspec*, *nokogiri* and *factory_bot*,
+for which (model) factories have already been defined.
+
+### What sort of applications is it most suited for?
+
+1. It's ideal for REST-based apps, especially administrative dashboards.
+
+2. Experimental or MVP sites, where it can quickly plug holes.
+   The framework reduces development time because most modifications
+   can be written in compact sections of (structured) code.
+
+3. In general, it's for data-base driven sites -
+   not so much for fancy (HTML/JS-heavy) sites
+   where data is passively consumed.
+
+### What are its advantages?
+
+1. As well as being quicker to develop in, it seems to run a bit faster
+   than the conventional Rails ERb rendering.
+
+2. Presentational changes can be made from a single place,
+   and then propagate immediately throughout the whole site.
+   For example, all textual HTML links can be changed to iconic
+   in a single line of code.
+
+3. It lets you do things like putting view segments
+   into variables that you can pass around for, say,
+   later rendition within another nested component.
+
+4. It can be used alongside existing views scripts and Helper methods.
+
+5. Testing view components is made easier, as they can be implemented
+   in separate stand-alone classes.
+
+### What are its disadvantages?
+
+1. The bare Bootstrap styling is characterless,
+   and the HTML will be difficult for designers to modify.
+
+2. The way in which this framework is structured may rub against your
+   existing practices.
+
+3. Some functionality, provided by Rails, for view rendering
+   is now not available. These are things like: view path look-ups,
+   Turbolinks support, and an inability to *yield* additional content
+   at arbitrary positions on the page.
+
+4. Similarly, caching view segments may be more difficult than usual.
+   You should still be able to use Rails' low-level fragment caching,
+   but partial caching is impossible.
+
+5. Having to learn how to use the caboodle in the first place.
+   But since you've ploughed through this far, you're getting there,
+   and I congratulate your endurance!
+
+6. But seriously, there may be possible security issues with
+   code injection attacks.
+   This is because the whole page is made *html_safe*.
+   Probably the best way of safeguarding against this is by adding model
+   validations to ensure that malicious snippets of code cannot be saved
+   to begin with.
+   There is a validator module,
+   (*app/models/concerns/nasty_char_validator.rb*, in *questionable*)
+   which can be added to model classes to prevent users from saving
+   records containing field values with non-standard punctuation.
+   Alternatively, you could *sanitize* input fields
+   in a *before_validation* callback.
+
+### How does it compare to similar offerings?
+
+Although the following claims do present
+the framework in its *best light*,
+they, nevertheless, hold good, arguably.
+
+1. It is similar in function to data-base maintenance gems,
+   (like *active_admin*),
+   but while such like provide a finished application,
+   (which can only be modified via a restrictive DSL),
+   this framework provides a prototype (preliminary) application,
+   (which can be modified in any way you wish).
+
+2. It has the modularity of say, *cells*, but does not rely on
+   scripts behind the scenes, which add a layer of complexity,
+   requiring you, for one, to flit between multiple file edits.
+
+3. It has the *kick-start* convenience of Rails's scaffolding. 
+
+4. You can write HTML with the economy of HAML or SLIM,
+   and be assured that it's well-formed.
+
+5. The *Viewer* classes, in themselves, have the simplicity of Sinatra.
+
+<a name="gen"></a> 
+## Generators
+
+The generators are your first port of call.
+One is invoked to install the framework's core code.
+Others are invoked as an initial step in developing application modules.
+
+The generators are contained in the gem, *templet_rails*.
+Apart from documentation, this gem contains nothing else of interest,
+and it's only for use in the development environment.
+
+These generators are listed as follows:
+
+```
+$ rails g
+...
+Templet:
+  templet:controller
+  templet:core
+  templet:core_rspec
+  templet:destroy
+  templet:routes
+  templet:rspec
+  templet:scaffold
+  templet:viewer
+...
+```
+
+> *Troubleshooting tip.* If you're unable to see these generators as listed,
+> from the command-line, try this: `$ mkdir lib/generators`.
+
+### Framework Installation
+
+The first generator to run is *templet:core*,
+which copies the complete source code of the framework into
+your local file system - once and for all.
+
+To install the framework, from the command line, key in:
+
+````
+$ rails generator templet:core
+````
+
+#### Testing the Framework Internally
+
+If you wish to add some tests for the framework itself,
+then you can run the generator *templet:core_rspec*.
+This generator copies files into your *spec/helpers/* directory tree,
+(inside the sub-directories: *app/* and *templet/*).
+
+This part is best left out at first, as it adds clutter,
+slowing down your test suite without any real pay back.
+However, if you modify the framework for yourself
+then these tests may be useful.
+
+#### Deinstallation
+
+If you decide to remove the framework,
+you can run the generator *templet:destroy*.
+This deletes __all__ associated files, apart from the controllers.
+You do this with:
+
+```
+$ rails generator templet:destroy --all
+```
+
+### Generating Application Code
+
+The remaining generators are for use when
+you begin to write your own application modules.
+
+But prior to using these generators, you need a model already in place,
+which you can create using the standard Rails (model) generator.
+
+These generators replace Rails' controller and view generators,
+with which they have a lot in common.
+That is, they provide basic REST functionality,
+(i.e. a data-base administration interface),
+that should run without error straight off,
+and is ready for you to change.
+
+#### Scaffold Generator
+
+The quickest way to start is by using the *templet:scaffold* generator,
+which creates the following:
+
+1. A controller that is similar to a regular REST controller, which:
+   * Handles the HTTP request formats: HTML, JS &amp; JSON
+   * Can be namespaced, i.e. nested within a Ruby module
+   * Allows you to restrict the supported REST actions
+   * Allows you to declare a parent (and grand-parent)
+     for the main model, which can have any name you like
+
+2. A *Viewer* subclass that renders all of the HTML
+   for each controller action.
+   It's usually generated with little in its body,
+   as it's for you to change.
+
+3. Some Rspec tests for the controller and *Viewer* classes.
+
+4. REST routing entries, which are written to *config/routes.rb*.
+
+In turn, it runs the four generators:
+
+1. templet:controller
+3. templet:viewer
+2. templet:rspec
+4. templet:routes
+
+Each of these generators can be invoked singly,
+which is useful, if, say, you don't want Rspec tests installed.
+
+#### Generator Remarks
+
+There are several options available which let you specify the names of
+controllers, models, installation directories, etc..
+For full information on usage, call any of them with the *--help* option.
+For example, `rails g templet:core --help`
+The scaffold generator lists all of the options concerned with
+producing application code.
+
+Like in Rails, the generators only provide support for REST functionality.
+If your requirements diverge from this,
+and you're forced to write code from scratch,
+then these generators probably won't be a great deal of use.
+_In such cases, you should find the framework no more difficult
+to code in than traditional view scripts - and maybe it'll be easier._
+
+> Once you're over and done with the generators, you can remove this gem.
+> Note that the other gem, *templet*, is a run-time dependency,
+> so needs to be present in all environments.
+
+<a name="notes"></a> 
+## Notes
+
+This part recaps some of what was said before, but in a bit more depth.
+
+### Overall (Onion) Structure
+
+The framework has a strict hierarchy,
+in which the higher layers depend on those below.
+Starting at the bottom, there are the four layers:
+
+1. A bare-boned DSL that renders markup tags. You pass in a number of
+   method look-up contexts into this API,
+   as well as local variables.
+
+2. Support for components (as Ruby classes) that render
+   (encapsulated) view segments.
+
+3. A Rails-like micro-framework that stands in for the usual
+   view handling mechanism, (i.e. ERb scripts),
+   providing default functionality, ready to be changed.
+
+4. A Rails scaffolding substitute, that generates a REST administrative
+   interface. This includes a controller and a *Viewer* class.
+
+This is a rather abstract refined description -
+so don't linger as more concrete details come next.
+
+### The Framework
+
+#### Prerequisites
+
+At run-time, the framework has a single dependent gem, *templet*.
+
+For testing, it requires *rspec*, *nokogiri* and *factory_bot*.
+And it needs *factory_bot* factories for the models being tested.
+
+#### Framework Code Locations
+
+The core code, which is installed by the generator, *templet:core*,
+is placed in two directories:
+
+1. In *app/helpers/templet/*, which is a tree (of several branches)
+   that contains the bulk of the code.
+   It contains the run-time framework and libraries.
+   _Incidentally, there is a generator option to relocate this directory._
+
+2. In *app/controllers/templet/*, which contains a few controller modules
+   of helper methods that simplify the process of invoking the view.
+
+Also, there are another two files, *app/helpers/templet_helper.rb*
+and *app/helpers/app.rb*, which, for now, can be safely deleted.
+They are reserved for global settings, the former for the framework,
+the latter for the application.
+
+### Writing Applications
+
+As usual, it's assumed that your applications will, for the most part,
+be made up of a series of REST interfaces,
+which have one or more models that are fetched from a data-base.
+
+If your requirements don't square with this methodology,
+then the framework may only be of limited assistance,
+but this much is also true of Rails.
+
+#### Application Code Locations
+
+In addition to the core code, (mentioned in the preceding section),
+the generator, *templet:core*, also creates another directory tree
+for view-specific application code.
+
+The generator installs a skeletal application area,
+(under the directory, *app/helpers/app/*),
+which is where your own application code goes.
+_At present, relocating this directory might cause issues._
+
+The generator also installs (in this area) some place-holder
+classes for the HTML layouts and REST link menus.
+These are put in the two sub-directories, *panel/* and *link_sets/*.
+The code placed here is only a suggestion to give you an idea
+of how the various elements fit together.
+
+> By the way, no files are needed in the view's usual directory tree,
+> i.e. *app/views/*, except mailers, of course.
+> Nor are (the Rails generated) Helper modules needed,
+> but their base directory (*app/helpers/*) is still used.
+
+#### Application Modules
+
+As said, to hook into the framework, 
+you build individual application modules with a *Controller* and,
+nearly always, a *Viewer* class.
+As said, both of these can be generated.
+
+#### The Controller
+
+The controller is put in its usual directory and will look familiar.
+It carries out its usual tasks in the usual way - for example,
+you still apply filters and define instance variables for use in the view.
+The only substantial difference is in the view dispatching.
+
+For brevity, helper methods are provided that reduce the
+view dispatching to a line, or two, of code.
+
+#### Invoking the View from the Controller
+
+To render a view, the controller calls a method
+on an instance of a *Viewer* class,
+which, by convention, shares the name of the controller's calling method.
+
+To save you from having to construct (and execute)
+a *Viewer* class explicitly,
+there are several controller helper methods,
+(kept in Ruby modules in *app/controllers/templet/*),
+that simplify the process of dealing with this *Viewer* class,
+which can, sometimes, require a fair few input parameters.
+
+These helper methods cater for the output formats: *html, js &amp; json*.
+And should be useful if you write controller code by hand.
+
+The *Viewer* is actually called from the controller's
+built-in *render* helper method, as an *inline* template.
+Eventually, it's a line of code (in the controller) resembling something
+like: `render inline: 'ViewerClass.new.index'`.
+
+However, in the current implementation,
+this *inline* template does not call the *Viewer* class directly,
+but instead uses the bridging class, *ViewerCallString*.
+This class compiles a string of executable Ruby that makes the
+actual call to the *Viewer* that fires up the view rendering.
+This round about path is taken so to pass in (implicitly)
+various variables for accessing within the view context.
+_This source of this class, *ViewerCallString* is quite well documented._
+
+#### The Viewer Class
+
+This class, which is placed under the directory, *app/helpers/app/*,
+(or sub-directory thereof),
+performs the functions of the usual view templates, such as ERb scripts.
+It renders the entire HTML page for each appropriate controller action.
+
+It inherits from a few superclasses,
+(e.g. *Templet::ViewerRest*),
+that provide very basic behaviour that you'll,
+inevitably, need to extend or replace.
+You can do this at any granularity.
+
+* For small changes, like specifying the fields
+  to display on the *index* or *show* pages.
+
+* For medium-sized changes, like adding pagination, images,
+  supplementary (contextual) text, link sets, etc..
+
+* For very large changes, like writing all of the HTML yourself or
+  calling ERb templates (via the built-in view helper method *render*).
+
+Broadly speaking, such changes are made by overriding methods.
+
+The superclass naming convention, where you append the substring *Viewer*
+onto a singular declension of the controller's (camel-cased) name,
+saves you from having to explicitly state
+the fully qualified class name when you call instances
+of this *Viewer* class from the controller.
+For example, this (derived) class may be called something
+like *App::UserViewer* or,
+if it's namespaced, *App::Admin::UserViewer*.
+
+#### The Viewer Subclass
+
+As said, the *Viewer* class inherits from a number of superclasses.
+These are: *App::BaseViewer*, (for site-wide settings), which inherits
+a non-abstract base class, *Templet::ViewerRest*,
+which itself inherits from the abstract class, *Templet::ViewerBase*.
+
+The purpose of these subclasses are to render markup (HTML)
+for each of the relevant controller actions.
+To expedite this, it has the following functionality:
+
+1. Handles shared layouts, which can be varied per controller,
+   via the *Viewer*.
+
+2. Provides ready access to the underlying API.
+
+3. Exposes a number of named data items for use in the view.
+   Most of these are set up in the call from the controller.
+
+In very simple cases, you can use an instance
+of *Templet::ViewerRest*, or *App::BaseViewer*, directly,
+whereupon a REST interface should still be fully operational.
+_Your own subclasses let you deviate from the *no-frills* functionality._
+
+#### HTML Layouts
+
+As in Rails, you can specify layouts which are used by all
+(or a circumscribed group of) controllers.
+
+But in this framework there are two layouts, an inner and outer.
+
+These are specified by class names returned by the *Viewer*
+instance methods, *layout_class* and *panel_class*.
+The former is for the outer layout, the latter for the inner.
+
+##### The Outer Layout
+
+This is equivalent to the layout that comes with Rails.
+It contains everything except for the HTML *body* tag,
+that is, it fills in the *head* tag,
+pulling in assets, such as the *Bootstrap* CSS and JS libraries.
+
+This layout is specified in a class kept inside of the framework's
+directory tree, namely, *app/helpers/templet/layouts/html.rb*
+If you want to use something else instead,
+you should put a new version in your application area.
+
+If the HTTP request is for the JS output format (i.e. remote, AJAX)
+then this (outer) layout is omitted - as you'd expect!
+
+##### The Inner Layout
+
+As said, you can also specify a further inner layout,
+(that is rendered within the *body* HTML tag),
+which allows you to display supplementary markup,
+like menus and headings.
+
+These layout classes are found in the directory, *app/helpers/app/panel/*.
+
+As noted, you'll want to change this inner layout,
+as it generated for you with pre-written sample code,
+intended to be illustrative.
+
+This sample code is nested via inheritance chains,
+whose participant classes have names that are prefixed with *Layout*.
+
+In this directory, there are also sample classes,
+suffixed with *Option*,
+that provide custom functionality for various page sections.
+They are set up in the class, *OptionsConfig*.
+You may possibly adopt this pattern in your own code,
+or just get shot of it.
+
+#### REST Link Menus
+
+There are general-purpose classes to render lists of HTML links that
+point to actions in REST controllers, e.g. index, show &amp; edit.
+These classes are in the directory, *app/helpers/templet/links/*.
+
+They are for use with any type of *ActiveRecord* model,
+combined with, if need be, a model's parent and grand-parent.
+And even a dependent's name, (i.e. a model's children),
+which is used to dispay a forward HTML link.
+
+There are, primarily, two template classes
+that render a list of HTML links for REST actions.
+These two are *Templet::Links::BsLinkSetNavigation*
+and *Templet::Links::BsLinkSetCollection*.
+The former is given a model *instance* (for the actions: edit show etc.),
+the latter is given a model's *name* (for the actions: index new etc.).
+
+You can add arbitrary links (at certain spots) to these lists of HTML links
+by subclassing one of the two above classes.
+
+These classes inherit from *Templet::Links::BsLinkSetBase*,
+which have utility methods to render individual HTML links.
+
+The directory, *app/helpers/app/link_sets/*, is reserved for
+your own classes that render HTML link menus.
+Your own classes should inherit from one of the three classes above.
+
+The (list of) links can be presented in HTML containers,
+such as the various *Bootstrap* Button Groups and Navbars.
+There are some factories (in *app/helpers/templet/utils/*)
+that do this for you.
+
+This part has, perhaps, the most intricate functionality,
+and is best learned by looking at sample code in the example app,
+[questionable](https://github.com/srycyk/questionable).
+
+> Do note that this example app has many other examples of API usage,
+> and is complementary to this guide,
+> as it has the examples that are absent here.
+
+#### HTML Components
+
+The API has utility mixin methods to render the standard
+HTML lists and tables - to which CSS class names can be passed.
+
+1. The lists (HTML tag *ul*) take as input a Ruby Array of list items.
+
+2. The tables take as input a Ruby Hash, where the key is the heading,
+   and the value is, usually, a Ruby Proc, to which individual models
+   are passed, taken one-by-one from a given Array of models.
+
+2. Definition (HTML tag *dl*) lists take as input
+   a similar kind of Hash as the tables (i.e. item *2*).
+   If this Hash has lambdas as values,
+   a single model should be passed to this method as well.
+
+There are other API facilities including:
+
+1. Mixin methods to render Bootstrap components,
+   e.g. for the grid system and button groups.
+
+2. Mixin methods that return various lambdas
+   that are used by the generic components.
+   A model instance is often passed to these lambdas.
+
+3. Classes to let you render HTML input forms in a short block of code.
+   The outputted HTML will be adorned with Bootstrap's regalia,
+   i.e. in a *form-group*, with optional help text, etc..
+   The main HTML input types are supported.
+
+4. Classes to render composite view segments, like a search form.
+
+These facilities are in sub-directories below *app/helpers/templet/*,
+and are *mixins/ (1 &amp; 2)*, *forms/ (2)*, and *utils/ (3)*.
+
+### System Variables
+
+Within the viewer class there are a number of objects made available
+that you can reference in your own custom view code.
+
+The principal object is *renderer*, and is used to render markup using
+the DSL that is mentioned many times above.
+This object is an instance of *Templet::Renderer* (in the gem *templet*),
+and can be used in two ways:
+
+  1. To render HTML snippets by means of its *call* method,
+     to which a block is passed, as in:
+     `renderer.call { span 'Goodbye cruel world' }`.
+
+  2. Directly, as in `renderer.root_path`. but this has limited usefulness.
+
+For REST controllers there are the objects *model*, *parent*, and
+perhaps *grand\_parent*, as well as a few others.
+These are used for generic components,
+such as REST link menus and headings.
+
+If you prefer more natural names than *model* or *parent*,
+(or if you require extra input for the view),
+you can define instance variables in the controller
+and then pass their names into the *Viewer* class,
+whereupon they will become accessible (by name) in the view code.
+
+### Configuration
+
+The example application,
+[questionable](https://github.com/srycyk/questionable),
+has all of these configuration settings in place,
+so may be worth looking at if anything goes wrong in your app.
+
+#### Adding Gems
+
+There are two necessary lines to add to your *Gemfile*:
+
+```
+  gem 'templet', git: 'https://github.com/srycyk/templet'
+
+  gem 'templet_rails', git: 'https://github.com/srycyk/templet_rails', group: :development
+```
+
+You can, instead, leave the *git* address out,
+and fetch the gems in the usual way, i.e. from *rubygems.org*.
+Fetching from *github*, however, will give you the most recent version.
+
+In addition, there are following gems:
+
+```
+  gem 'bootstrap-sass', '~> 3.3.7'
+
+  group :development, :test do
+    gem 'factory_bot_rails'
+  end
+
+  # These are optional
+  gem 'sqlite3' # or some other DB gem
+  gem 'kaminari' # if you want to use paging
+```
+
+#### Rspec Support
+
+If running tests, add these lines to *spec/spec_helper.rb*:
+
+```
+require 'factory_bot'
+
+Dir["./spec/support/**/*.rb"].each {|file| require file }
+```
+
+The testing suites require that you have *factory\_bot* factories
+set up for the models that are to be the subject of the tests.
+
+The framework installation will add a number of configuration files
+in *spec/support/apis/* and *spec/support/templet/*.
+
+## Licence
+
+The gem is available as open source under the terms
+of the [MIT License](https://opensource.org/licenses/MIT).
+
+### Contact
+
+If you have any queries or suggestions,
+mail me at stephen.rycyk@googlemail.com
+
+### To Do
+
+1. Upgrade support for installing a new version of the framework,
+   without affecting application code.
+2. Add two global config files for handling variation.
+   One for the framework, another for the application.
+3. Allow more flexibility about where the directory trees are to be located.
+4. Remove all files to do with Rspec support unless this is explicitly requested.
+5. Add support for mailer templates, so that HTML and plain-text formatted
+   mails are both rendered from a single source of text.
+6. Refactor the classes producing REST link menus.