Velocity
  1. Velocity
  2. VELOCITY-174

For consideration: #define()...#end directive to define a block of VTL as a reference

    Details

    • Type: Improvement Improvement
    • Status: Resolved
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 1.3.1
    • Fix Version/s: 1.6
    • Component/s: Engine
    • Labels:
      None
    • Environment:
      Operating System: All
      Platform: All

      Description

      • Proposal:

      #define( $block_ref )

        1. any VTL / text content here
          ...
          #end

      then you can use it like a reference:
      <html><body> $!block_ref </body></html> / #if( $block_ref ).. #end / and so on

      • Justification:

      1. Allows template designer to use a more efficient inside -> out approach
      (similar to Nathan's VelocityLayoutServlet)
      2. Keeps macro framework separate (the app developer can still disallow inline
      macros)
      3. #macros to return blocks of VTL cannot be used like silent references or in
      other directives (like #if)
      4. The multi-line #set proposal requires a quoted value. A #define() block can
      contain anything (without the need to escape quotes for example).
      5. #define() blocks are proxied (like #macros) and thus change according to the
      context after they are defined, something a normal $reference or #set can't do.
      7. Can improve template management by reducing number of unique template components
      8. Can improve template security/errors by reducing the need for bottom tier
      template makers to worry about generic layout code and visa-versa.
      9. Merges the strengths of #macros and $references = best of both worlds

      • Usage Example: Custom HTML forms:

      template 1. : document_type_1_custom_form_body.vm


      #define( $custom_form_body )

        1. unique form fields here

      #end
      #parse("main_form_layout.vm")


      template 2 : main_form_layout.vm


      #define( $custom_page_body )
      <form>

        1. common form fields here

      $!custom_form_body

      <input type="submit" value="submit">
      </form>

      #end
      #parse("main_page_layout.vm")


      template 2 : main_page_layout.vm


      <html><body>

        1. common page layout html here
          $!custom_page_body

      </body></html>


      If the #define() directive was not available a template designer would need to
      do this:

      template 1. : document_type_1_custom_form_body.vm


      #parse("main_page_layout_header.vm")
      #parse("main_form_layout_header.vm")

        1. unique form fields here
          #parse("main_form_layout_header.vm")
          #parse("main_page_layout_header.vm")

      Not only is the same output achieved with fewer #parse() directives (3 v 5), the
      unique templates are fewer and easier to manage. Template designers can make
      many document_type_X templates and need only to define the reference
      $custom_form_body and not worry about the overall page layout. Custom parts of
      the page are also only optionally required now; the main template can test for a
      reference and display a default block if it isn't defined.

      1. Extends.java
        6 kB
        bruce sherrod
      2. ASF.LICENSE.NOT.GRANTED--Define.java
        4 kB
        Andrew Tetlaw

        Issue Links

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              Andrew Tetlaw
            • Votes:
              2 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development