Trim the ERB backend down to a handful of examples #118
Comments
|
👍 |
|
Make a strong point in the README that we recommend using slim templates over ERB templates for anyone that is considering creating a set of custom templates. We should point out that ERB is complex and that, in our experience, the templates were exceptionally hard to maintain when done in ERB. In contrast, the templates are simple and clear when done in Slim and we have convenient facilities for simplifying the templates further with utility methods. Slim is a smarter engineering choice. To choose ERB is to choose a technology that is knowingly more expensive and tedious to maintain. |
pyokagan
added a commit
to pyokagan/addressbook-level4
that referenced
this issue
Jul 1, 2018
We are trying to implement a navigation bar in the SE-EDU website using asciidoctor's template mechanism[1]. Asciidoctor's template mechanism works by allowing template developers to override the rendering of certain blocks in asciidoctor's syntax tree. For our case, if we want to add a navigation bar to the top of the page, we will need to override asciidoctor's `document` block handling. The problem is: the document block itself is quite coarse -- covering everything from the header <meta> and <script> tags to the footer's "last updated" text. If we just want to add a navigation bar without changing the rest of the document's output, we will need to re-implement a large part of asciidoctor's HTML5 backend. Fortunately, the asciidoctor-backends[1] repository has done most of the hard work for us -- it features complete re-implementation of templates that mirror asciidoctor's default HTML5 output. By using these templates as a base, we can then make minimal changes on top to get our navigation bar. The asciidoctor-backends repo has templates for three different template engines: ERB, HAML and Slim. All three template engines are supported by the asciidoctor Gradle plugin, since AsciidoctorJ[2] bundles them inside its JAR file. Following the recommendation of asciidoctor's project lead[3], let's use the Slim backend. Import the necessary template files, contain within the slim/html5/ directory, from the latest commit (8ffcad1f9194fe2638f673aea7e41ed28c654800) of the asciidoctor-backends repo. Since we only need to modify the handling of the `document` block, we just need to import `document.html.slim`, as well as its dependencies. [1] https://asciidoctor.org/docs/user-manual/#provide-custom-templates [2] https://github.com/asciidoctor/asciidoctorj#project-layout "Also bundles optional RubyGems needed at runtime, such as coderay, tile, haml and slim." [3] asciidoctor/asciidoctor-backends#118 (comment) "We should point out that ERB is complex and that, in our experience, the templates were exceptionally hard to maintain when done in ERB. In contrast, the templates are simple and clear when done in Slim and we have convenient facilities for simplifying the templates further with utility methods. Slim is a smarter engineering choice."
pyokagan
added a commit
to pyokagan/addressbook-level4
that referenced
this issue
Jul 2, 2018
We are trying to implement a navigation bar in the SE-EDU website using asciidoctor's template mechanism[1]. Asciidoctor's template mechanism works by allowing template developers to override the rendering of certain blocks in asciidoctor's syntax tree. For our case, if we want to add a navigation bar to the top of the page, we will need to override asciidoctor's `document` block handling. The problem is: the document block itself is quite coarse -- covering everything from the header <meta> and <script> tags to the footer's "last updated" text. If we just want to add a navigation bar without changing the rest of the document's output, we will need to re-implement a large part of asciidoctor's HTML5 backend. Fortunately, the asciidoctor-backends[2] repository has done most of the hard work for us -- it features complete re-implementation of templates that mirror asciidoctor's default HTML5 output. By using these templates as a base, we can then make minimal changes on top to get our navigation bar. The asciidoctor-backends repo has templates for three different template engines: ERB, HAML and Slim. All three template engines are supported by the asciidoctor Gradle plugin, since AsciidoctorJ bundles them inside its JAR file[3]. Following the recommendation of asciidoctor's project lead[4], let's use the Slim backend. Import the necessary template files, contain within the slim/html5/ directory, from the latest commit (8ffcad1f9194fe2638f673aea7e41ed28c654800) of the asciidoctor-backends repo. Since we only need to modify the handling of the `document` block, we just need to import `document.html.slim`, as well as its dependencies. [1] https://asciidoctor.org/docs/user-manual/#provide-custom-templates [2] https://github.com/asciidoctor/asciidoctor-backends [3] https://github.com/asciidoctor/asciidoctorj#project-layout "Also bundles optional RubyGems needed at runtime, such as coderay, tile, haml and slim." [4] asciidoctor/asciidoctor-backends#118 (comment) "We should point out that ERB is complex and that, in our experience, the templates were exceptionally hard to maintain when done in ERB. In contrast, the templates are simple and clear when done in Slim and we have convenient facilities for simplifying the templates further with utility methods. Slim is a smarter engineering choice."
pyokagan
added a commit
to pyokagan/addressbook-level4
that referenced
this issue
Jul 4, 2018
We are trying to implement a navigation bar in the SE-EDU website using asciidoctor's template mechanism[1]. Asciidoctor's template mechanism works by allowing template developers to override the rendering of certain blocks in asciidoctor's syntax tree. For our case, if we want to add a navigation bar to the top of the page, we will need to override asciidoctor's `document` block handling. The problem is: the rendering logic for the document block itself is quite coarse -- covering everything from the header <meta> and <script> tags to the footer's "last updated" text. If we just want to add a navigation bar without changing the rest of the document's output, we will need to re-implement a large part of asciidoctor's HTML5 backend. Fortunately, the asciidoctor-backends[2] repository has done most of the hard work for us -- it features complete re-implementation of templates that mirror asciidoctor's default HTML5 output. By using these templates as a base, we can then make minimal changes on top to get our navigation bar. The asciidoctor-backends repo has templates for three different template engines: ERB, HAML and Slim. All three template engines are supported by the asciidoctor Gradle plugin, since AsciidoctorJ bundles them inside its JAR file[3]. Following the recommendation of asciidoctor's project lead[4], let's use the Slim backend. Import the necessary template files, contained within the slim/html5/ directory, from the latest commit (8ffcad1f9194fe2638f673aea7e41ed28c654800) of the asciidoctor-backends repo. Since we only need to modify the handling of the `document` block, we just need to import `document.html.slim`, as well as its dependencies. [1] https://asciidoctor.org/docs/user-manual/#provide-custom-templates [2] https://github.com/asciidoctor/asciidoctor-backends [3] https://github.com/asciidoctor/asciidoctorj#project-layout "Also bundles optional RubyGems needed at runtime, such as coderay, tile, haml and slim." [4] asciidoctor/asciidoctor-backends#118 (comment) "We should point out that ERB is complex and that, in our experience, the templates were exceptionally hard to maintain when done in ERB. In contrast, the templates are simple and clear when done in Slim and we have convenient facilities for simplifying the templates further with utility methods. Slim is a smarter engineering choice."
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
The ERB backend is exceptionally difficult to maintain because ERB templates are very complex. In order to ensure we are providing a sufficient reference that is well-maintained and tested, I propose that we trim the ERB backend down to a handful of templates (perhaps 3; one block, one inline and perhaps section) so they merely demonstrate the possibility of using ERB without the maintenance overhead (i.e., nightmare).
The text was updated successfully, but these errors were encountered: