The next version of WebMaker after V4.0 that is due at the end of the year, will support a new capability to enable the user to select JavaScript functions that have JSDocs standard documentation. This will enable the documented details to be displayed within the Studio and provide the parameters and appropriate options automatically. This approach will make it much easier to find common functions, or extend the capabilities of WebMaker with your own functions.
Note: We are notifying you of this feature in advance of release at the end of the year, in order that you may choose to look at documenting your functions in advance. This will be useful if you use common functions across multiple forms or projects. It is very simple to add the necessary comment block for a function (see below).
New 'Perform Script Function' Behaviour
This feature is designed to make it easier for users to add new JavaScript files if required and then find and use those functions via the Events Tab.
You will be able to search for functions in a similar manner to CSS Class Names in version 4.0, but in addition you will be provided with help tips regarding the parameters and appropriate drop-down lists for selection of values.
This is a more maintainable approach than using the 'Custom Script' method, as the parameters can be linked to the in-built WebMaker control types such as Fields, Groups, Repeats and Field specific values. This will mean that if Field or Group names are renamed, the information will remain in sync.
New Functions to be provided
The next version will provide a number of out-of-the-box functions to make it easier for users to use various common capabilities via the Events Tab:
Note: The current version 4.0 has a number of functions that are documented within the reference documentation. These functions will also be documented with JSDocs in the next version. Please refer to: WebMaker JavaScript Functions for further details.
Documenting JavaScript Functions
The future software will provide a list of any JavaScript Functions that are detected against a project, which have JSDoc standard comments before the function. Please see example below:
It is very important that the comment block starts with /** and ends with */.
Each of the other nested lines must have an * at the start.
These lines can then have @... keywords that are reserved for specific uses within JSDocs and WebMaker:
As well as standard data types such as: {boolean} {string} {number} {object}, you can document WebMaker specific data types:
If a Field above has a fixed set of values based on the enumerations defined against the Data Constraints of the field e.g. a radio button or drop-down list, then those values will be provided for the user to select. If the field values are then changed within WebMaker then they would remain in sync., unlike 'custom script' values.
You can define more than one parameter type, but WebMaker will use the first one to present suggested values e.g. {string | Field_Name | Group_Name}. The user can still switch to choose the other options.
Further Reference Material on the JSDocs Standard
For further details on JSDocs, please refer to the following links:
Using JSDocs - Simple examples
Wikipedia entry on JSDocs
[hr][/hr]
We are also very interested to identify those common functions that you would like to see built into WebMaker.
Please review the documentation of existing V4.0 functions, and the new list presented above.
If there are any others please provide details by replying to this post.
Note: We are notifying you of this feature in advance of release at the end of the year, in order that you may choose to look at documenting your functions in advance. This will be useful if you use common functions across multiple forms or projects. It is very simple to add the necessary comment block for a function (see below).
New 'Perform Script Function' Behaviour
This feature is designed to make it easier for users to add new JavaScript files if required and then find and use those functions via the Events Tab.
You will be able to search for functions in a similar manner to CSS Class Names in version 4.0, but in addition you will be provided with help tips regarding the parameters and appropriate drop-down lists for selection of values.
This is a more maintainable approach than using the 'Custom Script' method, as the parameters can be linked to the in-built WebMaker control types such as Fields, Groups, Repeats and Field specific values. This will mean that if Field or Group names are renamed, the information will remain in sync.
New Functions to be provided
The next version will provide a number of out-of-the-box functions to make it easier for users to use various common capabilities via the Events Tab:
- Set Mandatory (required) on/off for fields or groups of fields. This includes displaying the mandatory indicator appropriately. [/*]
- Set or reset Validation Ranges for Numbers - Inclusive or Exclusive Ranges. [/*]
- Set or reset field lengths - Minimum, Maximum or Fixed size lengths.[/*]
- Set or remove a Regular Expression (Validation Pattern) for a string field. [/*]
- Google Maps Current Location function allows the user to mark with a pin the users current location on a Google Map (if the user allows to operation via the Browser).[/*]
- Collapsible Section Set Visibility function can be called to set the visibility state of the collapsible section to either open or closed as required.[/*]
Note: The current version 4.0 has a number of functions that are documented within the reference documentation. These functions will also be documented with JSDocs in the next version. Please refer to: WebMaker JavaScript Functions for further details.
Documenting JavaScript Functions
The future software will provide a list of any JavaScript Functions that are detected against a project, which have JSDoc standard comments before the function. Please see example below:
/**
* This function allows the Mandatory (required) Data Constraint to be set.
* @param field {Field_Name} Set to the field to be constrained.
* @param isMandatory {boolean} Set to true if required, and false if not.
*
* @author Hyfinity Limited
*/
hyf.util.setMandatoryConstraint = function(field, isMandatory)
{
... Your Code ...
}
It is very important that the comment block starts with /** and ends with */.
Each of the other nested lines must have an * at the start.
These lines can then have @... keywords that are reserved for specific uses within JSDocs and WebMaker:
- The @param defines a parameter option for the function. This should be followed by the name of the parameter, its data type in {} brackets, and then a description. If the parameter is optional then we recommend adding the text (optional). [/*]
- The @author should refer to your companies name.[/*]
- The @private will mean the function will not be displayed in the list.[/*]
- The @return documents a return value. This can be useful if functions are performed that return a {boolean} true/false that can be used as a Condition Check within an Event.[/*]
As well as standard data types such as: {boolean} {string} {number} {object}, you can document WebMaker specific data types:
- {Field_Name} - Will provide a list of WebMaker field names[/*]
- {Group_Name} - Will provide a list of WebMaker group names[/*]
- {Repeat_Name} - Will provide a list of WebMaker repeat names[/*]
- {Display_Variable} - Will provide a list of WebMaker display variables[/*]
If a Field above has a fixed set of values based on the enumerations defined against the Data Constraints of the field e.g. a radio button or drop-down list, then those values will be provided for the user to select. If the field values are then changed within WebMaker then they would remain in sync., unlike 'custom script' values.
You can define more than one parameter type, but WebMaker will use the first one to present suggested values e.g. {string | Field_Name | Group_Name}. The user can still switch to choose the other options.
Further Reference Material on the JSDocs Standard
For further details on JSDocs, please refer to the following links:
Using JSDocs - Simple examples
Wikipedia entry on JSDocs
[hr][/hr]
We are also very interested to identify those common functions that you would like to see built into WebMaker.
Please review the documentation of existing V4.0 functions, and the new list presented above.
If there are any others please provide details by replying to this post.
Attachment
