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

Class FormsHelper

java.lang.Object
com.day.cq.wcm.foundation.forms.FormsHelper
public class FormsHelper extends Object
Helper class for the forms components.

  • Field Details

  • Method Details

    • startForm

      @Deprecated public static void startForm(SlingHttpServletRequest request, SlingHttpServletResponse response, JspWriter out) throws IOException, ServletException
      Deprecated.
      Use startForm(SlingHttpServletRequest, SlingHttpServletResponse)
      Signal the start of the form. Prepare the request object, write out the client javascript (if the form is configured accordingly) and write out the start form tag and hidden fields: FormsConstants.REQUEST_PROPERTY_FORMID with the value of the form id. FormsConstants.REQUEST_PROPERTY_FORM_START with the relative path to the form start par and _charset_ with the value UTF-8
      Parameters:
      request - The current request.
      response - The current response.
      out - The jsp writer.
      Throws:
      IOException - if form generation caused an error
      ServletException - if form generation caused an error

    • startForm

      public static void startForm(SlingHttpServletRequest request, SlingHttpServletResponse response) throws IOException, ServletException
      Signal the start of the form. Prepare the request object, write out the client javascript (if the form is configured accordingly) and write out the start form tag and hidden fields: FormsConstants.REQUEST_PROPERTY_FORMID with the value of the form id. FormsConstants.REQUEST_PROPERTY_FORM_START with the relative path to the form start par and _charset_ with the value UTF-8
      Parameters:
      request - The current request.
      response - The current response.
      Throws:
      IOException - if form generation caused an error
      ServletException - if form generation caused an error
      Since:
      5.3

    • runAction

      public static void runAction(String actionType, String scriptName, Resource formResource, SlingHttpServletRequest request, SlingHttpServletResponse response) throws IOException, ServletException
      Runs/includes a script of the form action.
      Parameters:
      actionType - action type
      scriptName - script name
      formResource - resource
      request - request
      response - response
      Throws:
      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, 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, 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 String getForwardPath(SlingHttpServletRequest req)
      Get the forward path for processing the form.
      Parameters:
      req - The current request.
      Returns:
      The forward path or null.

    • setForwardOptions

      public static void setForwardOptions(ServletRequest req, RequestDispatcherOptions options)
      Sets the Sling RequestDispatcherOptions to be used when forwarding to getForwardPath(SlingHttpServletRequest).
      Parameters:
      req - The current request
      options - options to use with forward path
      Since:
      5.5

    • getForwardOptions

      public static RequestDispatcherOptions getForwardOptions(ServletRequest req)
      Gets the Sling RequestDispatcherOptions to be used when forwarding to getForwardPath(SlingHttpServletRequest).
      Parameters:
      req - The current request
      Returns:
      options to use with forward path or null
      Since:
      5.5

    • setForwardRedirect

      public static void setForwardRedirect(ServletRequest request, 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 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, 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 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, 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 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 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, String selectorString) throws 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:
      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 String getFormId(SlingHttpServletRequest req)
      Return the formid
      Parameters:
      req - Request
      Returns:
      The form id or null

    • getParameterName

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

    • getFieldId

      public static 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 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 Iterator<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, 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 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 String getValue(SlingHttpServletRequest request, Resource elementResource, 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 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 String[] getValues(SlingHttpServletRequest request, Resource elementResource, 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 List<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 String getValue(SlingHttpServletRequest request, String name, 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 String[] getValues(SlingHttpServletRequest request, String name, 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, Writer out, String path) throws 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
      IOException - if there was a problem with the writer

    • inlineValuesAsJson

      public static void inlineValuesAsJson(SlingHttpServletRequest request, Writer out, String path, int nodeDepth) throws 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
      IOException - if there was a problem with the writer

    • getShowHideExpressions

      public static Map<String,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 Map<String,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.

    • setFormReadOnly

      public static void setFormReadOnly(SlingHttpServletRequest request)
      Marks the current form rendering to produce an read-only form. Form field renderings must use isReadOnly(SlingHttpServletRequest, Resource) to decide between edit or read-only representations.
      Parameters:
      request - the current request

    • pushFormReadOnly

      public static Object pushFormReadOnly(SlingHttpServletRequest request)
      Push a temporary read-only state. (See setFormReadOnly(SlingHttpServletRequest) for further details of read-only states.)
      Parameters:
      request - the current request
      Returns:
      a token for use by popFormReadOnly(SlingHttpServletRequest, Object)

    • popFormReadOnly

      public static void popFormReadOnly(SlingHttpServletRequest request, Object previousState)
      Pop a temporary read-only state.
      Parameters:
      request - the current request
      previousState - The token returned by pushFormReadOnly(SlingHttpServletRequest)

    • 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, 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 String getTitle(Resource formElement, 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 String getDescription(Resource formElement, 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, Map<String,String[]> params) throws 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:
      IOException - if redirection caused an error

    • redirectToReferrer

      public static void redirectToReferrer(SlingHttpServletRequest request, SlingHttpServletResponse res) throws 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:
      IOException - if redirection caused an error
      Since:
      5.2

    • checkFormStructure

      @Deprecated public static Resource checkFormStructure(Resource rsrc)
      Deprecated.
      use FormStructureHelper.updateFormStructure(Resource) instead.
      Fix the form. When a form start is added, add automatically a forms end (if missing) When only a form end is on the page remove it
      Since:
      5.2

    • encodeValue

      public static String encodeValue(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 String decodeValue(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 String getCss(ValueMap props, 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 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 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 String getLocalizedMessage(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 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