Uploaded image for project: 'Feedback Form'
  1. Feedback Form
  2. FEEDBACKFO-5

Allow custom feedback forms and saving feedback into the Wiki

    XMLWordPrintable

Details

    • New Feature
    • Resolution: Unresolved
    • Major
    • None
    • None
    • None
    • Medium
    • Hard

    Description

      This ticket describes the feature brought by version 2.0 of feedback application. It should have been written before the bulk of the development was done and committed, but here it is. Sorry for that.

      Version 1.0 allows visitors of a XWiki website to submit general feedback. It shows a side "feedback" button on which people can click. A modal is displayed, in which a form with a few required fields lets the users present themselves and write a message. When the form is submitted, a bunch of checks is realized (the required fields are filled) and the report is sent by mail to a configured address and sent to the user.

      Version 2.0 keeps all these features.

      It fixes:

      it provides the following features:

      Save to wiki

      XWiki administrators can enable an option in the FeedbackFormCode.Configuration page, saveToWiki, so feedback is saved in the wiki in the space set in feedbackSpace. By default, feedbackSpace is set to "Feedback".

      The extension will create the space set in feedbackSpace automatically if it does not exist.
      By default, this option is disabled to match the behavior of version 1.0, to allow a smooth upgrade.

      Allow disabling sending feedback by email

      Since feedback can be saved in the wiki, administrators may want to disable sending it by email. It allows using feedback even on an XWiki instance without a proper email installation. Option sendByEmail FeedbackFormCode.Configuration page can be set to false for this.

      Allow disabling the global feedback button

      Some use cases require the button to not be shown, and to trigger the feedback application in another way instead. Option generalButtonEnabled can be set to false in the FeedbackFormCode.Configuration page to hide the button.

      Ask less details to connected users

      Version 1.0 requires the users to provide their title, email, first name, last name. But this is not necessary for logged in users, who have their details in their XWiki account. Version 2.0 hides these fields to such users and link feedback to the users instead.

      Allow providing custom feedback forms

      In version 1.0, the feedback form is hard-coded. Version 2.0 allows administrators to design their own feedback forms.

      Feedback type class

      In order to implement a new form, one needs to create a new feedback type by creating an XWiki document named XXXFeedbackType (where XXX is replaced by a relevant name in camel case).

      Feedback fields

      The custom feedback fields of the feedback type are defined in the class of the XXXFeedbackType document. These fields supplement those defined in the FeedbackMetadataClass class:

      • type: the type of feedback. This is not asked to the end user, but set when feedback is submitted.
      • url: the url of the page on which the feedback is done, if provided
      • referrer: the referrer, if provided
      • userAgent: the user agent, if provided
      • screenResolution: the screen resolution, if provided
      • page: the concerned XWiki page, if provided
      • reporter: the user who is giving feedback. Will be set to XWiki.Guest if the user is not logged in.
      • reporterEmail: the reporter's email, if provided.
      • usersRecipients: users to which feedback is sent. This is not asked to users, but it can be tweaked during submission in the definition of the feedback type.

      Moreover, an object of type FeedbackFormCode.FeedbackTypeClass needs to be added to the {XXXFeedbackType document. This class defines the following fields:

      • type: a string which is a short identifier for the type. This should be the lower case version `XXX` in `XXXFeedbackType`. This is what will be put in the `type` field of `FeedbackMetadataClass` when feedback of this type is submitted.
      • suggestSendingBrowserEnv: a boolean that shows or hides the checkbox letting the user to provide their browser environment when submitting their feedback
      • sendURL: whether the current URL should be sent with the feedback
      • validateAndCustomizeSubmission: an optional velocity code to validate a submission and customize it. Described and specified later
      • allowedFileUploadMaxNumber: the maximum number of files that can be uploaded when submitting feedback? Version 1.0 hard-codes this to 5.
      • allowedFileUploadTypes: allowed types. This is a list of extensions or mimetype patterns as accepted by the accept HTML attribute of file inputs, e.g. "image/,.pdf". '' can be to allow anything. If left empty, for safety, no file will be accepted. Version 1.0 hard-codes a list of allowed extensions.
      • allowedFileUploadMaxSize: This is the maximum size of files in total in bytes. Set to -1 to disable the limit. 0 will disable file upload. Version 1.0 hard-codes this to 5M.
      • fileUploadRequired: in version 2.0, the file upload can be rendered mandatory by setting this to true
      • mailTemplate: an XWiki Page containing an XWiki.Mail object used when sending feedback by mail. Version 1.0 hard-codes this.

      In this mail template, values from the feedback can be retrieved in the provided $feedbackDoc variable, which is an XWiki Document with two objects: an object of type XXXFeedbackType and an object of type FeedbackMetadataClass.

      In addition to $feedbackDoc, like in version 1.0, two variables are provided to the mail template: $mailRecipient and $contextLocale.

        • $contextLocale is the locale to pass to functions such as $services.localization.render
        • $mailRecipients is equal to "user" when the mail is sent to the user, "wiki" when the mail is sent to the wiki administrator.

      In addition to these fields, a sheet needs to be bound to the feedback type document. This sheet defines how the feedback form looks like and how feedback pages for feedback of this type that has been saved in the wiki is displayed.

      Translation strings

      When defining a type, translation strings need to be set (where $type is the value in the type field of FeedbackFormCode.FeedbackTypeClass):

      • feedbackform.types.$type: it is the user-friendly name of the feedback type, like "Website" for website feedbacks.
      • feedbackform.types.$type.field.$field, for each custom $field of the type, defined in the XXXFeedbackType class.

      For example, if I define a Website feedback type (website), I'll define these strings:

      feedbackform.types.website=Website
      feedbackform.types.website.field.reporterEmail=E-mail
      feedbackform.types.website.field.subject=Subject
      feedbackform.types.website.field.message=Message

      ...

      Customizing and validating submissions

      Velocity code can be written in the validateAndCustomizeSubmission field. This code can:

      • add or change email recipients
      • validate the submission (check required fields, check values...), and therefore reject it if necessary
      • alter it: any field of the submission can be set or changed
      • trigger actions when feedback is submitted

      The code can customize the submission by accessing the $feedbackDoc variable, which is the feedback document that would be saved if the saveToWiki parameter is set to true. The $feedbackDoc variable is also available when saveToWiki is false, but the document won't be automatically saved. At the moment the code is run, $feedbackDoc contains two objects:

      • an XXXFeedbackType object
      • a FeedbackMetadata object

      These objects are filled with the default settings (like the email recipient) and the submitted data. Any modification will be taken in account when sending the mails and saving to the wiki.

      To validate the submission, the code should check the values available in the objects of $feedbackDoc. The code can set the $cancelSubmission variable to true to reject the submission.

      Integration macro: #feedbackButton

      Version 2.0 provides the feedbackButton macro in FeedbackFormCode.PublicMacros. This macro  allows velocity code to show a button that will display the feedback modal. It takes config parameter with these possible keys:

      • buttonLabel: the label of the button (default: "Feedback")
      • modalTitle: the title of the feedback modal (default: "Feedback")
      • allowFeedbackTypeChoice: let the user pick a public feedback type (default: true)
      • sendEmail: Submitted feedback should be sent by email (default: unset)
      • {{saveAsWikiPage: }}Submitted feedback should be saved in the wiki (default: unset)
      • type: the type of feedback to use (default: unset)

      Provided feedback type: Website

      Version 2.0 provides a website feedback type defined in WebsiteFeedbackType. This type serves two purposes:

      • being an example of feedback type implementation
      • keeping feature parity with version 1.0.

      It does not actually keeps feature parity: the distinction between website feedback and website page feedback submission is dropped, making the feedback modal a bit easier to the user. The actual message they write will make it clear whether the feedback is specific to the page or to the website in general.

      Version 2.0 comes with a prettier and clearer mail template, making it more enjoyable to read received feedback and looking more professional to users since they received their own feedback by mail.

      Allowed upload file types are a bit less restrictive in version 2.0: image/*,.pdf, which allows any image format, and PDFs, instead of a restricted list of image formats and PDFs hard-coded in version 1.0.

      Rich text submission fields (experimental)

      Version 2.0 allows rich text textarea fields. It will load ckeditor when needed. However, this presents a number of limitations which makes it an experimental feature:

      • CKEditor fails to load in a number of cases, including when a element of the same id as the field is already present in the page or when trying to submit feedback in edit mode
      • no HTML cleaning / sanitizing is done, which could cause security and robustness issues.

      Related commits:

       

       

      Attachments

        Activity

          People

            rjakse Raphaël Jakse
            rjakse Raphaël Jakse
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

              Created:
              Updated: