PHPOffice#266: Ability to add textinput, checkbox, and dropdown form elements

Author: ivanlanin

CHANGELOG.md

@@ -4,7 +4,7 @@ This is the changelog between releases of PHPWord. Releases are listed in revers
 
 ## 0.12.0 - Not yet released
 
-This release added drawing shapes (arc, curve, line, polyline, rect, oval) and basic 2D chart (pie, doughnut, bar, line, area, scatter, radar) elements along with some new styles.
+This release added form fields (textinput, checkbox, and dropdown), drawing shapes (arc, curve, line, polyline, rect, oval), and basic 2D chart (pie, doughnut, bar, line, area, scatter, radar) elements along with some new styles.
 
 ### Features
 
@@ -17,6 +17,7 @@ This release added drawing shapes (arc, curve, line, polyline, rect, oval) and b
 - General: New `Shared\Converter` static class - @ivanlanin
 - Chart: Basic 2D chart (pie, doughnut, bar, line, area, scatter, radar) - @ivanlanin GH-278
 - Chart: 3D charts and ability to set width and height - @ivanlanin
+- FormField: Ability to add textinput, checkbox, and dropdown form elements - @ivanlanin GH-266
 
 ### Bugfixes
 

README.md

@@ -32,6 +32,7 @@ With PHPWord, you can create DOCX, ODT, or RTF documents dynamically using your
 - Insert footnotes and endnotes
 - Insert drawing shapes (arc, curve, line, polyline, rect, oval)
 - Insert charts (pie, doughnut, bar, line, area, scatter, radar)
+- Insert form fields (textinput, checkbox, and dropdown)
 - Create document from templates
 - Use XSL 1.0 style sheets to transform main document part of OOXML template
 - ... and many more features on progress

docs/elements.rst

@@ -51,6 +51,8 @@ column shows the containers while the rows lists the elements.
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 | 21    | Chart           | v         | -        | -        | -       | -          | -          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
+| 22    | Form fields     | v         | v        | v        | v       | v          | v          |
++-------+-----------------+-----------+----------+----------+---------+------------+------------+
 
 Legend:
 
@@ -406,3 +408,8 @@ Charts
 ------
 
 To be completed.
+
+Form fields
+-----------
+
+To be completed.

docs/intro.rst

@@ -47,6 +47,7 @@ Features
 -  Insert footnotes and endnotes
 -  Insert drawing shapes (arc, curve, line, polyline, rect, oval)
 -  Insert charts (pie, doughnut, bar, line, area, scatter, radar)
+-  Insert form fields (textinput, checkbox, and dropdown)
 -  Create document from templates
 -  Use XSL 1.0 style sheets to transform main document part of OOXML
    template

docs/src/documentation.md

@@ -38,6 +38,7 @@ Don't forget to change `code::` directive to `code-block::` in the resulting rst
     - [Lines](#lines)
     - [Shapes](#shapes)
     - [Charts](#charts)
+    - [FormFields](#form-fields)
 - [Styles](#styles)
     - [Section](#section)
     - [Font](#font)
@@ -79,6 +80,7 @@ PHPWord is an open source project licensed under the terms of [LGPL version 3](h
 - Insert footnotes and endnotes
 - Insert drawing shapes (arc, curve, line, polyline, rect, oval)
 - Insert charts (pie, doughnut, bar, line, area, scatter, radar)
+- Insert form fields (textinput, checkbox, and dropdown)
 - Create document from templates
 - Use XSL 1.0 style sheets to transform main document part of OOXML template
 - ... and many more features on progress
@@ -444,6 +446,7 @@ Below are the matrix of element availability in each container. The column shows
 | 19  | Line          | v       | v      | v      | v    | v        | v        |
 | 20  | Shape         | v       | v      | v      | v    | v        | v        |
 | 21  | Chart         | v       | -      | -      | -    | -        | -        |
+| 22  | Form Fields   | v       | v      | v      | v    | v        | v        |
 
 Legend:
 
@@ -745,6 +748,10 @@ To be completed.
 
 To be completed.
 
+## Form fields
+
+To be completed.
+
 # Styles
 
 ## Section

samples/Sample_33_FormField.php

@@ -0,0 +1,26 @@
+<?php
+include_once 'Sample_Header.php';
+
+// New Word document
+echo date('H:i:s'), " Create new PhpWord object", EOL;
+$phpWord = new \PhpOffice\PhpWord\PhpWord();
+
+$section = $phpWord->addSection();
+
+$textrun = $section->addTextRun();
+$textrun->addText('Form fields can be added in a text run and can be in form of textinput ');
+$textrun->addFormField('textinput')->setName('MyTextBox');
+$textrun->addText(', checkbox ');
+$textrun->addFormField('checkbox')->setDefault(true);
+$textrun->addText(', or dropdown ');
+$textrun->addFormField('dropdown')->setEntries(array('Choice 1', 'Choice 2', 'Choice 3'));
+$textrun->addText('. You have to set document protection to "forms" to enable dropdown.');
+
+$section->addText('They can also be added as a stand alone paragraph.');
+$section->addFormField('textinput')->setValue('Your name');
+
+// Save file
+echo write($phpWord, basename(__FILE__, '.php'), $writers);
+if (!CLI) {
+    include_once 'Sample_Footer.php';
+}

src/PhpWord/Element/AbstractContainer.php

@@ -41,7 +41,8 @@
  * @method Field addField(string $type = null, array $properties = array(), array $options = array())
  * @method Line addLine(mixed $lineStyle = null)
  * @method Shape addObject(string $type, mixed $style = null)
- * @method Chart addChart()
+ * @method Chart addChart(string $type, array $categories, array $values, array $style = null)
+ * @method FormField addFormField(string $type, mixed $fStyle = null, mixed $pStyle = null)
  *
  * @since 0.10.0
  */
@@ -78,7 +79,7 @@ public function __call($function, $args)
         $elements = array('Text', 'TextRun', 'Link', 'PreserveText', 'TextBreak',
             'ListItem', 'ListItemRun', 'Table', 'Image', 'Object', 'Footnote',
             'Endnote', 'CheckBox', 'TextBox', 'Field', 'Line', 'Shape',
-            'Title', 'TOC', 'PageBreak', 'Chart');
+            'Title', 'TOC', 'PageBreak', 'Chart', 'FormField');
         $functions = array();
         for ($i = 0; $i < count($elements); $i++) {
             $functions[$i] = 'add' . $elements[$i];
@@ -190,6 +191,7 @@ private function checkValidity($method)
             'Field'         => $allContainers,
             'Line'          => $allContainers,
             'Shape'         => $allContainers,
+            'FormField'     => $allContainers,
             'TextRun'       => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
             'ListItem'      => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
             'ListItemRun'   => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),

src/PhpWord/Element/Chart.php

@@ -19,7 +19,6 @@
 
 use PhpOffice\PhpWord\Style\Chart as ChartStyle;
 
-
 /**
  * Chart element
  *
@@ -61,6 +60,7 @@ class Chart extends AbstractElement
      * @param string $type
      * @param array $categories
      * @param array $values
+     * @param array $style
      */
     public function __construct($type, $categories, $values, $style = null)
     {

src/PhpWord/Element/CheckBox.php

@@ -21,6 +21,8 @@
 
 /**
  * Check box element
+ *
+ * @since 0.10.0
  */
 class CheckBox extends Text
 {

src/PhpWord/Element/FormField.php

@@ -0,0 +1,195 @@
+<?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
+ */
+
+namespace PhpOffice\PhpWord\Element;
+
+/**
+ * Form field element
+ *
+ * @since 0.12.0
+ * @link http://www.datypic.com/sc/ooxml/t-w_CT_FFData.html
+ */
+class FormField extends Text
+{
+    /**
+     * Form field type: textinput|checkbox|dropdown
+     *
+     * @var string
+     */
+    private $type = 'textinput';
+
+    /**
+     * Form field name
+     *
+     * @var string
+     */
+    private $name;
+
+    /**
+     * Default value
+     *
+     * - TextInput: string
+     * - CheckBox: bool
+     * - DropDown: int Index of entries (zero based)
+     *
+     * @var string|bool|int
+     */
+    private $default;
+
+    /**
+     * Value
+     *
+     * @var string|bool|int
+     */
+    private $value;
+
+    /**
+     * Dropdown entries
+     *
+     * @var array
+     */
+    private $entries = array();
+
+    /**
+     * Create new instance
+     *
+     * @param string $type
+     * @param mixed $fontStyle
+     * @param mixed $paragraphStyle
+     * @return self
+     */
+    public function __construct($type, $fontStyle = null, $paragraphStyle = null)
+    {
+        $this->setType($type);
+    }
+
+    /**
+     * Get type
+     *
+     * @return string
+     */
+    public function getType()
+    {
+        return $this->type;
+    }
+
+    /**
+     * Set type
+     *
+     * @param string $value
+     * @return self
+     */
+    public function setType($value)
+    {
+        $enum = array('textinput', 'checkbox', 'dropdown');
+        $this->type = $this->setEnumVal($value, $enum, $this->type);
+
+        return $this;
+    }
+
+    /**
+     * Get name
+     *
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    /**
+     * Set name
+     *
+     * @param string|bool|int $value
+     * @return self
+     */
+    public function setName($value)
+    {
+        $this->name = $value;
+
+        return $this;
+    }
+
+    /**
+     * Get default
+     *
+     * @return string|bool|int
+     */
+    public function getDefault()
+    {
+        return $this->default;
+    }
+
+    /**
+     * Set default
+     *
+     * @param string|bool|int $value
+     * @return self
+     */
+    public function setDefault($value)
+    {
+        $this->default = $value;
+
+        return $this;
+    }
+
+    /**
+     * Get value
+     *
+     * @return string|bool|int
+     */
+    public function getValue()
+    {
+        return $this->value;
+    }
+
+    /**
+     * Set value
+     *
+     * @param string|bool|int $value
+     * @return self
+     */
+    public function setValue($value)
+    {
+        $this->value = $value;
+
+        return $this;
+    }
+
+    /**
+     * Get entries
+     *
+     * @return array
+     */
+    public function getEntries()
+    {
+        return $this->entries;
+    }
+
+    /**
+     * Set entries
+     *
+     * @param array $value
+     * @return self
+     */
+    public function setEntries($value)
+    {
+        $this->entries = $value;
+
+        return $this;
+    }
+}