Package com.terminalfour.publish.handlebars.helper.content.element

Class ScaleHandlebarsHelper

  • All Implemented Interfaces:
    com.github.jknack.handlebars.Helper<Object>
    @Component
public class ScaleHandlebarsHelper
extends BaseHelper
    The {{#scale ...}} handlebars helper should be used to created scaled instances of images during publish.

    Usage

    The scale handlebars helper can be used as either a standard expression or a block level expression.

    Attributes

    There are a number of attributes that can be set on the scale helper.

    • element - The Content Element that contains the image to be scaled.
    • max-width - This is the maximum width, in pixels, of the scaled image.
    • max-height - This is the maximum height, in pixels, of the scaled image.
    • client-scaling - This allows the developer to flag that the image should not be scaled during publish. It is most useful when using a block expression, as outlined below.
    • debug - This can be of use with standard expressions, as outlined below.

    Standard expression

    When used as a standard expression, the helper returns the path to the published scaled image.

    Error handling

    If image scaling fails this helper returns a blank string by default. To get more information about the error, the debug attribute should be set to true. In this case, the helper will return the generated error string instead of a blank string.

    Example
      <img src="{{scale element="Content Element" max-width="640" max-height="480"}}" alt="{{publish element="Description"}}" />

    Block expression

    Using a block expression gives the developer much more control over the generated output.

    In order to provide the developer with more control, the helper returns three variables that can be accessed as handlebars expressions within the block.

    • path - This is the path (URL) to which the scaled image has been published. It should be noted that if client-scaling was specified, the image will not have been scaled during publish.
    • width - This is the scaled width of the image, based solely on the original dimensions and the max-width and max-height expression attributes.
    • height - This is the scaled height of the image, based solely on the original dimensions and the max-width and max-height expression attributes.
    Error handling

    Finally, in order to assist with image scaling issues, on an error being encountered during image scaling, a separate block will be processed, if provided. This secondary block provides only a single variable.

    • error - This contains the generated error message and should assist with debugging.
    Example
      {{#scale element="Content Element" max-width="640" max-height="480"}}
    <img
      src="{{path}}"
      style="width: {{width}}px; height: {{height}}px;"
      width="{{width}}"
      height="{{height}}"
      alt="{{#ifSet element="Description"}}{{publish element="Description"}}{{else}}Name: {{publish element="Name"}}{{/ifSet}}" />
  {{else}}
    {{#if (preview)}}
      <div class="pError">Error: {{error}}</div>
    {{/if}}
  {{/scale}}

    • Constructor Detail

      • ScaleHandlebarsHelper

        public ScaleHandlebarsHelper()

    • Method Detail

      • apply

        public Object apply​(Object context,
                    com.github.jknack.handlebars.Options options)
             throws IOException
        Description copied from class: BaseHelper
        The apply method is the main entry point for handlebars.java helpers.

        It is called internally by the handlebars.java engine when a matching handlebars.java expression is encountered.

        Specified by:
        apply in interface com.github.jknack.handlebars.Helper<Object>
        Specified by:
        apply in class BaseHelper
        Parameters:
        context - The currently executing context.
        options - The options.
        Returns:
        The generated output.
        Throws:
        IOException - If processing of the expressions fails.