Add support for XE and INDEX fields (#922)

docs/elements.rst

@@ -377,7 +377,35 @@ To be completed
 Fields
 ------
 
-To be completed
+Currently the following fields are supported: 
+
+- PAGE
+- NUMPAGES
+- DATE
+- XE
+- INDEX
+
+.. code-block:: php
+
+    $section->addField($fieldType, [$properties], [$options], [$fieldText])
+
+See ``\PhpOffice\PhpWord\Element\Field`` for list of properties and options available for each field type.
+Options which are not specifically defined can be added. Those must start with a ``\``.
+
+For instance for the INDEX field, you can do the following (See `Index Field for list of available options <https://support.office.com/en-us/article/Field-codes-Index-field-adafcf4a-cb30-43f6-85c7-743da1635d9e?ui=en-US&rs=en-US&ad=US>`_ ):
+
+.. code-block:: php
+
+    //the $fieldText can be either a simple string
+    $fieldText = 'The index value';
+
+    //or a 'TextRun', to be able to format the text you want in the index
+    $fieldText = new TextRun();
+    $fieldText->addText('My ');
+    $fieldText->addText('bold index', ['bold' => true]);
+    $fieldText->addText(' entry');
+
+    $section->addField('INDEX', array(), array('\\e "	" \\h "A" \\c "3"'), $fieldText);
 
 Line
 ------

samples/Sample_27_Field.php

@@ -1,4 +1,6 @@
 <?php
+use PhpOffice\PhpWord\Element\TextRun;
+
 include_once 'Sample_Header.php';
 
 // New Word document
@@ -14,10 +16,28 @@ $section->addText('Date field:');
 $section->addField('DATE', array('dateformat' => 'dddd d MMMM yyyy H:mm:ss'), array('PreserveFormat'));
 
 $section->addText('Page field:');
-$section->addField('PAGE', array('format' => 'ArabicDash'));
+$section->addField('PAGE', array('format' => 'Arabic'));
 
 $section->addText('Number of pages field:');
-$section->addField('NUMPAGES', array('format' => 'Arabic', 'numformat' => '0,00'), array('PreserveFormat'));
+$section->addField('NUMPAGES', array('numformat' => '0,00', 'format' => 'Arabic'), array('PreserveFormat'));
+
+$textrun = $section->addTextRun();
+$textrun->addText('An index field is ');
+$textrun->addField('XE', array(), array('Italic'), 'My first index');
+$textrun->addText('here:');
+
+$indexEntryText = new TextRun();
+$indexEntryText->addText('My ');
+$indexEntryText->addText('bold index', ['bold' => true]);
+$indexEntryText->addText(' entry');
+
+$textrun = $section->addTextRun();
+$textrun->addText('A complex index field is ');
+$textrun->addField('XE', array(), array('Bold'), $indexEntryText);
+$textrun->addText('here:');
+
+$section->addText('The actual index:');
+$section->addField('INDEX', array(), array('\\e "	"'), 'right click to update the index');
 
 $textrun = $section->addTextRun(array('alignment' => \PhpOffice\PhpWord\SimpleType\Jc::CENTER));
 $textrun->addText('This is the date of lunar calendar ');

src/PhpWord/Element/AbstractContainer.php

@@ -39,7 +39,7 @@ namespace PhpOffice\PhpWord\Element;
  * @method Image addImage(string $source, mixed $style = null, bool $isWatermark = false)
  * @method Object addObject(string $source, mixed $style = null)
  * @method TextBox addTextBox(mixed $style = null)
- * @method Field addField(string $type = null, array $properties = array(), array $options = array())
+ * @method Field addField(string $type = null, array $properties = array(), array $options = array(), mixed $text = null)
  * @method Line addLine(mixed $lineStyle = null)
  * @method Shape addShape(string $type, mixed $style = null)
  * @method Chart addChart(string $type, array $categories, array $values, array $style = null)

src/PhpWord/Element/Field.php

@@ -40,7 +40,8 @@ class Field extends AbstractElement
         ),
         'NUMPAGES'=>array(
            'properties'=>array(
-               'format' => array('Arabic', 'ArabicDash', 'alphabetic', 'ALPHABETIC', 'roman', 'ROMAN'),
+               'format' => array('Arabic', 'ArabicDash', 'CardText', 'DollarText', 'Ordinal', 'OrdText',
+                   'alphabetic', 'ALPHABETIC', 'roman', 'ROMAN', 'Caps', 'FirstCap', 'Lower', 'Upper'),
                'numformat' => array('0', '0,00', '#.##0', '#.##0,00', '€ #.##0,00(€ #.##0,00)', '0%', '0,00%')
            ),
            'options'=>array('PreserveFormat')
@@ -52,6 +53,14 @@ class Field extends AbstractElement
                     'h:mm am/pm', 'h:mm:ss am/pm', 'HH:mm', 'HH:mm:ss')
             ),
             'options'=>array('PreserveFormat', 'LunarCalendar', 'SakaEraCalendar', 'LastUsedFormat')
+        ),
+        'XE'=>array(
+            'properties' => array(),
+            'options' => array('Bold', 'Italic')
+        ),
+        'INDEX'=>array(
+            'properties' => array(),
+            'options' => array('PreserveFormat')
         )
     );
 
@@ -62,6 +71,13 @@ class Field extends AbstractElement
      */
     protected $type;
 
+    /**
+     * Field text
+     *
+     * @var TextRun | string
+     */
+    protected $text;
+
     /**
      * Field properties
      *
@@ -82,12 +98,14 @@ class Field extends AbstractElement
      * @param string $type
      * @param array $properties
      * @param array $options
+     * @param TextRun | string $text
      */
-    public function __construct($type = null, $properties = array(), $options = array())
+    public function __construct($type = null, $properties = array(), $options = array(), $text = null)
     {
         $this->setType($type);
         $this->setProperties($properties);
         $this->setOptions($options);
+        $this->setText($text);
     }
 
     /**
@@ -105,7 +123,7 @@ class Field extends AbstractElement
             if (isset($this->fieldsArray[$type])) {
                 $this->type = $type;
             } else {
-                throw new \InvalidArgumentException("Invalid type");
+                throw new \InvalidArgumentException("Invalid type '$type'");
             }
         }
         return $this->type;
@@ -135,7 +153,7 @@ class Field extends AbstractElement
         if (is_array($properties)) {
             foreach (array_keys($properties) as $propkey) {
                 if (!(isset($this->fieldsArray[$this->type]['properties'][$propkey]))) {
-                    throw new \InvalidArgumentException("Invalid property");
+                    throw new \InvalidArgumentException("Invalid property '$propkey'");
                 }
             }
             $this->properties = array_merge($this->properties, $properties);
@@ -166,8 +184,8 @@ class Field extends AbstractElement
     {
         if (is_array($options)) {
             foreach (array_keys($options) as $optionkey) {
-                if (!(isset($this->fieldsArray[$this->type]['options'][$optionkey]))) {
+                if (!(isset($this->fieldsArray[$this->type]['options'][$optionkey])) && substr($optionkey, 0, 1) !== '\\') {
-                    throw new \InvalidArgumentException("Invalid option");
+                    throw new \InvalidArgumentException("Invalid option '$optionkey', possible values are " . implode(', ', $this->fieldsArray[$this->type]['options']));
                 }
             }
             $this->options = array_merge($this->options, $options);
@@ -184,4 +202,35 @@ class Field extends AbstractElement
     {
         return $this->options;
     }
+
+    /**
+     * Set Field text
+     *
+     * @param string | TextRun $text
+     *
+     * @return string | TextRun
+     * 
+     * @throws \InvalidArgumentException
+     */
+    public function setText($text)
+    {
+        if (isset($text)) {
+            if (is_string($text) || $text instanceof TextRun) {
+                $this->text = $text;
+            } else {
+                throw new \InvalidArgumentException("Invalid text");
+            }
+        }
+        return $this->text;
+    }
+
+    /**
+     * Get Field text
+     *
+     * @return string | TextRun
+     */
+    public function getText()
+    {
+        return $this->text;
+    }
 }

src/PhpWord/Writer/Word2007/Element/Field.php

@@ -37,16 +37,90 @@ class Field extends Text
             return;
         }
 
+        $this->startElementP();
+
+        $xmlWriter->startElement('w:r');
+        $xmlWriter->startElement('w:fldChar');
+        $xmlWriter->writeAttribute('w:fldCharType', 'begin');
+        $xmlWriter->endElement(); // w:fldChar
+        $xmlWriter->endElement(); // w:r
+
         $instruction = ' ' . $element->getType() . ' ';
+        if ($element->getText() != null) {
+            if (is_string($element->getText())) {
+                $instruction .= '"' . $element->getText() . '" ';
+                $instruction .= $this->buildPropertiesAndOptions($element);
+            } else {
+                $instruction .= '"';
+            }
+        } else {
+            $instruction .= $this->buildPropertiesAndOptions($element);
+        }
+        $xmlWriter->startElement('w:r');
+        $xmlWriter->startElement('w:instrText');
+        $xmlWriter->writeAttribute('xml:space', 'preserve');
+        $xmlWriter->text($instruction);
+        $xmlWriter->endElement(); // w:instrText
+        $xmlWriter->endElement(); // w:r
+
+        if ($element->getText() != null) {
+            if ($element->getText() instanceof \PhpOffice\PhpWord\Element\TextRun) {
+
+                $containerWriter = new Container($xmlWriter, $element->getText(), true);
+                $containerWriter->write();
+
+                $xmlWriter->startElement('w:r');
+                $xmlWriter->startElement('w:instrText');
+                $xmlWriter->text('"' . $this->buildPropertiesAndOptions($element));
+                $xmlWriter->endElement(); // w:instrText
+                $xmlWriter->endElement(); // w:r
+
+                $xmlWriter->startElement('w:r');
+                $xmlWriter->startElement('w:instrText');
+                $xmlWriter->writeAttribute('xml:space', 'preserve');
+                $xmlWriter->text(' ');
+                $xmlWriter->endElement(); // w:instrText
+                $xmlWriter->endElement(); // w:r
+            }
+        }
+
+        $xmlWriter->startElement('w:r');
+        $xmlWriter->startElement('w:fldChar');
+        $xmlWriter->writeAttribute('w:fldCharType', 'separate');
+        $xmlWriter->endElement(); // w:fldChar
+        $xmlWriter->endElement(); // w:r
+
+        $xmlWriter->startElement('w:r');
+        $xmlWriter->startElement('w:rPr');
+        $xmlWriter->startElement('w:noProof');
+        $xmlWriter->endElement(); // w:noProof
+        $xmlWriter->endElement(); // w:rPr
+        $xmlWriter->writeElement('w:t', $element->getText() != null && is_string($element->getText()) ? $element->getText() : '1');
+        $xmlWriter->endElement(); // w:r
+
+        $xmlWriter->startElement('w:r');
+        $xmlWriter->startElement('w:fldChar');
+        $xmlWriter->writeAttribute('w:fldCharType', 'end');
+        $xmlWriter->endElement(); // w:fldChar
+        $xmlWriter->endElement(); // w:r
+
+        $this->endElementP(); // w:p
+    }
+
+    private function buildPropertiesAndOptions(\PhpOffice\PhpWord\Element\Field $element)
+    {
+        $propertiesAndOptions = '';
         $properties  = $element->getProperties();
         foreach ($properties as $propkey => $propval) {
             switch ($propkey) {
                 case 'format':
+                    $propertiesAndOptions.= '\* ' . $propval . ' ';
+                    break;
                 case 'numformat':
-                    $instruction .= '\* ' . $propval . ' ';
+                    $propertiesAndOptions.= '\# ' . $propval . ' ';
                     break;
                 case 'dateformat':
-                    $instruction .= '\@ "' . $propval . '" ';
+                    $propertiesAndOptions.= '\@ "' . $propval . '" ';
                     break;
             }
         }
@@ -55,34 +129,27 @@ class Field extends Text
         foreach ($options as $option) {
             switch ($option) {
                 case 'PreserveFormat':
-                    $instruction .= '\* MERGEFORMAT ';
+                    $propertiesAndOptions.= '\* MERGEFORMAT ';
                     break;
                 case 'LunarCalendar':
-                    $instruction .= '\h ';
+                    $propertiesAndOptions.= '\h ';
                     break;
                 case 'SakaEraCalendar':
-                    $instruction .= '\s ';
+                    $propertiesAndOptions.= '\s ';
                     break;
                 case 'LastUsedFormat':
-                    $instruction .= '\l ';
+                    $propertiesAndOptions.= '\l ';
                     break;
+                case 'Bold':
+                    $propertiesAndOptions.= '\b ';
+                    break;
+                case 'Italic':
+                    $propertiesAndOptions.= '\i ';
+                    break;
+                default:
+                    $propertiesAndOptions.= $option .' ';
             }
         }
-
+        return $propertiesAndOptions;
-        $this->startElementP();
-
-        $xmlWriter->startElement('w:fldSimple');
-        $xmlWriter->writeAttribute('w:instr', $instruction);
-        $xmlWriter->startElement('w:r');
-        $xmlWriter->startElement('w:rPr');
-        $xmlWriter->startElement('w:noProof');
-        $xmlWriter->endElement(); // w:noProof
-        $xmlWriter->endElement(); // w:rPr
-
-        $xmlWriter->writeElement('w:t', '1');
-        $xmlWriter->endElement(); // w:r
-        $xmlWriter->endElement(); // w:fldSimple
-
-        $this->endElementP(); // w:p
     }
 }

tests/PhpWord/Element/FieldTest.php

@@ -70,6 +70,47 @@ class FieldTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals(array('SakaEraCalendar', 'PreserveFormat'), $oField->getOptions());
     }
 
+    /**
+     * New instance with type and properties and options and text
+     */
+    public function testConstructWithTypePropertiesOptionsText()
+    {
+        $oField = new Field('XE', array(), array('Bold', 'Italic'), 'FieldValue');
+
+        $this->assertInstanceOf('PhpOffice\\PhpWord\\Element\\Field', $oField);
+        $this->assertEquals('XE', $oField->getType());
+        $this->assertEquals(array(), $oField->getProperties());
+        $this->assertEquals(array('Bold', 'Italic'), $oField->getOptions());
+        $this->assertEquals('FieldValue', $oField->getText());
+    }
+
+    /**
+     * New instance with type and properties and options and text as TextRun
+     */
+    public function testConstructWithTypePropertiesOptionsTextAsTextRun()
+    {
+        $textRun = new TextRun();
+        $textRun->addText('test string');
+
+        $oField = new Field('XE', array(), array('Bold', 'Italic'), $textRun);
+
+        $this->assertInstanceOf('PhpOffice\\PhpWord\\Element\\Field', $oField);
+        $this->assertEquals('XE', $oField->getType());
+        $this->assertEquals(array(), $oField->getProperties());
+        $this->assertEquals(array('Bold', 'Italic'), $oField->getOptions());
+        $this->assertInstanceOf('PhpOffice\\PhpWord\\Element\\TextRun', $oField->getText());
+    }
+
+    public function testConstructWithOptionValue()
+    {
+        $oField = new Field('INDEX', array(), array('\\c "3" \\h "A"'));
+
+        $this->assertInstanceOf('PhpOffice\\PhpWord\\Element\\Field', $oField);
+        $this->assertEquals('INDEX', $oField->getType());
+        $this->assertEquals(array(), $oField->getProperties());
+        $this->assertEquals(array('\\c "3" \\h "A"'), $oField->getOptions());
+    }
+
     /**
      * Test setType exception
      *
@@ -105,4 +146,16 @@ class FieldTest extends \PHPUnit_Framework_TestCase
         $object = new Field('PAGE');
         $object->setOptions(array('foo' => 'bar'));
     }
+
+    /**
+     * Test setText exception
+     *
+     * @expectedException \InvalidArgumentException
+     * @expectedExceptionMessage Invalid text
+     */
+    public function testSetTextException()
+    {
+        $object = new Field('XE');
+        $object->setText(array());
+    }
 }

tests/PhpWord/Writer/Word2007/ElementTest.php

@@ -19,6 +19,7 @@ namespace PhpOffice\PhpWord\Writer\Word2007;
 use PhpOffice\Common\XMLWriter;
 use PhpOffice\PhpWord\PhpWord;
 use PhpOffice\PhpWord\TestHelperDOCX;
+use PhpOffice\PhpWord\Element\TextRun;
 
 /**
  * Test class for PhpOffice\PhpWord\Writer\Word2007\Element subnamespace
@@ -192,6 +193,51 @@ class ElementTest extends \PHPUnit_Framework_TestCase
         }
     }
 
+    public function testFieldElement()
+    {
+        $phpWord = new PhpWord();
+        $section = $phpWord->addSection();
+
+        $section->addField('INDEX', array(), array('\\c "3"'));
+        $section->addField('XE', array(), array('Bold', 'Italic'), 'Index Entry');
+        $section->addField('DATE', array('dateformat' => 'd-M-yyyy'), array('PreserveFormat', 'LastUsedFormat'));
+        $section->addField('DATE', array(), array('LunarCalendar'));
+        $section->addField('DATE', array(), array('SakaEraCalendar'));
+        $section->addField('NUMPAGES', array('format' => 'roman', 'numformat' => '0,00'), array('SakaEraCalendar'));
+        $doc = TestHelperDOCX::getDocument($phpWord);
+
+        $element = '/w:document/w:body/w:p/w:r/w:instrText';
+        $this->assertTrue($doc->elementExists($element));
+        $this->assertEquals(' INDEX \\c "3" ', $doc->getElement($element)->textContent);
+    }
+
+    public function testFieldElementWithComplexText()
+    {
+        $phpWord = new PhpWord();
+        $section = $phpWord->addSection();
+
+        $text = new TextRun();
+        $text->addText('test string', array('bold' => true));
+
+        $section->addField('XE', array(), array('Bold', 'Italic'), $text);
+        $doc = TestHelperDOCX::getDocument($phpWord);
+
+        $element = '/w:document/w:body/w:p/w:r[2]/w:instrText';
+        $this->assertTrue($doc->elementExists($element));
+        $this->assertEquals(' XE "', $doc->getElement($element)->textContent);
+
+        $element = '/w:document/w:body/w:p/w:r[3]/w:rPr/w:b';
+        $this->assertTrue($doc->elementExists($element));
+
+        $element = '/w:document/w:body/w:p/w:r[3]/w:t';
+        $this->assertTrue($doc->elementExists($element));
+        $this->assertEquals('test string', $doc->getElement($element)->textContent);
+
+        $element = '/w:document/w:body/w:p/w:r[4]/w:instrText';
+        $this->assertTrue($doc->elementExists($element));
+        $this->assertEquals('"\\b \\i ', $doc->getElement($element)->textContent);
+    }
+
     /**
      * Test form fields
      */