Show help text alongside field if specified

doc/reference/Field.md

@@ -173,6 +173,9 @@ Define the default value of the field in the creation form.
 * `pinned(boolean)`
 Whether the field should always appear. Used in filters (see listView Settings). Default to false.
 
+* `helpText(string)`
+Define help text to be shown under the field in `editionView` and `creationView`.
+
 ## `wysiwyg` Field Type
 
 * `stripTags(boolean)`

package.json

@@ -9,7 +9,7 @@
     "url": "git://github.com/marmelab/ng-admin.git"
   },
   "devDependencies": {
-    "admin-config": "^0.11.0",
+    "admin-config": "stevehalford/admin-config#field-descriptions",
     "angular": "~1.4.8",
     "angular-mocks": "~1.4.8",
     "angular-numeraljs": "^1.1.6",

src/javascripts/ng-admin/Crud/CrudModule.js

@@ -81,6 +81,7 @@ CrudModule.directive('maViewBatchActions', require('./button/maViewBatchActions'
 CrudModule.directive('maShowItem', require('./show/maShowItem'));
 CrudModule.directive('maViewActions', require('./misc/ViewActions'));
 CrudModule.directive('compile', require('./misc/Compile'));
+CrudModule.directive('maHelpText', require('./misc/maHelpText'));
 
 CrudModule.config(require('./routing'));
 CrudModule.config(require('./config/factories'));

src/javascripts/ng-admin/Crud/fieldView/BooleanFieldView.js

@@ -5,5 +5,6 @@ export default {
     getWriteWidget:  () => `<div class="row">
         <ma-choice-field class="col-sm-4 col-md-3" ng-if="!field.validation().required" field="::field" value="$parent.value"></ma-choice-field>
         <ma-checkbox-field class="col-sm-4 col-md-3" ng-if="!!field.validation().required" field="::field" value="$parent.value"></ma-checkbox-field>
+        <ma-help-text field="field"></ma-help-text>
     </div>`
 };

src/javascripts/ng-admin/Crud/fieldView/ChoiceFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-string-column value="::field.getLabelForChoice(value, entry)"></ma-string-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-choice-field field="::field" value="value"></ma-choice-field>',
-    getWriteWidget:  () => '<ma-choice-field field="::field" entry="entry" value="value"></ma-choice-field>'
+    getWriteWidget:  () => '<ma-choice-field field="::field" entry="entry" value="value"></ma-choice-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/ChoicesFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-choices-column values="::value"></ma-choices-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-choices-field field="::field" value="value"></ma-choices-field>',
-    getWriteWidget:  () => '<ma-choices-field field="::field" entry="::entry" value="value"></ma-choices-field>'
+    getWriteWidget:  () => '<ma-choices-field field="::field" entry="::entry" value="value"></ma-choices-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/DateFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-date-column field="::field" value="::value"></ma-date-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-date-field field="::field" value="value"></ma-date-field>',
-    getWriteWidget:  () => '<div class="date_widget"><ma-date-field field="::field" value="value"></ma-date-field></div>'
+    getWriteWidget:  () => '<div class="date_widget"><ma-date-field field="::field" value="value"></ma-date-field></div> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/DateTimeFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-date-column field="::field" value="::value"></ma-date-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-date-field field="::field" value="value"></ma-date-field>',
-    getWriteWidget:  () => '<div class="datetime_widget"><ma-date-field field="::field" value="value"></ma-date-field></div>'
+    getWriteWidget:  () => '<div class="datetime_widget"><ma-date-field field="::field" value="value"></ma-date-field></div> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/EmailFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-string-column value="::value"></ma-string-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-input-field field="::field" value="value"></ma-input-field>',
-    getWriteWidget:  () => '<ma-input-field type="email" field="::field" value="value"></ma-input-field>'
+    getWriteWidget:  () => '<ma-input-field type="email" field="::field" value="value"></ma-input-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/EmbeddedListFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-embedded-list-column field="::field" value="::value" datastore="::datastore"></ma-embedded-list-column>',
     getLinkWidget:   () => 'error: cannot display referenced_list field as linkable',
     getFilterWidget: () => 'error: cannot display referenced_list field as filter',
-    getWriteWidget:  () => '<ma-embedded-list-field field="::field" value="value" datastore="::datastore"></ma-embedded-list-field>'
+    getWriteWidget:  () => '<ma-embedded-list-field field="::field" value="value" datastore="::datastore"></ma-embedded-list-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/FileFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => 'error: cannot display file field as readable',
     getLinkWidget:   () => 'error: cannot display file field as linkable',
     getFilterWidget: () => 'error: cannot display file field as filter',
-    getWriteWidget:  () => '<ma-file-field field="::field" value="value"></ma-file-field>'
+    getWriteWidget:  () => '<ma-file-field field="::field" value="value"></ma-file-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/FloatFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-number-column field="::field" value="::value"></ma-number-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-input-field type="number" step="any" field="::field" value="value"></ma-input-field>',
-    getWriteWidget:  () => '<ma-input-field type="number" step="any" field="::field" value="value"></ma-input-field>'
+    getWriteWidget:  () => '<ma-input-field type="number" step="any" field="::field" value="value"></ma-input-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/JsonFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-json-column value="::value"></ma-json-column>',
     getLinkWidget:   () => 'error: cannot display a json field as linkable',
     getFilterWidget: () => '<ma-input-field field="::field" value="value"></ma-input-field>',
-    getWriteWidget:  () => '<ma-json-field field="::field" value="value"></ma-json-field>'
+    getWriteWidget:  () => '<ma-json-field field="::field" value="value"></ma-json-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/NumberFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-number-column field="::field" value="::value"></ma-number-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-input-field type="number" field="::field" value="value"></ma-input-field>',
-    getWriteWidget:  () => '<ma-input-field type="number" field="::field" value="value"></ma-input-field>'
+    getWriteWidget:  () => '<ma-input-field type="number" field="::field" value="value"></ma-input-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/PasswordFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => 'error: cannot display password field as readable',
     getLinkWidget:   () => 'error: cannot display password field as linkable',
     getFilterWidget: () => 'error: cannot display password field as filter',
-    getWriteWidget:  () => '<ma-input-field type="password" field="::field" value="value"></ma-input-field>'
+    getWriteWidget:  () => '<ma-input-field type="password" field="::field" value="value"></ma-input-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/ReferenceFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-reference-column field="::field" value="::value" datastore="::datastore"></ma-reference-column>',
     getLinkWidget:   () => '<ma-reference-link-column entry="::entry" field="::field" value="::value" datastore="::datastore"></ma-reference-link-column>',
     getFilterWidget: () => '<ma-reference-field field="::field" value="value" datastore="::datastore"></ma-reference-field>',
-    getWriteWidget:  () => '<ma-reference-field field="::field" value="value" datastore="::datastore"></ma-reference-field>'
+    getWriteWidget:  () => '<ma-reference-field field="::field" value="value" datastore="::datastore"></ma-reference-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/ReferenceManyFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-choices-column values="::entry.listValues[field.name()]"></ma-choices-column>',
     getLinkWidget:   () => '<ma-reference-many-link-column ids="::value" values="::entry.listValues[field.name()]" field="::field"></ma-reference-many-link-column>',
     getFilterWidget: () => '<ma-reference-many-field field="::field" value="value" datastore="::datastore"></ma-reference-many-field>',
-    getWriteWidget:  () => '<ma-reference-many-field field="::field" value="value" datastore="::datastore"></ma-reference-many-field>'
+    getWriteWidget:  () => '<ma-reference-many-field field="::field" value="value" datastore="::datastore"></ma-reference-many-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/ReferencedListFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-referenced-list-column field="::field" datastore="::datastore"></ma-referenced-list-column>',
     getLinkWidget:   () => 'error: cannot display referenced_list field as linkable',
     getFilterWidget: () => 'error: cannot display referenced_list field as filter',
-    getWriteWidget:  () => '<ma-referenced-list-column field="::field" datastore="::datastore"></ma-referenced-list-column>'
+    getWriteWidget:  () => '<ma-referenced-list-column field="::field" datastore="::datastore"></ma-referenced-list-column> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/StringFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-string-column value="::value"></ma-string-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-input-field field="::field" value="value"></ma-input-field>',
-    getWriteWidget:  () => '<ma-input-field field="::field" value="value"></ma-input-field>'
+    getWriteWidget:  () => '<ma-input-field field="::field" value="value"></ma-input-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/TextFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-string-column value="::value"></ma-string-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-input-field field="::field" value="value"></ma-input-field>',
-    getWriteWidget:  () => '<ma-text-field field="::field" value="value"></ma-text-field>'
+    getWriteWidget:  () => '<ma-text-field field="::field" value="value"></ma-text-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/fieldView/WysiwygFieldView.js

@@ -2,5 +2,5 @@ export default {
     getReadWidget:   () => '<ma-wysiwyg-column field="::field" value="::value"></ma-wysiwyg-column>',
     getLinkWidget:   () => '<a ui-sref="{{detailState}}(detailStateParams)">' + module.exports.getReadWidget() + '</a>',
     getFilterWidget: () => '<ma-input-field field="::field" value="value"></ma-input-field>',
-    getWriteWidget:  () => '<ma-wysiwyg-field field="::field" value="value"></ma-wysiwyg-field>'
+    getWriteWidget:  () => '<ma-wysiwyg-field field="::field" value="value"></ma-wysiwyg-field> <ma-help-text field="field"></ma-help-text>'
 };

src/javascripts/ng-admin/Crud/misc/maHelpText.js

@@ -0,0 +1,32 @@
+/**
+ * Help text for a form field.
+ *
+ * @example <ma-help-text field="field"></ma-help-text>
+ *
+ * @param field.helpText()  If a string, it will be displayed as text to the user.
+ *                          If an `angular.element`, it will be compiled and displayed.
+ *                          You can use "entry.values[x]" to check the current value
+ *                          of property "x" (e.g. if you want to give different hints)
+ */
+export default function maHelpText($compile) {
+    return {
+        scope: true,
+        restrict: 'E',
+        link: function(scope, element) {
+            var field = scope.field;
+
+            var helpText = field && field.helpText();
+            if (helpText && typeof helpText === "object" && helpText.contents) {
+                // looks like an angular.element:
+                element.append(helpText.clone());
+                $compile(element.contents())(scope);
+            } else {
+                // treat as plain text:
+                scope.helpText = helpText;
+            }
+        },
+        template: '<small ng-if="helpText" class="help-block">{{ helpText }}</small>'
+    };
+}
+
+maHelpText.$inject = ['$compile'];