Package com.day.cq.wcm.foundation.forms

Class FormsHelper

  • public class FormsHelper
extends java.lang.Object
    Helper class for the forms components.

    • Field Detail

      • REQ_ATTR_GLOBAL_LOAD_MAP

        public static final java.lang.String REQ_ATTR_GLOBAL_LOAD_MAP
        See Also:
        Constant Field Values

      • REQ_ATTR_GLOBAL_LOAD_RESOURCE

        public static final java.lang.String REQ_ATTR_GLOBAL_LOAD_RESOURCE
        See Also:
        Constant Field Values

      • REQ_ATTR_EDIT_RESOURCES

        public static final java.lang.String REQ_ATTR_EDIT_RESOURCES
        See Also:
        Constant Field Values

      • REQ_ATTR_CLIENT_VALIDATION

        public static final java.lang.String REQ_ATTR_CLIENT_VALIDATION
        See Also:
        Constant Field Values

      • REQ_ATTR_WRITTEN_JAVASCRIPT

        public static final java.lang.String REQ_ATTR_WRITTEN_JAVASCRIPT
        See Also:
        Constant Field Values

      • REQ_ATTR_ACTION_SUFFIX

        public static final java.lang.String REQ_ATTR_ACTION_SUFFIX
        See Also:
        Constant Field Values

      • REQ_ATTR_FORWARD_PATH

        public static final java.lang.String REQ_ATTR_FORWARD_PATH
        See Also:
        Constant Field Values

      • REQ_ATTR_FORWARD_OPTIONS

        public static final java.lang.String REQ_ATTR_FORWARD_OPTIONS
        See Also:
        Constant Field Values

      • REQ_ATTR_IS_INIT

        public static final java.lang.String REQ_ATTR_IS_INIT
        See Also:
        Constant Field Values

      • REQ_ATTR_READ_ONLY

        public static final java.lang.String REQ_ATTR_READ_ONLY
        See Also:
        Constant Field Values

      • REQ_ATTR_REDIRECT

        public static final java.lang.String REQ_ATTR_REDIRECT
        See Also:
        Constant Field Values

      • REQ_ATTR_REDIRECT_TO_REFERRER

        public static final java.lang.String REQ_ATTR_REDIRECT_TO_REFERRER

      • REQ_ATTR_PROP_WHITELIST

        public static final java.lang.String REQ_ATTR_PROP_WHITELIST
        See Also:
        Constant Field Values

      • REQ_ATTR_EXPRESSIONS_ENABLED

        public static final java.lang.String REQ_ATTR_EXPRESSIONS_ENABLED
        See Also:
        Constant Field Values

      • REQ_ATTR_FORM_STRUCTURE_HELPER

        public static final java.lang.String REQ_ATTR_FORM_STRUCTURE_HELPER
        See Also:
        Constant Field Values

    • Method Detail

      • runAction

        public static void runAction​(java.lang.String actionType,
                             java.lang.String scriptName,
                             Resource formResource,
                             SlingHttpServletRequest request,
                             SlingHttpServletResponse response)
                      throws java.io.IOException,
                             ServletException
        Runs/includes a script of the form action.
        Parameters:
        actionType - action type
        scriptName - script name
        formResource - resource
        request - request
        response - response
        Throws:
        java.io.IOException - if inclusion caused an error
        ServletException - if inclusion caused an error

      • endForm

        public static void endForm​(SlingHttpServletRequest req)
        Signal the end of the form.
        Parameters:
        req - Request

      • setForwardPath

        public static void setForwardPath​(SlingHttpServletRequest req,
                                  java.lang.String path)
        Set the forward path for processing the form.
        Parameters:
        req - The current request.
        path - The forward path.

      • setForwardPath

        public static void setForwardPath​(SlingHttpServletRequest req,
                                  java.lang.String path,
                                  boolean clearFormSelector)
        Set the forward path for processing the form and makes sure the "form" selector from the form request is cleared upon forwarding. This is usually required if the forward should go to the sling POST servlet, to avoid conflicts with the form chooser.

        This is not required if the forward path already contains an extension and possible selectors, in which case these overwrite the form request selector anyway.

        * This uses setForwardOptions with RequestDispatcherOptions.setReplaceSelectors("").

        Parameters:
        req - The current request.
        path - The forward path.
        clearFormSelector - if the "form" selector should be cleared
        Since:
        5.5

      • getForwardPath

        public static java.lang.String getForwardPath​(SlingHttpServletRequest req)
        Get the forward path for processing the form.
        Parameters:
        req - The current request.
        Returns:
        The forward path or null.

      • setForwardRedirect

        public static void setForwardRedirect​(ServletRequest request,
                                      java.lang.String redirect)
        Sets the Sling POST serlvet's ":redirect" parameter dynamically during the form POST execution, when setForwardPath(SlingHttpServletRequest, String) is used.
        Parameters:
        request - the current request
        redirect - a redirect path/url
        Since:
        5.5

      • getForwardRedirect

        public static java.lang.String getForwardRedirect​(ServletRequest request)
        Returns the redirect to inject as ":redirect" parameter for the Sling POST servlet, when a form forward is done.
        Parameters:
        request - the current request
        Returns:
        redirect path/url
        Since:
        5.5

      • setActionSuffix

        public static void setActionSuffix​(SlingHttpServletRequest req,
                                   java.lang.String suffix)
        Set a request suffix to be added to the form action's URI.
        Parameters:
        req - The current request.
        suffix - The suffix or null.

      • getActionSuffix

        public static java.lang.String getActionSuffix​(SlingHttpServletRequest req)
        Get the request suffix currently set for the form action's URI.
        Parameters:
        req - The current Request.
        Returns:
        THe suffix or null.

      • setFormLoadResource

        public static void setFormLoadResource​(SlingHttpServletRequest req,
                                       Resource rsrc)
        Set the load resource for the form.
        Parameters:
        req - The current request.
        rsrc - The load resource

      • getFormLoadResource

        public static Resource getFormLoadResource​(SlingHttpServletRequest req)
        Get the load resource for the form.
        Parameters:
        req - current request
        Returns:
        load resource or null if not set

      • getGlobalFormValues

        public static ValueMap getGlobalFormValues​(SlingHttpServletRequest req)
        Return the form values to load.
        Parameters:
        req - The request
        Returns:
        The values or null

      • setFormEditResources

        public static void setFormEditResources​(SlingHttpServletRequest req,
                                        java.util.List<Resource> resources)
        Sets the list of resources to be handled by the "edit" resources form action.
        Parameters:
        req - current request
        resources - the list of resources

      • getFormEditResources

        public static java.util.List<Resource> getFormEditResources​(SlingHttpServletRequest req)
        Get the list of resources to be handled by the "edit" resources form action.
        Parameters:
        req - current request
        Returns:
        the list of resources (or null if not set)

      • getFormsPreCheckMethodName

        public static java.lang.String getFormsPreCheckMethodName​(SlingHttpServletRequest req)
        Return the name of the check method. Method name is based on from id with any hyphens converted to underscores. If the form can't be found, it will default to defaultForm.
        Parameters:
        req - The current request.
        Returns:
        The method name

      • includeResource

        public static void includeResource​(SlingHttpServletRequest request,
                                   SlingHttpServletResponse response,
                                   Resource resource,
                                   java.lang.String selectorString)
                            throws java.io.IOException,
                                   ServletException
        Include the resource with the given selector with method GET
        Parameters:
        request - The current request.
        response - The current response.
        resource - The resource to include.
        selectorString - The selector string to use for inclusion.
        Throws:
        java.io.IOException - if requested resource is not accessible
        ServletException - if requested resource is not accessible

      • doClientValidation

        public static boolean doClientValidation​(SlingHttpServletRequest req)
        Are we generating client validation?
        Parameters:
        req - Request
        Returns:
        true or false

      • getFormId

        public static java.lang.String getFormId​(SlingHttpServletRequest req)
        Return the formid
        Parameters:
        req - Request
        Returns:
        The form id or null

      • getParameterName

        public static java.lang.String getParameterName​(Resource rsrc)
        Return the parameter name for the field
        Parameters:
        rsrc - The resource
        Returns:
        The parameter name.

      • getFieldId

        public static java.lang.String getFieldId​(SlingHttpServletRequest req,
                                          Resource rsrc)
        Return the id for the field
        Parameters:
        req - The current request.
        rsrc - The resource.
        Returns:
        The id.

      • getFormElements

        @Deprecated
public static java.util.Iterator<Resource> getFormElements​(Resource formResource)
        Deprecated.
        use FormStructureHelper.getFormElements(Resource) instead.
        Return all form elements for this form.
        Parameters:
        formResource - The form resource-
        Returns:
        An iterator for all form elements.

      • getContentRequestParameterNames

        public static java.util.Iterator<java.lang.String> getContentRequestParameterNames​(SlingHttpServletRequest req)
        Return a list of content fields. This method returns all field names (= request parameter names) that contain actually content by filtering out special request parameters like those starting with a ":", "_charset_" etc.
        Returns:
        Iterator for the field names.

      • getResource

        public static Resource getResource​(SlingHttpServletRequest request,
                                   Resource elementResource,
                                   java.lang.String relPath)
        Returns a resource identified by a path relative to the elementResource. This method also considers form edit resources.
        Parameters:
        request - the current request.
        elementResource - the element resource.
        relPath - a path relative to elementResource.
        Returns:
        the resource or null if none exists at the given relPath.

      • getValue

        public static java.lang.String getValue​(SlingHttpServletRequest request,
                                        Resource elementResource)
        Return the value for the element. This method invokes getValues(SlingHttpServletRequest, Resource) and returns if available the first value from the array.
        Parameters:
        request - The current request.
        elementResource - The element resource.
        Returns:
        The value for the form element or null.

      • getValue

        public static java.lang.String getValue​(SlingHttpServletRequest request,
                                        Resource elementResource,
                                        java.lang.String nameParam)
        Return the value for the element. This method invokes getValues(SlingHttpServletRequest, Resource) and returns if available the first value from the array.
        Parameters:
        request - The current request.
        elementResource - The element resource.
        nameParam - The name of the name parameter (defaults to "name")
        Returns:
        The value for the form element or null.

      • getValues

        public static java.lang.String[] getValues​(SlingHttpServletRequest request,
                                           Resource elementResource)
        Return the values for the element. This method
        Parameters:
        request - The current request.
        elementResource - The element resource.
        Returns:
        The values for the form element or null.

      • getValues

        public static java.lang.String[] getValues​(SlingHttpServletRequest request,
                                           Resource elementResource,
                                           java.lang.String nameParam)
        Return the values for the element. This method
        Parameters:
        request - The current request.
        elementResource - The element resource.
        nameParam - The name of the name parameter (defaults to "name")
        Returns:
        The values for the form element or null.

      • getValuesAsList

        public static java.util.List<java.lang.String> getValuesAsList​(SlingHttpServletRequest request,
                                                               Resource elementResource)
        Return the values for the element as a list This method
        Parameters:
        request - The current request.
        elementResource - The element resource.
        Returns:
        The values for the form element or an empty list.

      • getValue

        public static java.lang.String getValue​(SlingHttpServletRequest request,
                                        java.lang.String name,
                                        java.lang.String defaultValue)
        Returns the value for the given name (property).
        Parameters:
        request - The current request
        name - name of the property (or property path)
        defaultValue - default value to return if property is not present
        Returns:
        The value for the given property

      • getValues

        public static java.lang.String[] getValues​(SlingHttpServletRequest request,
                                           java.lang.String name,
                                           java.lang.String[] defaultValues)
        Returns the values for the given name (property).
        Parameters:
        request - The current request
        name - name of the property (or property path)
        defaultValues - default values to return if property is not present
        Returns:
        The values for the given property

      • inlineValuesAsJson

        public static void inlineValuesAsJson​(SlingHttpServletRequest request,
                                      java.io.Writer out,
                                      java.lang.String path)
                               throws java.io.IOException,
                                      RepositoryException,
                                      JSONException
        Writes the given form load resource as JSON into the given writer. This will dump the full tree; use inlineValuesAsJson(SlingHttpServletRequest, Writer, String, int) for controlling the node depth.

        Can be used in JSPs to inline JSON for javascript code, for example: 

         var data = <% FormsHelper.inlineValuesAsJson(slingRequest, out, "."); %>;
        which might result in: 
         var data = { "jcr:primaryType": "nt:unstructured", "property" : "value" };

        If the path cannot be found, an empty object "{}" will be written. Any exception will be passed to the caller.

        The underlying form load resource must be based on a JCR Node. The path is relative and allows to specify subnodes. It cannot point to JCR properties, please use getValue(SlingHttpServletRequest, String, String) or getValues(SlingHttpServletRequest, String, String[]) for them.

        Parameters:
        request - the current request
        out - a writer, such as a JspWriter, to write the JSON into. Will automatically be flushed before and after.
        path - an absolute node path or a node path relativ to the current form load resource. Use "." for the resource node itself.
        Throws:
        RepositoryException - if some jcr error happened
        JSONException - if writing the json failed
        java.io.IOException - if there was a problem with the writer

      • inlineValuesAsJson

        public static void inlineValuesAsJson​(SlingHttpServletRequest request,
                                      java.io.Writer out,
                                      java.lang.String path,
                                      int nodeDepth)
                               throws java.io.IOException,
                                      RepositoryException,
                                      JSONException
        Writes the given form load resource as JSON into the given writer. Can be used in JSPs to inline JSON for javascript code, for example: 
         var data = <% FormsHelper.inlineValuesAsJson(slingRequest, out, "."); %>;
        which might result in: 
         var data = { "jcr:primaryType": "nt:unstructured", "property" : "value" };

        If the path cannot be found, an empty object "{}" will be written. Any exception will be passed to the caller.

        The underlying form load resource must be based on a JCR Node. The path is relative and allows to specify subnodes. It cannot point to JCR properties, please use getValue(SlingHttpServletRequest, String, String) or getValues(SlingHttpServletRequest, String, String[]) for them.

        Parameters:
        request - the current request
        out - a writer, such as a JspWriter, to write the JSON into. Will automatically be flushed before and after.
        path - an absolute node path or a node path relativ to the current form load resource. Use "." for the resource node itself.
        nodeDepth - until which depth the tree should be written; 0 means the current node and its properties only; -1 means the whole tree.
        Throws:
        RepositoryException - if some jcr error happened
        JSONException - if writing the json failed
        java.io.IOException - if there was a problem with the writer

      • getShowHideExpressions

        public static java.util.Map<java.lang.String,​java.lang.String> getShowHideExpressions​(Resource resource)
                                                                                     throws RepositoryException
        Return a flattened map of all showHideExpressions that are descendants of a resource.
        Parameters:
        resource - the node to check to see if there's any showHideExpressions.
        Returns:
        A map of showHideExpressions keyed by element name.
        Throws:
        RepositoryException - if repository access caused an error

      • getOptions

        public static java.util.Map<java.lang.String,​java.lang.String> getOptions​(SlingHttpServletRequest request,
                                                                                Resource elementResource)
        Return the options for a form element
        Parameters:
        request - request
        elementResource - element
        Returns:
        A map of options (key-value) or null.

      • isRequired

        public static boolean isRequired​(Resource formElement)
        Is this field required?
        Parameters:
        formElement - The form element.
        Returns:
        true if the field is required, false otherwise.

      • isReadOnly

        public static boolean isReadOnly​(SlingHttpServletRequest request,
                                 Resource formElement)
        Returns true if either the passed form field is configured as read-only or if the entire form is to be displayed in a read-only way. The latter is the case when setFormReadOnly(SlingHttpServletRequest) was called, for example if the "view" selector of the FormChooserServlet is used.
        Parameters:
        request - the current request
        formElement - the form field resource
        Returns:
        true if this field is to be rendered as read-only, false otherwise.

      • isReadOnly

        public static boolean isReadOnly​(SlingHttpServletRequest request)
        Returns true if the entire form has to be displayed in a read-only way.
        Parameters:
        request - the current request
        Returns:
        true if a form element has to be rendered as read-only, false otherwise.
        Since:
        5.5

      • isReadOnly

        @Deprecated
public static boolean isReadOnly​(Resource formElement)
        Deprecated.
        To always support the global read-only flag, set for example by the "view" selector of the FormChooserServlet, use isReadOnly(SlingHttpServletRequest, Resource) instead.
        Returns true if the passed form field is configured as read-only. This is determined solely by looking at the field's "readOnly" property.
        Parameters:
        formElement - the form field resource
        Returns:
        true if this field is read-only, false otherwise.

      • checkRule

        public static boolean checkRule​(Resource resource,
                                SlingHttpServletRequest req,
                                PageContext pageContext,
                                java.lang.String propName)

        Checks the rule specified by the given form property.

        Rules may be used to enable/disable form elements according to some serverside conditions.

        Currently, only rules depending on access rights are available.

        Parameters:
        resource - resource
        req - request
        propName - property name
        Returns:
        true if check was successful

      • getTitle

        public static java.lang.String getTitle​(Resource formElement,
                                        java.lang.String defaultTitle)
        Return the title for the field.
        Parameters:
        formElement - The form element.
        defaultTitle - The default title.
        Returns:
        The title to display.

      • getDescription

        public static java.lang.String getDescription​(Resource formElement,
                                              java.lang.String defaultDescription)
        Return the description for the field.
        Parameters:
        formElement - The form element.
        defaultDescription - The default description.
        Returns:
        The description to display.

      • hasMultiSelection

        public static boolean hasMultiSelection​(Resource formElement)
        Is this a field with multi selection?
        Parameters:
        formElement - The form element
        Returns:
        true if field has multi selection
        Since:
        5.5

      • redirectToReferrer

        public static void redirectToReferrer​(SlingHttpServletRequest req,
                                      SlingHttpServletResponse res,
                                      java.util.Map<java.lang.String,​java.lang.String[]> params)
                               throws java.io.IOException
        Redirect to the referrer. This method redirects to the referrer and adds optional request parameters.
        Parameters:
        req - The current request
        res - The current response
        Throws:
        java.io.IOException - if redirection caused an error

      • redirectToReferrer

        public static void redirectToReferrer​(SlingHttpServletRequest request,
                                      SlingHttpServletResponse res)
                               throws java.io.IOException
        Redirect to the referrer. This method redirects to the referrerand copies the request parameters.
        Parameters:
        request - The current request
        res - The current response
        Throws:
        java.io.IOException - if redirection caused an error
        Since:
        5.2

      • encodeValue

        public static java.lang.String encodeValue​(java.lang.String value)
        Url encode the value. The value is encoded with character set UTF-8.
        Parameters:
        value - The value
        Returns:
        The encoded value.
        Since:
        5.2

      • decodeValue

        public static java.lang.String decodeValue​(java.lang.String value)
        Url decode the value. The value is decoded with character set UTF-8.
        Parameters:
        value - The value
        Returns:
        The decoded value.
        Since:
        5.2

      • getCss

        public static java.lang.String getCss​(ValueMap props,
                                      java.lang.String defaultCss)
        Return the css classes for the field. If the field has a property FormsConstants.ELEMENT_PROPERTY_CSS the value of this property is appended to the default css. If not, only the default css is returned.
        Parameters:
        props - The field properties.
        defaultCss - The default css for this field.
        Returns:
        The css classes
        Since:
        5.4

      • getReferrer

        public static java.lang.String getReferrer​(HttpServletRequest request)
        Returns the HTTP "referrer" header from the request, and also looks out for the common "referer" misspelling.
        Parameters:
        request - current request
        Returns:
        value of the referrer header or null if not present
        Since:
        5.5

      • setRedirectToReferrer

        public static void setRedirectToReferrer​(ServletRequest request,
                                         boolean redirectToReferrer)
        Sets a flag to redirect to the HTTP referrer after the forward of a form POST request. This will usually only be used if no explicit redirect is already given in the ":redirect" parameter used by the Sling POST servlet.
        Parameters:
        request - current request
        redirectToReferrer - true to enable the redirect to the referrer
        Since:
        5.5

      • isRedirectToReferrer

        public static boolean isRedirectToReferrer​(ServletRequest request)
        Returns whether there should be a redirect to the HTTP referrer after the forward of a form POST request.
        Parameters:
        request - current request
        Returns:
        true if there should be a redirect to the referrer
        Since:
        5.5

      • getLocale

        public static java.util.Locale getLocale​(SlingHttpServletRequest request)
        Returns the locale. If the request originates from a jsp, it returns the locale as defined by the LanguageManager, otherwise it returns null
        Parameters:
        request - The current request
        Returns:
        the locale or null if not determinable

      • getLocalizedMessage

        public static java.lang.String getLocalizedMessage​(java.lang.String msg,
                                                   SlingHttpServletRequest request)
        Returns the localized message. If the request originates from a jsp, it returns the localized message based on the ResourceBundle of the request and the locale defined by the LanguageManager. Otherwise it returns the original message.
        Parameters:
        msg - The message to be localized
        request - The current request
        Returns:
        the localized message or the original message if it cannot be localized

      • getWhitelistPatterns

        public static java.lang.String[] getWhitelistPatterns​(SlingHttpServletRequest req)
        Get the list of white listed data name patterns.
        Parameters:
        req - The current request.
        Returns:
        The array of white listed data name patterns

      • allowExpressions

        public static boolean allowExpressions​(SlingHttpServletRequest req)
        Indicates whether posted form values should be passed through an expression evaluator. It will be up to each component to decide how it react to this attribute.
        Parameters:
        req - The current request.
        Returns:
        true if expressions should be evaluated on posted values