Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Forms 31: Difference between revisions

From MoodleDocs
(Creation of base page)
 
(38 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Forms for 3.1=
{{Infobox Project
|name = Forms improvements targeted for Moodle 3.1
|state = Planning
|tracker = 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. Current tests show that php 7 is quicker than php 5 and we are always looking to work with the more recent versions of all software.
 
JavaScript forms at the moment are basic hard coded html elements. One of the main stumbling blocks for creating forms in JavaScript is that it is not currently possible to implement a text editor. The text editors need to be able to set up a temporary file area to store images (and files) that are often inserted into the text. So alterations will be made to make these elements work with JavaScript.
 
One of the benefits of mforms is that it automatically inserts aria attributes into the forms for added accessibility. Current JavaScript forms need to manually insert these attributes, and so the JavaScript forms library should also have this functionality.
 
=Scope=
 
We are limiting ourselves to completing the following:
* Updating the current mform library to use templates and work with php 7.
** Changing the class constructors.
** Editing each mform element to use a template.
* Creating AMD modules to create forms in JavaScript.
** Updating the text editors to create file storage areas via AJAX.
** Methods to set and retrieve data in forms
** Error message handling
** Standardized way to create forms.
 
==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==
 
The text editors (Atto, TinyMCE) set up temporary file areas to keep track of images and files. This needs to be updated to use AJAX which will allow them to be inserted into 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. Methods will need to be created to send record data to be inserted into the form elements. Methods will also need to be included to retrieve all of the information from the form to be manipulated as the developer sees fit. A method should also be included to handle validation errors that are received from other sources (web services).
 
=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.
 
=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.
 
Form data object format - The key of the object should match the name given to the form element e.g. name="firstname" this will help when saving the form data.
 
<code javascript>
var firstname = "George";
var description = "<p>Some detail about George</p>";
var countryoptions = [{
        value: "AF",
        text: "Afghanistan"
    },
    {
        value: "AX",
        text: "Aland Islands"
    },
    {
        value: "AL",
        text: "Albania",
        selected: 1
    }]; // Dependant on the form definition.
 
 
var formdata = {
    firstname: {
        id: 'user_firstname',
        label: "First name",
        name: "firstname",
        required: 1,
        size: 40,
        helpButton: firstnamehelp
    },
    description: {
        id: 'user_description',
        label: "Description",
        name: 'description'
    },
    country: {
        id: 'user_country',
        label: 'Country',
        name: 'country',
        options: countryoptions,
        helpButton: countryhelp
    }
};
</code>
In this example "firstname" is a text input, "description" is a textarea, and "country"  is a select element. We could create a helper function to format arrays into the appropriate object to be used with a select form element.
 
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 ready to be sent via AJAX. Formatting may have to be done via the page script in complex situations.
* 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.
 
===Returned form data format===
 
<code javascript>
[{
        name: "firstname",
        value: "George"
    },
    {
        name: "description",
        value: "<p>Some detail about George</p>"
    },
    {
        name: "country",
        value: "AL"
    }
];
</code>
 
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 javascript>
{
  "code" : "formvalidationfailed",
  "message" : "Validation Failed",
  "errors" : [
    {
        "code" : "firstnamespecialcharacters",
        "name" : "firstname",
        "message" : "First name can not use special characters"
    },
    {
        "code" : "passwordnotfilled",
        "name" : "password",
        "message" : "Password can not be blank"
    }
  ]
}
</code>
 
Issue number: MDL-52146
 
==Form definition==
 
We are still deciding on how the forms should be created. Some options are:
* JavaScript 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.
 
[[Image:assign-grader.png|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 student's data.
 
[[Image:assignment-grading.png|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.
 
[[Image:lesson-page.png|lesson-page.png]]
 
* A teacher creates a lesson activity.
* An initial page type needs to be selected and then filled in.
* The teacher then selects the new lesson creation tool.
* The teacher drags lesson page elements onto the page.
* Editing of the lesson page elements is done by clicking the cog and selecting edit.
* The lesson page edit form is very similar to the static mforms page.
* Additional answers may be desired (not shown in images) and so dynamically adding (and deleting) form elements would be desirable.
 
[[Image:lesson-page-form.png|lesson-page-form.png]]
 
=Definitions=
 
* AJAX - Asynchronous JavaScript and XML: Ajax is a method of building interactive applications for the Web that process user requests immediately. http://searchwindevelopment.techtarget.com/definition/Ajax
* WCAG - Web Content Accessibility Guidelines
* mustache template - The current templating system used in Moodle to display web pages. https://docs.moodle.org/dev/Templates

Revision as of 05:29, 20 November 2015

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. Current tests show that php 7 is quicker than php 5 and we are always looking to work with the more recent versions of all software.

JavaScript forms at the moment are basic hard coded html elements. One of the main stumbling blocks for creating forms in JavaScript is that it is not currently possible to implement a text editor. The text editors need to be able to set up a temporary file area to store images (and files) that are often inserted into the text. So alterations will be made to make these elements work with JavaScript.

One of the benefits of mforms is that it automatically inserts aria attributes into the forms for added accessibility. Current JavaScript forms need to manually insert these attributes, and so the JavaScript forms library should also have this functionality.

Scope

We are limiting ourselves to completing the following:

  • Updating the current mform library to use templates and work with php 7.
    • Changing the class constructors.
    • Editing each mform element to use a template.
  • Creating AMD modules to create forms in JavaScript.
    • Updating the text editors to create file storage areas via AJAX.
    • Methods to set and retrieve data in forms
    • Error message handling
    • Standardized way to create forms.

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

The text editors (Atto, TinyMCE) set up temporary file areas to keep track of images and files. This needs to be updated to use AJAX which will allow them to be inserted into 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. Methods will need to be created to send record data to be inserted into the form elements. Methods will also need to be included to retrieve all of the information from the form to be manipulated as the developer sees fit. A method should also be included to handle validation errors that are received from other sources (web services).

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.

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.

Form data object format - The key of the object should match the name given to the form element e.g. name="firstname" this will help when saving the form data.

var firstname = "George";

var description = "

Some detail about George

";

var countryoptions = [{

       value: "AF",
       text: "Afghanistan"
   },
   {
       value: "AX",
       text: "Aland Islands"
   },
   {
       value: "AL",
       text: "Albania",
       selected: 1
   }]; // Dependant on the form definition.


var formdata = {

   firstname: {
       id: 'user_firstname',
       label: "First name",
       name: "firstname",
       required: 1,
       size: 40,
       helpButton: firstnamehelp
   },
   description: {
       id: 'user_description',
       label: "Description",
       name: 'description'
   },
   country: {
       id: 'user_country',
       label: 'Country',
       name: 'country',
       options: countryoptions,
       helpButton: countryhelp
   }

}; In this example "firstname" is a text input, "description" is a textarea, and "country" is a select element. We could create a helper function to format arrays into the appropriate object to be used with a select form element.

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 ready to be sent via AJAX. Formatting may have to be done via the page script in complex situations.
  • 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.

Returned form data format

[{

       name: "firstname",
       value: "George"
   },
   {
       name: "description",

value: "

Some detail about George

"

   },
   {
       name: "country",
       value: "AL"
   }

];

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",
       "name" : "firstname",
       "message" : "First name can not use special characters"
   },
   {
       "code" : "passwordnotfilled",
       "name" : "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:

  • JavaScript 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 student's 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.

lesson-page.png

  • A teacher creates a lesson activity.
  • An initial page type needs to be selected and then filled in.
  • The teacher then selects the new lesson creation tool.
  • The teacher drags lesson page elements onto the page.
  • Editing of the lesson page elements is done by clicking the cog and selecting edit.
  • The lesson page edit form is very similar to the static mforms page.
  • Additional answers may be desired (not shown in images) and so dynamically adding (and deleting) form elements would be desirable.

lesson-page-form.png

Definitions