NEW: Implement unshift() in field list classes (closes #4834)

forms/CompositeField.php

@@ -213,6 +213,15 @@ class CompositeField extends FormField {
 		$this->children->push($field);
 	}
 
+	/**
+	 * Add a new child field to the beginning of the set.
+	 *
+	 * @param FormField
+	 */
+	public function unshift(FormField $field) {
+		$this->children->unshift($field);
+	}
+
 	/**
 	 * @uses FieldList->insertBefore()
 	 */

forms/FieldList.php

@@ -412,16 +412,27 @@ class FieldList extends ArrayList {
 	}
 
 	/**
-	 * Push a single field into this FieldList instance.
+	 * Push a single field onto the end of this FieldList instance.
 	 *
 	 * @param FormField $item The FormField to add
-	 * @param string $key An option array key (field name)
 	 */
-	public function push($item, $key = null) {
+	public function push($item) {
 		$this->onBeforeInsert($item);
 		$item->setContainerFieldList($this);
 
-		return parent::push($item, $key);
+		return parent::push($item);
+	}
+
+	/**
+	 * Push a single field onto the beginning of this FieldList instance.
+	 *
+	 * @param FormField $item The FormField to add
+	 */
+	public function unshift($item) {
+		$this->onBeforeInsert($item);
+		$item->setContainerFieldList($this);
+
+		return parent::unshift($item);
 	}
 
 	/**

forms/TabSet.php

@@ -150,6 +150,14 @@ class TabSet extends CompositeField {
 		$field->setTabSet($this);
 	}
 
+	/**
+	 * Add a new child field to the beginning of the set.
+	 */
+	public function unshift(FormField $field) {
+		parent::unshift($field);
+		$field->setTabSet($this);
+	}
+
 	/**
 	 * Inserts a field before a particular field in a FieldList.
 	 *

tests/forms/CompositeFieldTest.php

@@ -44,6 +44,24 @@ class CompositeFieldTest extends SapphireTest {
 		$this->assertStringEndsWith('/fieldset>', trim($fieldset->FieldHolder()));
 	}
 
+	public function testPushAndUnshift() {
+		$composite = new CompositeField(
+			new TextField('Middle')
+		);
+
+		$composite->push(new TextField('End'));
+		/* There are now 2 fields in the set */
+		$this->assertEquals(2, $composite->getChildren()->Count());
+		/* The most recently added field is at the end of the set */
+		$this->assertEquals('End', $composite->getChildren()->Last()->getName());
+
+		$composite->unshift(new TextField('Beginning'));
+		/* There are now 3 fields in the set */
+		$this->assertEquals(3, $composite->getChildren()->Count());
+		/* The most recently added field is at the beginning of the set */
+		$this->assertEquals('Beginning', $composite->getChildren()->First()->getName());
+	}
+
 	public function testLegend() {
 		$composite = new CompositeField(
 			new TextField('A'),

tests/forms/FieldListTest.php

@@ -374,6 +374,37 @@ class FieldListTest extends SapphireTest {
 		$this->assertEquals(3, $fields->Count());
 	}
 
+	/**
+	 * Test pushing a field to the beginning of a set.
+	 *
+	 * This tests {@link FieldList->unshift()}.
+	 */
+	public function testPushFieldToBeginningOfSet() {
+		$fields = new FieldList();
+
+		/* A field named Country is added to the set */
+		$fields->unshift(new TextField('Country'));
+
+		/* We only have 1 field in the set */
+		$this->assertEquals(1, $fields->Count());
+
+		/* Another field called Email is added to the set */
+		$fields->unshift(new EmailField('Email'));
+
+		/* There are now 2 fields in the set */
+		$this->assertEquals(2, $fields->Count());
+
+		/* The most recently added field is at the beginning of the set */
+		$this->assertEquals('Email', $fields->First()->getName());
+
+		// Test that pushing a composite field without a name onto the set works
+		$fields->unshift(new CompositeField(
+			new TextField('Test1'),
+			new TextField('Test2')
+		));
+		$this->assertEquals(3, $fields->Count());
+	}
+
 	/**
 	 * Test inserting a field before another in a set.
 	 *