Update changelog, docs, and unit tests for new Field element #251

ivanlanin · ivanlanin · commit e81d92e26529 · 2014-05-29T16:25:39.000+07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,16 +4,15 @@ This is the changelog between releases of PHPWord. Releases are listed in revers
 
 ## 0.11.0 - Not yet released
 
-This release marked the change of PHPWord license from LGPL 2.1 to LGPL 3; new relative and absolute positioning for image; new `TextBox` and `ListItemRun` element; refactorings of writer classes into parts, elements, and styles; and ability to add elements to PHPWord object via HTML.
+This release marked the change of PHPWord license from LGPL 2.1 to LGPL 3. Three new elements were added: TextBox, ListItemRun, and Field. Relative and absolute positioning for images and textboxes were added. Writer classes were refactored into parts, elements, and styles. ODT and RTF features were enhanced. Ability to add elements to PHPWord object via HTML were implemeted.
 
 ### Features
 
 - Image: Ability to define relative and absolute positioning - @basjan GH-217
 - Footer: Conform footer with header by adding firstPage, evenPage and by inheritance - @basjan @ivanlanin GH-219
-- TextBox: Ability to add textbox in section, header, and footer - @basjan @ivanlanin GH-228 GH-229
-- TextBox: Ability to add table inside textbox - @basjan GH-231
+- Element: New `TextBox` element - @basjan @ivanlanin GH-228 GH-229 GH-231
 - HTML: Ability to add elements to PHPWord object via html - @basjan GH-231
-- ListItemRun: New element that can add a list item with inline formatting like a textrun - @basjan GH-235
+- Element: New `ListItemRun` element that can add a list item with inline formatting like a textrun - @basjan GH-235
 - Table: Ability to add table inside a cell (nested table) - @ivanlanin GH-149
 - RTF Writer: UTF8 support for RTF: Internal UTF8 text is converted to Unicode before writing - @ivanlanin GH-158
 - Table: Ability to define table width (in percent and twip) and position - @ivanlanin GH-237
@@ -30,6 +29,7 @@ This release marked the change of PHPWord license from LGPL 2.1 to LGPL 3; new r
 - Image: Enable "image float left" - @ivanlanin GH-244
 - RTF Writer: Ability to write document properties - @ivanlanin
 - RTF Writer: Ability to write image - @ivanlanin
+- Element: New `Field` element - @basjan GH-251
 
 ### Bugfixes
 
diff --git a/docs/elements.rst b/docs/elements.rst
@@ -17,7 +17,7 @@ column shows the containers while the rows lists the elements.
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 | 4     | Title           | v         | ?        | ?        | ?       | ?          | ?          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
-| 5     | Preserve Text   | ?         | v        | v        | v\*     | ?          | ?          |
+| 5     | Preserve Text   | ?         | v        | v        | v\*     | -          | -          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 | 6     | Text Break      | v         | v        | v        | v       | v          | v          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
@@ -39,7 +39,11 @@ column shows the containers while the rows lists the elements.
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 | 15    | Endnote         | v         | -        | -        | v\*\*   | v\*\*      | -          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
-| 16    | CheckBox        | v         | v        | v        | v       | ?          | ?          |
+| 16    | CheckBox        | v         | v        | v        | v       | -          | -          |
++-------+-----------------+-----------+----------+----------+---------+------------+------------+
+| 17    | TextBox         | v         | v        | v        | v       | -          | -          |
++-------+-----------------+-----------+----------+----------+---------+------------+------------+
+| 18    | Field           | v         | v        | v        | v       | v          | v          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 
 Legend:
@@ -473,3 +477,13 @@ Checkbox elements can be added to sections or table cells by using
 -  ``$text`` Text following the check box
 -  ``$fontStyle`` See "Font style" section.
 -  ``$paragraphStyle`` See "Paragraph style" section.
+
+Textboxes
+---------
+
+To be completed
+
+Fields
+------
+
+To be completed
diff --git a/docs/src/documentation.md b/docs/src/documentation.md
@@ -33,6 +33,8 @@ Don't forget to change `code::` directive to `code-block::` in the resulting rst
     - [Table of contents](#table-of-contents)
     - [Footnotes & endnotes](#footnotes-endnotes)
     - [Checkboxes](#checkboxes)
+    - [Textboxes](#textboxes)
+    - [Fields](#fields)
 - [Templates](#templates)
 - [Writers & readers](#writers-readers)
     - [OOXML](#ooxml)
@@ -447,7 +449,7 @@ Below are the matrix of element availability in each container. The column shows
 | 2   | Text Run      | v       | v      | v      | v    | -        | -        |
 | 3   | Link          | v       | v      | v      | v    | v        | v        |
 | 4   | Title         | v       | ?      | ?      | ?    | ?        | ?        |
-| 5   | Preserve Text | ?       | v      | v      | v*   | ?        | ?        |
+| 5   | Preserve Text | ?       | v      | v      | v*   | -        | -        |
 | 6   | Text Break    | v       | v      | v      | v    | v        | v        |
 | 7   | Page Break    | v       | -      | -      | -    | -        | -        |
 | 8   | List          | v       | v      | v      | v    | -        | -        |
@@ -458,7 +460,9 @@ Below are the matrix of element availability in each container. The column shows
 | 13  | TOC           | v       | -      | -      | -    | -        | -        |
 | 14  | Footnote      | v       | -      | -      | v**  | v**      | -        |
 | 15  | Endnote       | v       | -      | -      | v**  | v**      | -        |
-| 16  | CheckBox      | v       | v      | v      | v    | ?        | ?        |
+| 16  | CheckBox      | v       | v      | v      | v    | -        | -        |
+| 17  | TextBox       | v       | v      | v      | v    | -        | -        |
+| 18  | Field         | v       | v      | v      | v    | v        | v        |
 
 Legend:
 
@@ -832,6 +836,14 @@ $section->addCheckBox($name, $text, [$fontStyle], [$paragraphStyle])
 - `$fontStyle` See "Font style" section.
 - `$paragraphStyle` See "Paragraph style" section.
 
+## Textboxes
+
+To be completed.
+
+## Fields
+
+To be completed.
+
 # Templates
 
 You can create a docx template with included search-patterns that can be replaced by any value you wish. Only single-line values can be replaced. To load a template file, use the `loadTemplate` method. After loading the docx template, you can use the `setValue` method to change the value of a search pattern. The search-pattern model is: `${search-pattern}`. It is not possible to add new PHPWord elements to a loaded template file.
diff --git a/samples/Sample_27_Field.php b/samples/Sample_27_Field.php
@@ -10,10 +10,20 @@
 
 // Add Field elements
 // See Element/Field.php for all options
-$section->addField('DATE', array('dateformat'=>'d-M-yyyy H:mm:ss'), array('PreserveFormat', 'LunarCalendar'));
+$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->addText('Number of pages field:');
 $section->addField('NUMPAGES', array('format'=>'Arabic', 'numformat'=>'0,00'), array('PreserveFormat'));
 
+$textrun = $section->addTextRun(array('align' => 'center'));
+$textrun->addText('This is the date of lunar calendar ');
+$textrun->addField('DATE', array('dateformat'=>'d-M-yyyy H:mm:ss'), array('PreserveFormat', 'LunarCalendar'));
+$textrun->addText(' written in a textrun.');
+
 // Save file
 echo write($phpWord, basename(__FILE__, '.php'), $writers);
 if (!CLI) {
diff --git a/src/PhpWord/Element/AbstractContainer.php b/src/PhpWord/Element/AbstractContainer.php
@@ -145,14 +145,17 @@ public function addTextRun($paragraphStyle = null)
 
     /**
      * Add field element
-     * @param
+     *
+     * @param string $type
+     * @param array $properties
+     * @param array $options
      */
     public function addField($type = null, $properties = array(), $options = array())
     {
         return $this->addElement('Field', $type, $properties, $options);
-        
+
     }
-    
+
     /**
      * Add link element
      *
@@ -327,6 +330,7 @@ private function checkValidity($method)
             'TextBreak'     => $allContainers,
             'Image'         => $allContainers,
             'Object'        => $allContainers,
+            'Field'         => $allContainers,
             'TextRun'       => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
             'ListItem'      => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
             'ListItemRun'   => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
diff --git a/src/PhpWord/Element/Field.php b/src/PhpWord/Element/Field.php
@@ -1,35 +1,34 @@
 <?php
 /**
  * This file is part of PHPWord - A pure PHP library for reading and writing
-* word processing documents.
-*
-* PHPWord is free software distributed under the terms of the GNU Lesser
-* General Public License version 3 as published by the Free Software Foundation.
-*
-* For the full copyright and license information, please read the LICENSE
-* file that was distributed with this source code. For the full list of
-* contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
-*
-* @link        https://github.com/PHPOffice/PHPWord
-* @copyright   2010-2014 PHPWord contributors
-* @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
-*/
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License version 3 as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @link        https://github.com/PHPOffice/PHPWord
+ * @copyright   2010-2014 PHPWord contributors
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
 
 namespace PhpOffice\PhpWord\Element;
 
-use PhpOffice\PhpWord\Shared\String;
-
 /**
  * Field element
+ *
+ * @since 0.11.0
+ * @link http://www.schemacentral.com/sc/ooxml/t-w_CT_SimpleField.html
  */
 class Field extends AbstractElement
 {
-    
-    
     /**
      * Field properties and options. Depending on type, a field can have different properties
      * and options
-     * 
+     *
      * @var array
      */
     protected $fieldsArray = array(
@@ -55,7 +54,7 @@ class Field extends AbstractElement
             'options'=>array('PreserveFormat', 'LunarCalendar', 'SakaEraCalendar', 'LastUsedFormat')
         )
     );
-    
+
     /**
      * Field type
      *
@@ -81,8 +80,8 @@ class Field extends AbstractElement
      * Create a new Field Element
      *
      * @param string $type
-     * @param mixed $properties
-     * @param mixed $options
+     * @param array $properties
+     * @param array $options
      */
     public function __construct($type = null, $properties = array(), $options = array())
     {
@@ -94,7 +93,7 @@ public function __construct($type = null, $properties = array(), $options = arra
     /**
      * Set Field type
      *
-     * @param string
+     * @param string $type
      * @return string
      */
     public function setType($type = null)
@@ -122,18 +121,18 @@ public function getType()
     /**
      * Set Field properties
      *
-     * @param array
+     * @param array $properties
      * @return self
      */
     public function setProperties($properties = array())
     {
         if (is_array($properties)) {
             foreach (array_keys($properties) as $propkey) {
                 if (!(array_key_exists($propkey, $this->fieldsArray[$this->type]['properties']))) {
-                        throw new \InvalidArgumentException("Invalid property");
+                    throw new \InvalidArgumentException("Invalid property");
                 }
             }
-            $this->properties=array_merge($this->properties, $properties);
+            $this->properties = array_merge($this->properties, $properties);
         }
         return $this->properties;
     }
@@ -151,7 +150,7 @@ public function getProperties()
     /**
      * Set Field options
      *
-     * @param array
+     * @param array $options
      * @return self
      */
     public function setOptions($options = array())
@@ -162,11 +161,11 @@ public function setOptions($options = array())
                     throw new \InvalidArgumentException("Invalid option");
                 }
             }
-            $this->options=array_merge($this->options, $options);
+            $this->options = array_merge($this->options, $options);
         }
         return $this->options;
     }
-    
+
     /**
      * Get Field properties
      *
diff --git a/src/PhpWord/Writer/Word2007/Element/Field.php b/src/PhpWord/Writer/Word2007/Element/Field.php
@@ -20,7 +20,7 @@
 /**
  * Field element writer
  *
- * @since 0.10.0
+ * @since 0.11.0
  */
 class Field extends Text
 {
@@ -30,44 +30,43 @@ class Field extends Text
     public function write()
     {
         $xmlWriter = $this->getXmlWriter();
-        $element = $this->getElement();
+        $element   = $this->getElement();
         if (!$element instanceof \PhpOffice\PhpWord\Element\Field) {
             return;
         }
 
-        $instruction=' '.$element->getType().' ';
-        $properties=$element->getProperties();
+        $instruction = ' ' . $element->getType() . ' ';
+        $properties  = $element->getProperties();
         foreach ($properties as $propkey => $propval) {
             switch ($propkey) {
                 case 'format':
-                    $instruction.='\* '.$propval.' ';
-                    break;
                 case 'numformat':
-                    $instruction.='\* '.$propval.' ';
+                    $instruction .= '\* ' . $propval . ' ';
                     break;
                 case 'dateformat':
-                    $instruction.='\@ "'.$propval.'" ';
+                    $instruction .= '\@ "' . $propval . '" ';
                     break;
             }
         }
-        
-        $options=$element->getOptions();
+
+        $options = $element->getOptions();
         foreach ($options as $option) {
             switch ($option) {
                 case 'PreserveFormat':
-                    $instruction.='\* MERGEFORMAT ';
+                    $instruction .= '\* MERGEFORMAT ';
                     break;
                 case 'LunarCalendar':
-                    $instruction.='\h ';
+                    $instruction .= '\h ';
                     break;
                 case 'SakaEraCalendar':
-                    $instruction.='\s ';
+                    $instruction .= '\s ';
                     break;
                 case 'LastUsedFormat':
-                    $instruction.='\l ';
+                    $instruction .= '\l ';
                     break;
             }
         }
+
         $this->writeOpeningWP();
         $xmlWriter->startElement('w:fldSimple');
         $xmlWriter->writeAttribute('w:instr', $instruction);
@@ -76,7 +75,7 @@ public function write()
         $xmlWriter->startElement('w:noProof');
         $xmlWriter->endElement(); // w:noProof
         $xmlWriter->endElement(); // w:rPr
-        
+
         $xmlWriter->startElement('w:t');
         $xmlWriter->writeRaw('1');
         $xmlWriter->endElement(); // w:t
diff --git a/tests/PhpWord/Tests/Writer/Word2007/ElementTest.php b/tests/PhpWord/Tests/Writer/Word2007/ElementTest.php
@@ -30,7 +30,7 @@ public function testUnmatchedElements()
     {
         $elements = array(
             'CheckBox', 'Container', 'Footnote', 'Image', 'Link', 'ListItem', 'ListItemRun',
-            'Object', 'PreserveText', 'Table', 'Text', 'TextBox', 'TextBreak', 'Title', 'TOC'
+            'Object', 'PreserveText', 'Table', 'Text', 'TextBox', 'TextBreak', 'Title', 'TOC', 'Field'
         );
         foreach ($elements as $element) {
             $objectClass = 'PhpOffice\\PhpWord\\Writer\\Word2007\\Element\\' . $element;
diff --git a/tests/PhpWord/Tests/Writer/Word2007/Part/DocumentTest.php b/tests/PhpWord/Tests/Writer/Word2007/Part/DocumentTest.php
@@ -83,6 +83,10 @@ public function testElements()
             'innerMargin' => 10, 'borderSize' => 1, 'borderColor' => '#FF0'));
         $section->addTextBox(array('wrappingStyle' => 'tight', 'positioning' => 'absolute', 'align' => 'center'));
         $section->addListItemRun()->addText('List item run 1');
+        $section->addField('DATE', array('dateformat'=>'dddd d MMMM yyyy H:mm:ss'), array('PreserveFormat', 'LunarCalendar'));
+        $section->addField('DATE', array('dateformat'=>'dddd d MMMM yyyy H:mm:ss'), array('PreserveFormat', 'SakaEraCalendar'));
+        $section->addField('DATE', array('dateformat'=>'dddd d MMMM yyyy H:mm:ss'), array('PreserveFormat', 'LastUsedFormat'));
+        $section->addField('PAGE', array('format'=>'ArabicDash'));
 
         $doc = TestHelperDOCX::getDocument($phpWord);
 

Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ public function testUnmatchedElements()`
`30`	`30`	`{`
`31`	`31`	`$elements = array(`
`32`	`32`	`'CheckBox', 'Container', 'Footnote', 'Image', 'Link', 'ListItem', 'ListItemRun',`
`33`		`- 'Object', 'PreserveText', 'Table', 'Text', 'TextBox', 'TextBreak', 'Title', 'TOC'`
	`33`	`+ 'Object', 'PreserveText', 'Table', 'Text', 'TextBox', 'TextBreak', 'Title', 'TOC', 'Field'`
`34`	`34`	`);`
`35`	`35`	`foreach ($elements as $element) {`
`36`	`36`	`$objectClass = 'PhpOffice\\PhpWord\\Writer\\Word2007\\Element\\' . $element;`