0.8.3 Field template does not show description after upgrading to 1.0.0-alpha.5

[donalmurtagh]

Problem

Steps to reproduce:

• Open the Plunker demo
• Enter some data in the field and notice that the description "Enter your name" appears under the field when it is valid
• Clear the contents of the field such that it becomes invalid, and notice that the error message is displayed twice: once in the expected <div> and once in the <div> which is supposed to show the description

This demo uses the latest 1.0.0-alpha.5 code. I've changed the default field template by making the following change to angular-schema-form-bootstap.js on line 125

var path = '/bootstrap/default.html';
var html =
    '<div class="form-group schema-form-{{form.type}} {{form.htmlClass}}"' +
    '     ng-class="{\'has-error\': hasError(), \'has-success\': hasSuccess() }">' +

    '    <label class="control-label" for="{{form.key.join(\'.\')}}"> ' +
    '        {{form.title}}' +
    '    </label>' +

    '    <input ng-show="form.key"' +
    '           type="{{form.type}}"' +
    '           sf-changed="form"' +
    '           placeholder="{{form.placeholder}}"' +
    '           class="form-control {{form.fieldHtmlClass}}"' +
    '           id="{{form.key.join(\'.\')}}"' +
    '           sf-field-model' +
    '           ng-disabled="form.readonly"' +
    '           schema-validate="form"' +
    '           name="{{form.key.join(\'.\')}}">' +

    '        <div class="help-block" ng-show="(hasError() && errorMessage(schemaError()))"' +
    '             ng-bind-html="(hasError() && errorMessage(schemaError()))"></div>' +

    '        <div class="help-block success" ng-show="form.description" sf-message="form.description"></div>' +
    '</div>';

When using version 0.8.3 this template works as expected, i.e. when a field is valid only the description is shown under the field, and when a field is invalid both the validation message and description are shown under the field.

My Solution

I replaced the following

<div class="help-block" aria-live='assertive'
     ng-show="(hasError() && errorMessage(schemaError()))"
     ng-bind-html="(hasError() && errorMessage(schemaError()))"></div>

<div class="help-block success" ng-show="form.description" sf-message="form.description"></div>

with:

<div class="help-block" aria-live='assertive'
     ng-show="(hasError() && errorMessage(schemaError()))"
     ng-bind-html="(hasError() && errorMessage(schemaError()))"></div>

<div class="help-block success" ng-show="form.description" ng-bind-html="form.description"></div>

After making this change, I see both the description and the error message when a field is in an invalid state.

Conclusion

It seems the behaviour of sf-message="form.description" has changed in the two versions, i.e. in 0.8.3 it always returns the description, but in 1.0.0-alpha.5 it returns the error message if the field is in an invalid state.

If this change is retained, it should be documented in an upgrade guide.

Usability (aside)

Personally, I think always showing the field description is preferable from a usability point of view. Typically, the field description provides some hints to the user about how to complete a field, so if a field is invalid, that's likely when it is most useful, so I dislike hiding the description when the field is invalid.

@json-schema-form/angular-schema-form-lead

[Anthropic]

@donalmurtagh I agree with you usability, I want to add a help tooltip option 'hint' or 'instruction' to make it clearer what the annotation is for, my one problem with 'description' is that the json-schema is used for defining only the data definition and validation and as such technically description should be more like 'I am the field for this' rather than 'please enter your whatever here'. There is discussions in the json-schema org about an annotation extension to provide the additional information as well as one for error message handling, so in future there will be breaking changes in this area I expect.

For now I will take a look at this as a bug, I suspect the test cases check for the error showing but don't check if there are two of the same thing!

[donalmurtagh]

my one problem with 'description' is that the json-schema is used for defining only the data definition and validation

In my case I use the field description to provide guidance to the user about how to complete the field, and this is always defined via the description attribute of the field in the form definition, e.g.

    $scope.schema = {
      "type": "object",
      "properties": {
        name: {
          type: "string",
        }
      },
      "required": ['name']
    };

    $scope.form = [{
      key: 'name',
      validationMessage: 'This field is required',
      description: 'Enter your first name and surname'
    }];

Am I using description incorrectly?

[Anthropic]

In ASF you are using it correctly, but ASF is currently using it wrong in my opinion and it will probably need to change in future. But not yet.

[scottux]

I think this is related to #866