NEW Tooltip and inline help text support for CMS form fields

admin/css/screen.css

@@ -153,19 +153,18 @@ form.nostyle input.text, form.nostyle textarea, form.nostyle select, form.nostyl
 .field:last-child { border-bottom: none; -webkit-box-shadow: none; -moz-box-shadow: none; box-shadow: none; }
 .field:after { content: "\0020"; display: block; height: 0; clear: both; overflow: hidden; visibility: hidden; }
 .field.nolabel .middleColumn { margin-left: 0; }
-.field.nolabel .help { margin-left: 0; }
+.field.nolabel .description { margin-left: 0; }
 .field.checkbox label.right { margin: 4px 0 0 0; display: inline; font-style: normal; color: #444444; clear: none; }
 .field label.left { float: left; display: block; width: 176px; padding: 8px 8px 8px 0; line-height: 16px; font-weight: bold; text-shadow: 1px 1px 0 white; }
 .field label.right { cursor: pointer; clear: both; color: #777777; display: block; font-style: italic; margin: 4px 0 0 184px; }
 .field .middleColumn { margin-left: 184px; }
 .field span.readonly { padding-top: 8px; line-height: 16px; display: block; }
 .field .fieldgroup .fieldgroup-field.last { /* This is used on page/settings/visibility */ padding-bottom: 8px; /* replicates li item spacing */ }
-.field .help { clear: both; color: #777777; display: block; font-style: italic; margin: 4px 0 0 184px; }
+.field .description { clear: both; color: #777777; display: block; font-style: italic; margin: 4px 0 0 184px; }
-.field.help label.right { clear: both; color: #777777; display: block; font-style: italic; margin: 4px 0 0 184px; }
+.field.checkbox .description, .field.ss-gridfield .description { margin-left: 0; }
-.field.checkbox .help, .field.ss-gridfield .help { margin-left: 0; }
+.field input.text, .field textarea, .field select, .field .TreeDropdownField { margin-left: 10px; width: 100%; max-width: 512px; -webkit-box-sizing: border-box; -moz-box-sizing: border-box; box-sizing: border-box; }
-.field input.text, .field textarea, .field select, .field .TreeDropdownField { width: 100%; max-width: 512px; -webkit-box-sizing: border-box; -moz-box-sizing: border-box; box-sizing: border-box; }
+.field input.text.description, .field textarea.description, .field select.description, .field .TreeDropdownField.description { margin: 0; }
-.field input.text.help, .field textarea.help, .field select.help, .field .TreeDropdownField.help { margin: 0; }
+.field input.text .description, .field textarea .description, .field select .description, .field .TreeDropdownField .description { max-width: 512px; }
-.field input.text .help, .field textarea .help, .field select .help, .field .TreeDropdownField .help { max-width: 512px; }
 .field input.text, .field textarea, .field .TreeDropdownField { background: #fff; border: 1px solid #b3b3b3; padding: 7px 7px; line-height: 16px; margin: 0; outline: none; -moz-transition: 0.2s box-shadow ease-in; -webkit-transition: 0.2s box-shadow ease-in; -o-transition: 0.2s box-shadow ease-in; transition: 0.2s box-shadow ease-in; -moz-transition: 0.2s border ease-in; -webkit-transition: 0.2s border ease-in; -o-transition: 0.2s border ease-in; transition: 0.2s border ease-in; -webkit-border-radius: 4px; -moz-border-radius: 4px; -ms-border-radius: 4px; -o-border-radius: 4px; border-radius: 4px; background-image: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4gPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGRlZnM+PGxpbmVhckdyYWRpZW50IGlkPSJncmFkIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9IjUwJSIgeTE9IjAlIiB4Mj0iNTAlIiB5Mj0iMTAwJSI+PHN0b3Agb2Zmc2V0PSIwJSIgc3RvcC1jb2xvcj0iI2VhZWFlYSIvPjxzdG9wIG9mZnNldD0iMTAlIiBzdG9wLWNvbG9yPSIjZmZmZmZmIi8+PC9saW5lYXJHcmFkaWVudD48L2RlZnM+PHJlY3QgeD0iMCIgeT0iMCIgd2lkdGg9IjEwMCUiIGhlaWdodD0iMTAwJSIgZmlsbD0idXJsKCNncmFkKSIgLz48L3N2Zz4g'); background-size: 100%; background-image: -webkit-gradient(linear, 50% 0%, 50% 100%, color-stop(0%, #eaeaea), color-stop(10%, #ffffff)); background-image: -webkit-linear-gradient(#eaeaea, #ffffff 10%); background-image: -moz-linear-gradient(#eaeaea, #ffffff 10%); background-image: -o-linear-gradient(#eaeaea, #ffffff 10%); background-image: linear-gradient(#eaeaea, #ffffff 10%); }
 .field input.text:focus, .field textarea:focus, .field .TreeDropdownField:focus { border: 1px solid #9a9a9a; border-top-color: gray; -webkit-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2) inset; -moz-box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2) inset; box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2) inset; }
 .field input[disabled], .field input.disabled, .field textarea[disabled], .field textarea.disabled, .field select[disabled], .field select.disabled { color: #777777; background: #efefef; background-image: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4gPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGRlZnM+PGxpbmVhckdyYWRpZW50IGlkPSJncmFkIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9IjUwJSIgeTE9IjAlIiB4Mj0iNTAlIiB5Mj0iMTAwJSI+PHN0b3Agb2Zmc2V0PSIwJSIgc3RvcC1jb2xvcj0iI2JjYmNiYyIvPjxzdG9wIG9mZnNldD0iMTAlIiBzdG9wLWNvbG9yPSIjZWZlZmVmIi8+PHN0b3Agb2Zmc2V0PSI5MCUiIHN0b3AtY29sb3I9IiNmZmZmZmYiLz48c3RvcCBvZmZzZXQ9IjEwMCUiIHN0b3AtY29sb3I9IiNiY2JjYmMiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48cmVjdCB4PSIwIiB5PSIwIiB3aWR0aD0iMTAwJSIgaGVpZ2h0PSIxMDAlIiBmaWxsPSJ1cmwoI2dyYWQpIiAvPjwvc3ZnPiA='); background-size: 100%; background-image: -webkit-gradient(linear, 50% 0%, 50% 100%, color-stop(0%, #bcbcbc), color-stop(10%, #efefef), color-stop(90%, #ffffff), color-stop(100%, #bcbcbc)); background-image: -webkit-linear-gradient(#bcbcbc, #efefef 10%, #ffffff 90%, #bcbcbc); background-image: -moz-linear-gradient(#bcbcbc, #efefef 10%, #ffffff 90%, #bcbcbc); background-image: -o-linear-gradient(#bcbcbc, #efefef 10%, #ffffff 90%, #bcbcbc); background-image: linear-gradient(#bcbcbc, #efefef 10%, #ffffff 90%, #bcbcbc); border: 1px solid #b3b3b3; }
@@ -243,7 +242,7 @@ form.small .field input.text, form.small .field textarea, form.small .field sele
 .ss-toggle .ui-accordion-content .field:last-child { margin-bottom: 0; }
 .ss-toggle .ui-accordion-content .field .middleColumn { margin-left: 0; }
 .ss-toggle .ui-accordion-content .field label { float: none; margin-left: 0; }
-.ss-toggle .ui-accordion-content .field .help { margin-left: 0; }
+.ss-toggle .ui-accordion-content .field .description { margin-left: 0; }
 
 /** ---------------------------------------------------- Checkbox Field ---------------------------------------------------- */
 .field.checkbox { padding-left: 184px; margin-bottom: 8px; }

admin/javascript/LeftAndMain.FieldHelp.js

@@ -1,27 +1,35 @@
 (function($) {
 	$.entwine('ss', function($) {
 		/**
-		 * Takes form fields with a title attribute, extracts it, and displays
+		 * Converts an inline field description into a tooltip
-		 * it as inline help text below the field.
+		 * which is shown on hover over any part of the field container,
+		 * as well as when focusing into an input element within the field container.
+		 *
+		 * Note that some fields don't have distinct focusable
+		 * input fields (e.g. GridField), and aren't compatible
+		 * with showing tooltips.
 		 */
-		$(".cms form .field .middleColumn > [title]").entwine({
+		$(".cms .field.cms-description-tooltip").entwine({
 			onmatch: function() {
-				
+				var descriptionEl = this.find('.description'), inputEl, tooltipEl;
-				var title = this.prop("title");
+				if(descriptionEl.length) {
-				var field = this.closest(".field");
+					this
-
+						// TODO Remove title setting, shouldn't be necessary
-				if(title && title.length && field.has('.help').length == 0) {
+						.attr('title', descriptionEl.text())
-					var span = $("<span></span>", {
+						.tooltip({content: descriptionEl.html()});
-						"class": "help",
+					descriptionEl.remove();
-						"text":  title
-					});
-
-					field.append(span);
-					this.removeProp("title");
 				}
-
-				this._super();
 			}
 		});
+
+		$(".cms .field.cms-description-tooltip :input").entwine({
+			onfocusin: function(e) {
+				this.closest('.field').tooltip('open');
+			},
+			onfocusout: function(e) {
+				this.closest('.field').tooltip('close');
+			}
+		});
+
 	});
 }(jQuery));

admin/scss/_forms.scss

@@ -42,7 +42,7 @@ form.nostyle {
 		.middleColumn {
 			margin-left: 0;
 		}
-		.help {
+		.description {
 			margin-left: 0;
 		}
 	}
@@ -90,23 +90,15 @@ form.nostyle {
 
 	// Additional help text to clarify the field intent,
 	// displayed alongside the field (rather than in a tooltip)
-	.help {
+	.description {
 		clear: both;
 		color: lighten($color-text, 20%);
 		display: block;
 		font-style: italic;
-		margin: $grid-y/2 0 0 $grid-x*23;
+		margin: $grid-y/2 0 0 $grid-x*23; // left align with .middleColumn
 	}
-	&.help {
+	
-		label.right {
+	&.checkbox .description, &.ss-gridfield .description {
-			clear: both;
-			color: lighten($color-text, 20%);
-			display: block;
-			font-style: italic;
-			margin: $grid-y/2 0 0 $grid-x*23;
-		}
-	}
-	&.checkbox .help, &.ss-gridfield .help {
 		margin-left: 0;
 	}
 	
@@ -118,10 +110,10 @@ form.nostyle {
 		width: 100%;
 		max-width: $grid-x * 64;
 		@include box-sizing(border-box);
-		&.help {
+		&.description {
 			margin:0; //overrides help class adding left margin to the textarea input.
 		}
-		.help {
+		.description {
 			max-width: $grid-x * 64;
 		}
 	}
@@ -588,7 +580,7 @@ form.small .field, .field.small {
 				float: none;
 				margin-left: 0;
 			}
-			.help {
+			.description {
 				margin-left: 0;
 			}
 		}

docs/en/howto/cms-formfield-help-text.md

@@ -0,0 +1,30 @@
+# How to Show Help Text on CMS Form Fields
+
+Sometimes you need to express more context for a form field
+than is suitable for its `<label>` element.
+The CMS provides you with an easy way to transform
+form field attributes into either help text
+shown alongside the field, or a tooltip which shows on demand.
+
+The `FormField->setDescription()` method will add a `<span class="description">`
+at the last position within the field, and expects unescaped HTML content.
+
+	:::php
+	TextField::create('MyText', 'My Text Label')
+		->setDescription('More <strong>detailed</strong> help');
+
+To show the help text as a tooltip instead of inline,
+add a `.cms-description-tooltip` class. 
+
+	:::php
+	TextField::create('MyText', 'My Text Label')
+		->setDescription('More <strong>detailed</strong> help')
+		->addExtraClass('cms-help-tooltip');
+
+Tooltips are only supported
+for native, focusable input elements, which excludes
+more complex fields like `GridField`, `UploadField`
+or `DropdownField` with the chosen.js behaviour applied.
+
+Note: For more advanced help text we recommend using
+[Custom form field templates](/topics/forms#custom-form-field-templates);

docs/en/howto/index.md

@@ -12,6 +12,7 @@ the language and functions which are used in the guides.
 * [PHPUnit Configuration](phpunit-configuration). How to setup your testing environment with PHPUnit
 * [Extend the CMS Interface](extend-cms-interface). 
 * [How to customize CMS Tree](customize-cms-tree).
+* [How to Show Help Text on CMS Form Fields](cms-formfield-help-text).
 * [Cache control](cache-control). Override the default PHP cache-control settings.
 * [Howto customize the CMS menu](customize-cms-menu).
 * [How to create a navigation menu](navigation-menu). Create primary navigation for your website.

forms/gridfield/GridField.php

@@ -397,6 +397,13 @@ class GridField extends FormField {
 			'cellspacing' => '0'	
 		);
 
+		if($this->getDescription()) {
+			$content['after'] .= FormField::create_tag(
+				'span', 
+				array('class' => 'description'), 
+				$this->getDescription()
+			);
+		}
 
 		return
 			FormField::create_tag('fieldset', $attrs, 

templates/forms/CheckboxField_holder.ss

@@ -2,4 +2,5 @@
 	$Field
 	<label class="right" for="$ID">$Title</label>
 	<% if Message %><span class="message $MessageType">$Message</span><% end_if %>
+	<% if Description %><span class="description">$Description</span><% end_if %>
 </div>

templates/forms/CompositeField_holder.ss

@@ -12,4 +12,6 @@
 			$FieldHolder
 		<% end_if %>
 	<% end_loop %>
+
+	<% if Description %><span class="description">$Description</span><% end_if %>
 </$Tag>