[5.1] Header list field

administrator/language/en-GB/plg_fields_list.ini

@@ -7,6 +7,8 @@ PLG_FIELDS_LIST="Fields - List"
 PLG_FIELDS_LIST_LABEL="List (%s)"
 ; The following string is deprecated and will be removed with 6.0
 PLG_FIELDS_LIST_PARAMS_FORM_LAYOUT_FANCY_SELECT="Enhanced select"
+PLG_FIELDS_LIST_PARAMS_HEADER_DESC="Add a string with no value at the top of the dropdown list eg ' - Select Article - '."
+PLG_FIELDS_LIST_PARAMS_HEADER_LABEL="Header"
 PLG_FIELDS_LIST_PARAMS_MULTIPLE_LABEL="Multiple"
 PLG_FIELDS_LIST_PARAMS_OPTIONS_LABEL="List Values"
 PLG_FIELDS_LIST_PARAMS_OPTIONS_NAME_LABEL="Text"

libraries/src/Form/Field/ListField.php

@@ -14,6 +14,7 @@
 use Joomla\CMS\Form\FormField;
 use Joomla\CMS\Form\FormHelper;
 use Joomla\CMS\Helper\ModuleHelper;
+use Joomla\CMS\HTML\HTMLHelper;
 use Joomla\CMS\Language\Associations;
 use Joomla\CMS\Language\Multilanguage;
 use Joomla\CMS\Language\Text;
@@ -48,6 +49,14 @@ class ListField extends FormField
      */
     protected $layout = 'joomla.form.field.list';
 
+    /**
+     * The header.
+     *
+     * @var    mixed
+     * @since  __DEPLOY_VERSION__
+     */
+    protected $header;
+
     /**
      * Method to get the field input markup for a generic list.
      * Use the multiple attribute to enable multiselect.
@@ -74,8 +83,14 @@ protected function getInput()
      */
     protected function getOptions()
     {
+        $header    = $this->header;
         $fieldname = preg_replace('/[^a-zA-Z0-9_\-]/', '_', $this->fieldname);
         $options   = [];
+        // Add header.
+        if (!empty($header)) {
+            $header_title = Text::_($header);
+            $options[]    = HTMLHelper::_('select.option', '', $header_title);
+        }
 
         foreach ($this->element->xpath('option') as $option) {
             // Filter requirements
@@ -232,4 +247,30 @@ public function __get($name)
 
         return parent::__get($name);
     }
+
+    /**
+     * Method to attach a Form object to the field.
+     *
+     * @param   \SimpleXMLElement  $element  The SimpleXMLElement object representing the `<field>` tag for the form field object.
+     * @param   mixed              $value    The form field value to validate.
+     * @param   string             $group    The field name group control value. This acts as an array container for the field.
+     *                                       For example if the field has name="foo" and the group value is set to "bar" then the
+     *                                       full field name would end up being "bar[foo]".
+     *
+     * @return  boolean  True on success.
+     *
+     * @see     FormField::setup()
+     * @since   __DEPLOY_VERSION__
+     */
+    public function setup(\SimpleXMLElement $element, $value, $group = null)
+    {
+        $return = parent::setup($element, $value, $group);
+
+        if ($return) {
+            // Check if it's using the old way
+            $this->header = (string) $this->element['header'] ?: false;
+        }
+
+        return $return;
+    }
 }

libraries/src/Form/Field/SqlField.php

@@ -287,12 +287,6 @@ protected function getOptions()
             }
         }
 
-        // Add header.
-        if (!empty($header)) {
-            $header_title = Text::_($header);
-            $options[]    = HTMLHelper::_('select.option', '', $header_title);
-        }
-
         // Build the field options.
         if (!empty($items)) {
             foreach ($items as $item) {

plugins/fields/list/list.xml

@@ -23,6 +23,14 @@
 	<config>
 		<fields name="params">
 			<fieldset name="basic">
+				<field
+					name="header"
+					type="text"
+					label="PLG_FIELDS_LIST_PARAMS_HEADER_LABEL"
+					description="PLG_FIELDS_LIST_PARAMS_HEADER_DESC"
+					filter="string"
+				/>
+
 				<field
 					name="multiple"
 					type="radio"

plugins/fields/list/params/list.xml

@@ -2,6 +2,14 @@
 <form>
 	<fields name="fieldparams">
 		<fieldset name="fieldparams">
+			<field
+				name="header"
+				type="text"
+				label="PLG_FIELDS_LIST_PARAMS_HEADER_LABEL"
+				description="PLG_FIELDS_LIST_PARAMS_HEADER_DESC"
+				filter="string"
+			/>
+
 			<field
 				name="multiple"
 				type="list"