templet_rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e7deaf8989e6c551f2a2a43643b4a9cf0cc869f6
-  data.tar.gz: d36afba37dfd38b61d462d812df24ec821413265
+SHA256:
+  metadata.gz: ef2754d432745180b4320ecd6fd27b4b947e704387735db7f4453dc0153649d4
+  data.tar.gz: 49fd8a805cb8199ae055964ada2ebdaa28d6d0e7f7cd12dcea4a1e661dcf3093
 SHA512:
-  metadata.gz: f717307ac491b39041177dcaa47bc3939e7bfa746829759f77a2963ac1a58263a521fca4e7a537e482fa3f7278b7d4526afe18bec17490681978f1414f8fd4e9
-  data.tar.gz: 5144a6c2c625b587c55c263a42943503f6c1ac01ced1220aa833aa6c6fca5129a936c6fab38c14c7c9b7668b23cbedc70d926e5ef169ca89d982822dcbe3cab3
+  metadata.gz: 7b827e845ac901d87db748e74ccdfdb732dff07225215bb8548485f8d7c51950950debfe917a6e30ea52cdfe37ce0f0c3c6e97331d8cb743d33a6caa4f62b67c
+  data.tar.gz: d72cbd74415bf74e347ad562211eb96c0417469094f6a5823c5f60489635ffb53be7f14919eff310f6855c465bbad650024318d6e736f836520b83271148a351

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 
+
+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

@@ -1,4 +1,4 @@
-# Templet
+# Templet Rails
 
 ## Sections
 
@@ -24,20 +24,23 @@ a wider summary.
 
 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 replaces ERb (HAML, etc.) scripts with pure Ruby classes
+that, by default, render (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.
+This facilitates a more object oriented approach to writing view code,
+yet the framework retains compatibility with
+Rails' 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.
+it shouldn't take you too much effort to learn this framework.
+Its underlying API is not large or complicated,
+and you can have a REST interface up and running
+as quickly as you can with Rails' scaffold generators.
 
 ### Example Application
 
 To learn it practically, there is an example Rails app,
-[questionable](https://github.com/srycyk/questionable),
+[templet_demo](https://github.com/srycyk/templet_demo),
 which is a small administrative front-end of just three models.
 
 This small app has lots of examples that illustrate
@@ -55,22 +58,23 @@ 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,
+it does explain why you may want to use the framework,
 where you begin,
 how it works,
 what it contains,
-and its internal organisation.
+as well as outlining its internal organisation.
 
-In addition, there is another guide found at,
+In addition, there is another guide, to be found at
 [templet](https://github.com/srycyk/templet),
-that describes the DSL that renders HTML tags.
+which 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.
+that you may only need a passing acquaintance with its documentation.
 _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,
+For devoted punishment gluttons, there is yet more to read -
+the source code carries comments
 and the purpose of each class is spelled out.
 
 <a name="intro"></a> 
@@ -86,9 +90,11 @@ and
 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.
+is a framework (packaged as a Rails Engine)
+that has similar functionality to
+the Rails scaffold generator.
+It is just as easy to get working and to change,
+but it is, arguably, more modular and concise.
 
 > Naturally, these gems need to be declared in your *Gemfile*.
 > Please see the *Configuration* section below for further details.
@@ -100,7 +106,7 @@ 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,
+The framework follows many of Rails' (naming) conventions,
 notably it provides default behaviour
 that can be easily overridden or supplanted.
 
@@ -108,12 +114,12 @@ that can be easily overridden or supplanted.
 
 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.
+which are essentially a single stretch of in-line code
+that can quickly become long and repetitive.
 
-The framework promotes productivity
+This framework promotes productivity
 as the views can be written in idiomatic Ruby,
-thus allowing more standardisation, concision and encapsulation.
+thus allowing more standardisation, reuse 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!
@@ -121,8 +127,9 @@ 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.
+An installation involves issuing a few commands,
+and, almost certainly,
+it will cause no conflicts with other packages.
 Likewise, a de-installation is even less trouble.
 
 ### Twitter Bootstrap Dependency
@@ -134,19 +141,20 @@ _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
+But if you don't use Bootstrap, it'll take you some time
 to modify the source to accommodate some other CSS library.
  
 ### Main Sections
 
-The framework introduces the following code divisions:
+The framework is divided into the following parts:
 
-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.
+1. The framework's core code.
+   This is accessed from inside of the *templet_rails* engine.
+   But if you decide to modify this code yourself,
+   there is a generator that will copy it into
+   your application's file system,
 
-2. Application code, consisting of your own
+2. Application code. This consists 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,
@@ -159,12 +167,12 @@ The framework introduces the following code divisions:
 #### Two Basic Steps
 
 To build individual application modules with the framework,
-you create a controller and a *Viewer* class,
+you need to create a Controller and *Viewer* class,
 both of which can be generated.
 
 ##### The Controller
 
-The controller looks pretty much the same as usual,
+A controller will look pretty much the same as usual,
 except for the way the view is invoked.
 
 You render a view by calling, from the controller,
@@ -177,24 +185,27 @@ to launch the view rendering.
 ##### The Viewer
 
 This *Viewer* class carries out all of the HTML rendering,
-letting you diverge from default functionality
+and it lets 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:
+Normally, there is just one of these classes per controller,
+and they have (public) method names in common.
+For example, an *index* method, in the controller,
+calls a counterpart *index* method in the *Viewer* class.
+
+Among other things, this *Viewer* class offers the following features:
 
-1. Adding, or excluding, one or two surrounding Layouts which are
-   shared by a group of pages.
+1. A main surrounding Layout which can be varied,
+   (maybe by inheritance),
+   and also be shared by a specified subset of pages.
+   For JS requests, obviously, it's left out.
 
-2. An ability to use Partials that let you split the whole
-   into discrete parts.
+2. Partials that let you split a whole page into discrete parts.
    Like the Layouts above, they are similar (in intent) to
-   their correlates in Rails, but here they are Ruby subclasses
+   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,
@@ -215,8 +226,8 @@ Among other things, this class offers the following features:
 
 #### Generators
 
-The gem for the framework consists of several generators,
-which are your starting point.
+The gem for the framework consists of several generators.
+These are your starting point in application development.
 
 A few are to do with the installation of the framework,
 and are to be run just once.
@@ -225,7 +236,7 @@ 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,
+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,
@@ -243,18 +254,20 @@ which are mentioned in the *Configuration* section at the end.
 
 ### 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.
+It is a framework, together with associated libraries,
+for rendering views in Rails.
+It provides scaffold-like functionality,
+and it permits you to render markup (HTML) in pure Ruby,
+thereby lending itself to component-based OO paradigms.
 
-The framework is sparse, has few dependencies
-and is not particularly complicated.
+The framework is pretty sparse, has few dependencies,
+and is not difficult to code in.
 
 ### Why use it?
 
 Primarily, it's to boost development efficiency.
 
-But you may also find it more comfortable to code in,
+But you may also find it more comfortable to work with,
 as it gives you more of a free rein than, say, ERb scripts.
 
 #### *It's quick*
@@ -272,24 +285,25 @@ it lets you do so easily and briefly.
 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.
+you're constrained by their in-line procedural methodology.
 
-These scripts often end up being monolithic and painful to maintain.
+These scripts often end up being monolithic and awkward to maintain.
 Code sharing is too verbose,
-as it usually results in a proliferation of tiny files and
+as it can result 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)
+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.
+to produce syntactically correct HTML,
+and to rearrange the various sections of a page.
 
 ### How easy is to learn?
 
@@ -304,14 +318,13 @@ In this framework, you're still able to use the
 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.
+allowing them both to sit alongside one another.
 
 ### 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.
+or you can use it as a library (toolkit) to render view segments.
 
 #### *As a framework*
 
@@ -325,7 +338,7 @@ To use it as a framework there are generally just two classes to create,
 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*.
+   For example, both may have public methods, *index* and *show*.
 
 #### *As a library*
 
@@ -343,38 +356,37 @@ 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).
+which is *Twitter Bootstrap 3.3*, (for HTML styling).
 
 ### 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.
+which are both run-time dependencies.
+The first is a DSL for rendering HTML,
+the second is an engine that is for use with Rails and Bootstrap (3.3),
+that contains the framework's source and several generators.
 
 ### 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/*.
+There's a generator to set this area up.
+
+The framework's source is accessed from
+within the *templet_rails* engine.
+But if you plan to change the source,
+you can use a generator to copy it into your app directly.
 
 ### Is it easy to deinstall?
 
-If you try it out, and then decide to ditch it,
+If you try it out, and then opt 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*.
+and the nearly all of the application files -
+your controllers and entries in *config/routes.rb* are left alone.
 
 ### What does it depend on?
 
@@ -384,7 +396,7 @@ 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
+It's currently for Bootstrap version 3.3, but if you do
 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.
@@ -393,16 +405,21 @@ 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.
+_Not so much in the number of code changes,
+but in tracking them down._
 
 ### Will it be supported?
 
 No guarantee!
 But will you need long-term external support? Probably not.
 
-The code-base so small that taking responsibility
+The code-base is so small that taking responsibility
 for its upkeep should not be too onerous.
 There is little to go wrong.
 
+Dealing with future Ruby and Rails deprecations
+will probably be your biggest risk.
+
 ### Are there tests?
 
 It comes supplied with a rudimentary testing system.
@@ -414,23 +431,25 @@ 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.
+Nonetheless, in their present form,
+they are not a viable substitute for the usual testing suites.
 
 When running the tests, it needs the gems:
 *rspec*, *nokogiri* and *factory_bot*,
-for which (model) factories have already been defined.
+for which (model) factories have previously 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.
+   The framework reduces development time because many modifications
+   can be written in small (centralised) code sections,
+   and more complex modifications can be structured in whatever
+   way you think best.
 
-3. In general, it's for data-base driven sites -
-   not so much for fancy (HTML/JS-heavy) sites
+3. In general, it's for data-base driven (form-filling) sites -
+   not really for fancy (JS-heavy, graphic-laden) sites
    where data is passively consumed.
 
 ### What are its advantages?
@@ -439,33 +458,39 @@ for which (model) factories have already been defined.
    than the conventional Rails ERb rendering.
 
 2. Presentational changes can be made from a single place,
-   and then propagate immediately throughout the whole site.
+   and then they'll 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.
+   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.
+   in separate stand-alone classes with regulated input.
 
 ### What are its disadvantages?
 
 1. The bare Bootstrap styling is characterless,
-   and the HTML will be difficult for designers to modify.
+   and the HTML will be tricky for web designers to modify.
 
-2. The way in which this framework is structured may rub against your
-   existing practices.
+2. The way in which this framework is laid out may
+   rub against your existing practices,
+   which may necessitate so much code reorganisation
+   that adopting the framework won't be worthwhile.
 
 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.
+   become unavailable.
+   Principally these things are: view path look-ups,
+   shortcuts for rendering collections,
+   inferring partial names from instance variables,
+   and an inability to *yield* additional content
+   at arbitrary positions on the page, i.e. *content_for* blocks.
+   _But in practice, this shouldn't be much of a constraint._
+
+4. Caching view segments may be prove harder than usual.
    You should still be able to use Rails' low-level fragment caching,
    but partial caching is impossible.
 
@@ -476,21 +501,21 @@ for which (model) factories have already been defined.
 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.
+   Probably the best way of safeguarding against this is by including
+   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*)
+   (*app/models/concerns/nasty_char_validator.rb*, in *templet_demo*)
    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.
+   in a *before_validation* callback (inside of a model).
 
 ### How does it compare to similar offerings?
 
 Although the following claims do present
-the framework in its *best light*,
-they, nevertheless, hold good, arguably.
+this framework in its *best light*,
+nevertheless, some might say otherwise.
 
 1. It is similar in function to data-base maintenance gems,
    (like *active_admin*),
@@ -508,7 +533,11 @@ they, nevertheless, hold good, arguably.
 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.
+5. The *Viewer* classes, in themselves, have the simplicity of, say,
+   Sinatra scripts, as they permit a number of distinct web pages
+   to be defined in a single file, which is fine in simple cases.
+   But in more complicated cases, you'd write a dedicated class
+   to render the HTML, and you'd invoke it from the *Viewer* class.
 
 <a name="gen"></a> 
 ## Generators
@@ -517,7 +546,7 @@ 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*.
+The generators are contained in the engine, *templet_rails*.
 Apart from documentation, this gem contains nothing else of interest,
 and it's only for use in the development environment.
 
@@ -528,9 +557,10 @@ $ rails g
 ...
 Templet:
   templet:controller
-  templet:core
+  templet:core_install
   templet:core_rspec
   templet:destroy
+  templet:install
   templet:routes
   templet:rspec
   templet:scaffold
@@ -541,57 +571,23 @@ Templet:
 > *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.
+The first generator to run is *templet:install*,
+which prepares an area for putting your 
+application code in - once and for all.
 
-But prior to using these generators, you need a model already in place,
+Prior to using these generators, you need a model already in place,
 which you can create using the standard Rails (model) generator.
 
+#### Scaffold 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
+that should run without error straight off.
+And the code produced is ready for you to customise.
 
 The quickest way to start is by using the *templet:scaffold* generator,
 which creates the following:
@@ -612,7 +608,7 @@ which creates the following:
 
 4. REST routing entries, which are written to *config/routes.rb*.
 
-In turn, it runs the four generators:
+In succession, the scaffold runs the four generators:
 
 1. templet:controller
 3. templet:viewer
@@ -627,20 +623,57 @@ which is useful, if, say, you don't want Rspec tests installed.
 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`
+For example, `rails g templet:install --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
+then the code these generators produce
+probably won't be a great deal of use.
+_In such cases, you should still 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.
+#### Deinstallation
+
+If you decide to remove the framework, and it artefacts,
+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
+```
+
+### Framework Installation
+
+Although it is more convenient to access
+the framework from within the engine, (*templet_rails*), 
+the generator, *templet:core_install*,
+will copy the complete source code of the framework into
+your local file system.
+
+This should only be done if you require
+to alter the framework's source code.
+
+To install the framework from the command line, you key in:
+
+````
+$ rails generator templet:core_install
+````
+
+#### 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, 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.
 
 <a name="notes"></a> 
 ## Notes
@@ -651,95 +684,91 @@ This part recaps some of what was said before, but in a bit more depth.
 
 The framework has a strict hierarchy,
 in which the higher layers depend on those below.
-Starting at the bottom, there are the four layers:
+Starting at the bottom, there are 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.
+   as well as local variables as and when they're required.
 
 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.
+3. A Rails-like micro-framework that stands in for an existing
+   view handling mechanism, e.g. ERb or Haml scripts.
+   The framework provides default functionality
+   that can be readily changed.
 
 4. A Rails scaffolding substitute, that generates a REST administrative
-   interface. This includes a controller and a *Viewer* class.
+   interface. This consists of pairs of Controller and *Viewer* classes.
 
-This is a rather abstract refined description -
+This description, admittedly, is too abstract and refined -
 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:
+At run-time, the framework has two dependent
+gems, *templet* and *templet_rails*
+_The first is a DSL to generate HTML, the second is a Rails Engine._
 
-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._
+For testing, it requires the gems: *rspec*, *nokogiri* and *factory_bot*.
+Also, it needs *factory_bot* factories defined for
+each of the models that are subjects of the tests.
 
-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.
+The testing, however, is optional.
+If you write a comprehensive set of tests yourself,
+the ones that this framework provides will be too superficial.
 
 ### 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.
+As is usual in Rails, it's assumed that your application will,
+for the most part, be made up of a series of REST interfaces,
+which contain models that are mapped to some sort of data-store.
 
 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.
+but this much is also true of Rails itself.
 
 #### Application Code Locations
 
 In addition to the core code, (mentioned in the preceding section),
-the generator, *templet:core*, also creates another directory tree
+the generator, *templet:install*, 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.
+under the directory, *app/helpers/app/*.
+Also, there's a file *app/helpers/app.rb*,
+which is for your own global settings,
+and which you can delete.
+
+Your own application code is to be put here.
 _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.
+These are put in the sub-directory, *layouts/*.
+The code placed here is really only a suggestion,
+so will need editing or, most likely, drastic revision,
+However, its basic structure indicates how application
+modules may be assembled.
 
-> 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.
+> 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.
+> However, the base directory (*app/helpers/*) remains in use.
 
 #### 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.
+As said, both of these classes 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,
+The controller is put in its usual location and will look familiar.
+It carries out its 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.
 
@@ -764,16 +793,17 @@ 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'`.
+Eventually, the call is reduced to line of code resembling:
+`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*.
+but instead uses a 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.
+actual call to the *Viewer*, that initiates the view rendering.
 This round about path is taken so to pass in (implicitly)
-various variables for accessing within the view context.
+a number of variables for accessing within the view context.
 _This source of this class, *ViewerCallString* is quite well documented._
 
 #### The Viewer Class
@@ -781,64 +811,71 @@ _This source of this class, *ViewerCallString* is quite well documented._
 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 renders an 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.
+You can do this at any granularity:
 
-* For small changes, like specifying the fields
-  to display on the *index* or *show* pages.
+1. 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..
+2. For medium-sized changes, like adding pagination, images,
+   supplementary text, contextual variation, 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*).
+3. For big changes, you may siphon off all of the HTML rendering to a
+   separate class, (perhaps inheriting from *Templet::Component::Partial*).
+   Or even, pathologically, resort back to ERb scripts,
+   (in which case, you'd run the script with the Rails-supplied
+   helper method *render*).
 
-Broadly speaking, such changes are made by overriding methods.
+Changes for the first two of these can often be 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 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.
+> An example might make this easier to swallow: this (derived) class
+> should be called something like *App::UserViewer* or,
+> if it's to be 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*.
+which, in turn, 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:
+for each of the corresponding controller actions.
+To expedite this, these superclasses expose the following functions
+that may be made use of when applying your own changes:
 
-1. Handles shared layouts, which can be varied per controller,
-   via the *Viewer*.
+1. Shared layout handling, which can be varied per controller,
+   (or action), via directives in the *Viewer* class.
 
-2. Provides ready access to the underlying API.
+2. 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.
+3. Providing access to a number of named data items for use in the view.
+   Most of these are set up in the call from the controller, like
+   instance variables, literal names and run-time options.
 
 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._
+_Your own subclasses let you deviate from the
+provided *no-frills* functionality._
 
 #### HTML Layouts
 
-As in Rails, you can specify layouts which are used by all
+As in Rails, you can specify a layout that is to be used by all
 (or a circumscribed group of) controllers.
 
-But in this framework there are two layouts, an inner and outer.
+However, in this framework, by default,
+there are two layouts, an outer and inner.
 
 These are specified by class names returned by the *Viewer*
 instance methods, *layout_class* and *panel_class*.
@@ -848,13 +885,13 @@ The former is for the outer layout, the latter for the inner.
 
 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,
+that is, it populates 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.
+This (outer) layout is specified in a class
+kept inside of the framework's directory tree,
+namely, *app/helpers/templet/layouts/html.rb*.
+It is rendered inside the *body* HTML tag.
 
 If the HTTP request is for the JS output format (i.e. remote, AJAX)
 then this (outer) layout is omitted - as you'd expect!
@@ -862,11 +899,11 @@ 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.
+This inner layout is included in JS (AJAX) requests.
 
-These layout classes are found in the directory, *app/helpers/app/panel/*.
+These layout classes are put in the directory, *app/helpers/app/layouts/*.
 
 As noted, you'll want to change this inner layout,
 as it generated for you with pre-written sample code,
@@ -877,10 +914,10 @@ 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.
+that provide custom functionality for the assorted 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.
+or just get rid of it.
 
 #### REST Link Menus
 
@@ -891,14 +928,14 @@ 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.
+which is used to display 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.).
+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.
@@ -906,9 +943,9 @@ 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
+The directory, *app/helpers/app/links/*, is reserved for
 your own classes that render HTML link menus.
-Your own classes should inherit from one of the three classes above.
+Your own classes can 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.
@@ -917,15 +954,15 @@ 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).
+[templet_demo](https://github.com/srycyk/templet_demo).
 
 > 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.
+> as it has lots of examples that are absent in this guide.
 
 #### HTML Components
 
-The API has utility mixin methods to render the standard
+The API has utility mixin methods to render 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.
@@ -946,7 +983,7 @@ There are other API facilities including:
 
 2. Mixin methods that return various lambdas
    that are used by the generic components.
-   A model instance is often passed to these lambdas.
+   A model instance is often passed into 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,
@@ -955,8 +992,8 @@ There are other API facilities including:
 
 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)*.
+> These facilities are in sub-directories below *app/helpers/templet/*,
+> and are *mixins/ (1 &amp; 2)*, *forms/ (2)*, and *utils/ (3)*.
 
 ### System Variables
 
@@ -972,9 +1009,9 @@ and can be used in two ways:
      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.
+  2. Directly, as in `renderer.root_path`. to retrieve single values.
 
-For REST controllers there are the objects *model*, *parent*, and
+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.
@@ -985,10 +1022,37 @@ 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.
 
+### Framework Code
+
+Normally, the framework's source code will be accessed
+from within the *templet_rails* engine.
+
+But if you require to modify the framework's code yourself, 
+you can copy the source into your application file system.
+
+The core code, which can be installed by the
+generator, *templet:core_install*,
+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 is another file, *app/helpers/templet_helper.rb*
+which can be safely deleted.
+It is reserved for global setting for the framework.
+
+If you install the core code locally,
+the engine, *templet_rails*, will no longer be required at run-time.
+
 ### Configuration
 
 The example application,
-[questionable](https://github.com/srycyk/questionable),
+[templet_demo](https://github.com/srycyk/templet_demo),
 has all of these configuration settings in place,
 so may be worth looking at if anything goes wrong in your app.
 
@@ -1003,16 +1067,17 @@ There are two necessary lines to add to your *Gemfile*:
 ```
 
 You can, instead, leave the *git* address out,
-and fetch the gems in the usual way, i.e. from *rubygems.org*.
+and fetch the gems directly from the repository, *rubygems.org*.
 Fetching from *github*, however, will give you the most recent version.
 
 In addition, there are following gems:
 
 ```
+  gem 'jquery-rails'
   gem 'bootstrap-sass', '~> 3.3.7'
 
   group :development, :test do
-    gem 'factory_bot_rails'
+    gem 'factory_bot_rails', '4.10.0'
   end
 
   # These are optional
@@ -1033,7 +1098,7 @@ 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
+Also, the installation will add a number of configuration files
 in *spec/support/apis/* and *spec/support/templet/*.
 
 ## Licence
@@ -1048,12 +1113,12 @@ 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.
+* Allow more flexibility about where the directory trees are to be situated.
+* Make Rspec support more optional. Should it be explicitly requested?
+* Decouple ActiveRecord dependencies.
+* Add support for rendering serialized fields.
+* Make calling the Viewer class from controller less cumbersome.
+* Refactor the classes producing REST link menus.
+* Add support for mailer templates, so that HTML and plain-text formatted
+  mails are both rendered from a single source of text.
+* Support for Bootstrap 4.