Forms 31

Revision as of 07:12, 18 November 2015 by Adrian Greeve (talk | contribs) (Use Cases - lesson module creation interface)

Jump to: navigation, search
Forms improvements targeted for Moodle 3.1
Project state Planning
Tracker issue MDL-52143
Discussion https://devpad.moodle.org/p/new_forms_lib, https://moodle.org/mod/forum/discuss.php?d=322751
Assignee Adrian Greeve


Forms for 3.1 (Purpose)

The main driving forces behind updating the forms library are a desire to create forms in JavaScript, and to make the current mforms work in php 7.

Scope

We are limiting ourselves to completing the following:

  • Updating the current mform library to use templates and work with php 7.
  • Creating AMD modules to create forms in JavaScript.

Updating mforms

Moodle currently uses mforms to create most of it's forms. We will be keeping this existing framework as a lot of work has been put in to customise it to Moodle and it still works; will maintain backwards compatibility; and will allow a gradual move to a different framework if required. Typical php forms are expected to still use this library.

php 7

Currently mforms doesn't work with php 7. This is mainly due to the use of the old constructor definition. We currently have MDL-52081 to fix the constructor throughout Moodle, including the mforms.

Mustache templates

Mustache templates have been introduced into Moodle. The current mform elements will be moved over to use the templates and become renderable. MDL-52144 is the issue number for updating the 'text' form element. See the epic issue for the full list of form elements being updated to use mustache templates.

JavaScript forms

Currently we have no library for creating a form in JavaScript. We need a library so that navigation and error handling are done in an accessible way.

System Overview

The JavaScript Form library does not use current existing libraries and needs to be created.

Populating a form

Filling in a form with all of the current information for a specific record or table.

  • The JavaScript file calls the AMD module function to create a form, and supplies that function with the current record values (Record values to be retrieved beforehand).
  • Some form elements may require an ajax request to create the form (select, autocomplete, radio buttons, checkboxes) e.g. Categories for creating a new course page.
  • Values are mapped to the correct fields and the form is now ready to be used.

Issue number: MDL-52159

Retrieving all information from a form ready for AJAX

  • Form is created and filled in.
  • Data is retrieved from the form and formatted into a format for the web service.
  • Web service save [info] called via AJAX.
  • Success message sent from the web service if save is successful.
  • A message should be displayed and / or the form is closed.

Issue number: MDL-52145

Form validation

  • Form is submitted
  • Form is formatted into a format for the web service
  • Form data is sent to the web service via AJAX
  • Data is validated
  • Validation errors are sent back via AJAX and then handled by the AMD module.
  • Errors are mapped to form elements and the top error element is set to focus.
  • If validation passes in the web service then the data is saved and a success message sent.
  • User is informed that the form has been saved.

Accepted error format

The received errors from the webservice should allow for mapping to the fields in the form. The following format is taken from http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#errors. The message could already be translated in the webservice and save an AJAX call to retrieve the string later.

{
  "code" : "formvalidationfailed",
  "message" : "Validation Failed",
  "errors" : [
    {
        "code" : "firstnamespecialcharacters",
        "field" : "firstname",
        "message" : "First name can not use special characters"
    },
    {
        "code" : "passwordnotfilled",
        "field" : "password",
        "message" : "Password can not be blank"
    }
  ]
}

Issue number: MDL-52146

Form definition

We are still deciding on how the forms should be created. Some options are:

  • JS only api that loosely resembles the mforms API.
  • In a mustache template with some magic processing.
  • In php - exporting the form definition in a standard format and sending it to the JavaScript.

Issue number: MDL-52147

Use Cases

Assignment module grading

The current assignment module can be cumbersome when trying to quickly grade a lot of students. The grading page requires some scrolling to view all the information, and all of this could be better presented on the page. Better use could be made of the screen and all relevant information could be shown all at once.

Ideally the page would use JavaScript to move between the students and the grades and feedback for the assignment would be loaded and saved via AJAX.

assign-grader.png


  • The teacher opens the grader form.
  • The student's submission and grade data is retrieved to populate the form.
  • The teacher reviews the submission and enters in a grade and feedback.
  • form information is pulled from the form and sent off to be validated and saved.
  • Any validation errors are show on the form with the first element having focus.
  • Once the form is successfully saved a message or some visual cue is displayed.
  • The teacher either closes the page or moves to the next student.
  • The form is loaded with the next students data.

assignment-grading.png

New Lesson module creation interface

The new lesson module create interface is a project to make creating lessons more intuitive, and provide a better understand of the flow of each particular lesson (MDL-50905). The interface is completely JavaScript. It is not currently possible to create forms like the standard ones as the text editors need to create draft areas and there is no code to do this via AJAX currently. Moving the teacher out of the dynamic page to a static one to fill out a form is not very graceful. The current forms do not have text editors available, instead it just uses a text area form element.

Requirements

JavaScript Forms

One of the main reasons for creating a library for form elements in JavaScript is to ensure that the form elements are accessible. It is very convenient to have accessibility included automatically in the form elements. See WCAG 2.0? http://www.w3.org/TR/WCAG20/#minimize-error for a description of possible error types and how to meet the requirements.

  • Form elements should automatically insert additional divs and spans for error messages and points of focus in the form.
  • Form elements should include and update aria attributes to inform screen readers of the current form status.
  • Forms should do simple validation on the client side.
  • Forms should be revalidated on the server side.
  • Errors from validation need to be specific to the form element that created the error where possible.
  • Forms should request and submit information via AJAX to web services.
  • Forms and form elements should not need to be recreated with new data. form values should have the ability to be updated with new data.