Add support for whole-document FootnoteProperties

Also improves support of these properties for Endnotes.

Author: Michaël Dupont

docs/elements.rst

@@ -359,17 +359,21 @@ The footnote numbering can be controlled by setting the FootnoteProperties on th
 
 .. code-block:: php
 
-    $fp = new PhpWord\SimpleType\FootnoteProperties();
+    $fp = new \PhpOffice\PhpWord\ComplexType\FootnoteProperties();
     //sets the position of the footnote (pageBottom (default), beneathText, sectEnd, docEnd)
-    $fp->setPos(FootnoteProperties::POSITION_DOC_END);
+    $fp->setPos(\PhpOffice\PhpWord\ComplexType\FootnoteProperties::POSITION_BENEATH_TEXT);
     //set the number format to use (decimal (default), upperRoman, upperLetter, ...)
-    $fp->setNumFmt(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN);
+    $fp->setNumFmt(\PhpOffice\PhpWord\SimpleType\NumberFormat::LOWER_ROMAN);
     //force starting at other than 1
     $fp->setNumStart(2);
     //when to restart counting (continuous (default), eachSect, eachPage)
-    $fp->setNumRestart(FootnoteProperties::RESTART_NUMBER_EACH_PAGE);
+    $fp->setNumRestart(\PhpOffice\PhpWord\ComplexType\FootnoteProperties::RESTART_NUMBER_EACH_PAGE);
     //And finaly, set it on the Section
-    $section->setFootnoteProperties($properties);
+    $section->setFootnoteProperties($fp);
+
+To set endnote properties, use the ``setEndnoteProperties`` method instead.
+You can also use ``$phpWord->setDefaultFootnoteProperties()`` and ``$phpWord->setDefaultEndnoteProperties()``
+to set the properties for all the footnotes/endnotes in the document.
 
 Checkboxes
 ----------

docs/general.rst

@@ -141,6 +141,24 @@ default font by using the following two functions:
     $phpWord->setDefaultFontName('Times New Roman');
     $phpWord->setDefaultFontSize(12);
 
+Default footnote and endnote properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, footnotes are displayed at the bottom of the page, numbered continuously from 1.
+Endnotes are displayed at the end of the document, numbered continuously in lower roman numerals starting from 1.
+
+Default properties will apply to all footnotes and endnotes in the document, unless overriden at the section level.
+
+You can change the default properties using ``$phpWord->setDefaultFootnoteProperties()`` and ``$phpWord->setDefaultEndnoteProperties()``:
+
+.. code-block:: php
+
+    $defaultProperties = new \PhpOffice\PhpWord\ComplexType\FootnoteProperties();
+    $defaultProperties->setPos(\PhpOffice\PhpWord\ComplexType\FootnoteProperties::POSITION_SECTION_END);
+    $defaultProperties->setNumFmt(\PhpOffice\PhpWord\SimpleType\NumberFormat::ORDINAL);
+    $defaultProperties->setNumStart(4);
+    $phpWord->setDefaultEndnoteProperties($defaultProperties);
+
 Document settings
 -----------------
 Settings for the generated document can be set using ``$phpWord->getSettings()``

samples/Sample_41_FootnoteProperties.php

@@ -0,0 +1,100 @@
+<?php
+use PhpOffice\PhpWord\ComplexType\FootnoteProperties;
+use PhpOffice\PhpWord\SimpleType\NumberFormat;
+
+include_once 'Sample_Header.php';
+
+// New Word Document
+echo date('H:i:s'), ' Create new PhpWord object', EOL;
+$phpWord = new \PhpOffice\PhpWord\PhpWord();
+\PhpOffice\PhpWord\Settings::setCompatibility(false);
+
+$defaultFp = new FootnoteProperties();
+$defaultFp->setPos(FootnoteProperties::POSITION_BENEATH_TEXT);
+$defaultFp->setNumFmt(NumberFormat::DECIMAL);
+$defaultFp->setNumStart(3);
+$defaultFp->setNumRestart(FootnoteProperties::RESTART_NUMBER_CONTINUOUS);
+
+$phpWord->setDefaultFootnoteProperties($defaultFp);
+
+$defaultEp = new FootnoteProperties();
+$defaultEp->setPos(FootnoteProperties::POSITION_SECTION_END);
+$defaultEp->setNumFmt(NumberFormat::DECIMAL_ENCLOSED_CIRCLE);
+$defaultEp->setNumStart(8);
+$defaultEp->setNumRestart(FootnoteProperties::RESTART_NUMBER_CONTINUOUS);
+
+$phpWord->setDefaultEndnoteProperties($defaultEp);
+
+// First portrait section
+$section = $phpWord->addSection();
+
+$textrun = $section->addTextrun();
+$textrun->addText('This is some lead text in a paragraph with a following endnote and footnote. ');
+
+// First endnote, follows default properties.
+$endnote = $textrun->addEndnote();
+$endnote->addText('First endnote, should be on the second page, prefixed by a "8" enclosed in a circle.');
+
+// First footnote, follows default properties.
+$footnote = $textrun->addFootnote();
+$footnote->addText('First footnote, should be on the first page beneath the text, prefixed by a "3".');
+
+// Create a blank page before the next section
+$section->addPageBreak();
+$section->addPageBreak();
+
+// Second portrait section
+$section = $phpWord->addSection();
+
+// Custom endnote properties for this section
+$ep = new FootnoteProperties();
+$ep->setPos(FootnoteProperties::POSITION_DOC_END);
+$ep->setNumFmt(NumberFormat::DECIMAL_ZERO);
+$ep->setNumStart(2);
+$ep->setNumRestart(FootnoteProperties::RESTART_NUMBER_EACH_SECTION);
+
+// Custom footnote properties for this section
+$fp = new FootnoteProperties();
+$fp->setPos(FootnoteProperties::POSITION_PAGE_BOTTOM);
+$fp->setNumFmt(NumberFormat::ORDINAL_TEXT);
+$fp->setNumStart(6);
+$fp->setNumRestart(FootnoteProperties::RESTART_NUMBER_EACH_PAGE);
+
+$section->setEndnoteProperties($ep);
+$section->setFootnoteProperties($fp);
+
+$textrun = $section->addTextrun();
+$textrun->addText('Second section on a new page with some text followed by an endnote and a footnote. ');
+
+// Second endnote, follows custom properties
+$endnote = $textrun->addEndnote();
+$endnote->addText('Second endnote, should be on the third page at the end of the section
+– even though we told it to be at the end of the document, endnotes only obey default positioning –,
+prefixed by "01" – even though we told it to start at 2, the NumRestart value (each section) resets it to 1.');
+
+// Second footnote, follows custom properties
+$footnote = $textrun->addFootnote();
+$footnote->addText('Second footnote, should be at the bottom of the third page, prefixed by "First"
+– even though we told it to start at 6, the NumRestart value (each page), resets it to 1.');
+
+// Third portrait section
+$section = $phpWord->addSection();
+
+$textrun = $section->addTextrun();
+$textrun->addText('Third and last section, with an endnote and a footnote. ');
+
+// Third endnote, follows default properties
+$endnote = $textrun->addEndnote();
+$endnote->addText('Third endnote, should be at the bottom of the last section, prefixed by a "10" enclosed in a circle
+– note that the previous endnote was counted as part of the continuation, so "10" is displayed, not "9".');
+
+// Third footnote, follows default properties
+$footnote = $textrun->addFootnote();
+$footnote->addText('Third footnote, should be beneath the text on the last page, prefixed by a "5"
+– note that the previous endnote was counted as part of the continuation, so "5" is displayed, not "4".');
+
+// Save file
+echo write($phpWord, basename(__FILE__, '.php'), $writers);
+if (!CLI) {
+    include_once 'Sample_Footer.php';
+}

src/PhpWord/Element/Section.php

@@ -55,6 +55,13 @@ class Section extends AbstractContainer
      */
     private $footnoteProperties;
 
+    /**
+     * The properties for the endnote of this section
+     *
+     * @var FootnoteProperties
+     */
+    private $endnoteProperties;
+
     /**
      * Create new instance
      *
@@ -146,6 +153,18 @@ public function getFooters()
      *
      * @return FootnoteProperties
      */
+    public function getFootnoteProperties()
+    {
+        return $this->footnoteProperties;
+    }
+
+    /**
+     * Get the footnote properties
+     *
+     * @deprecated Use the `getFootnoteProperties` method instead
+     *
+     * @return FootnoteProperties
+     */
     public function getFootnotePropoperties()
     {
         return $this->footnoteProperties;
@@ -161,6 +180,26 @@ public function setFootnoteProperties(FootnoteProperties $footnoteProperties = n
         $this->footnoteProperties = $footnoteProperties;
     }
 
+    /**
+     * Get the endnote properties
+     *
+     * @return FootnoteProperties
+     */
+    public function getEndnoteProperties()
+    {
+        return $this->endnoteProperties;
+    }
+
+    /**
+     * Set the endnote properties
+     *
+     * @param FootnoteProperties $endnoteProperties
+     */
+    public function setEndnoteProperties(FootnoteProperties $endnoteProperties = null)
+    {
+        $this->endnoteProperties = $endnoteProperties;
+    }
+
     /**
      * Is there a header for this section that is for the first page only?
      *

src/PhpWord/PhpWord.php

@@ -17,6 +17,7 @@
 
 namespace PhpOffice\PhpWord;
 
+use PhpOffice\PhpWord\ComplexType\FootnoteProperties;
 use PhpOffice\PhpWord\Element\Section;
 use PhpOffice\PhpWord\Exception\Exception;
 
@@ -317,6 +318,46 @@ public function setDefaultParagraphStyle($styles)
         return Style::setDefaultParagraphStyle($styles);
     }
 
+    /**
+     * Set default Footnote properties to settings.xml
+     *
+     * @param FootnoteProperties $properties
+     */
+    public function setDefaultFootnoteProperties(FootnoteProperties $properties)
+    {
+        Settings::setDefaultFootnoteProperties($properties);
+    }
+
+    /**
+     * Get default Footnote properties
+     *
+     * @return FootnoteProperties
+     */
+    public function getDefaultFootnoteProperties()
+    {
+        return Settings::getDefaultFootnoteProperties();
+    }
+
+    /**
+     * Set default Endnote properties to settings.xml
+     *
+     * @param FootnoteProperties $properties
+     */
+    public function setDefaultEndnoteProperties(FootnoteProperties $properties)
+    {
+        Settings::setDefaultEndnoteProperties($properties);
+    }
+
+    /**
+     * Get default Endnote properties
+     *
+     * @return FootnoteProperties
+     */
+    public function getDefaultEndnoteProperties()
+    {
+        return Settings::getDefaultEndnoteProperties();
+    }
+
     /**
      * Load template by filename
      *

src/PhpWord/Settings.php

@@ -17,6 +17,8 @@
 
 namespace PhpOffice\PhpWord;
 
+use PhpOffice\PhpWord\ComplexType\FootnoteProperties;
+
 /**
  * PHPWord settings class
  *
@@ -134,6 +136,20 @@ class Settings
      */
     private static $outputEscapingEnabled = false;
 
+    /**
+     * Default properties for the Footnotes
+     *
+     * @var FootnoteProperties
+     */
+    private static $defaultFootnoteProperties = null;
+
+    /**
+     * Default properties for the Endnotes
+     *
+     * @var FootnoteProperties
+     */
+    private static $defaultEndnoteProperties = null;
+
     /**
      * Return the compatibility option used by the XMLWriter
      *
@@ -443,4 +459,44 @@ public static function getCompatibility()
     {
         return self::hasCompatibility();
     }
+
+    /**
+     * Set default Footnote properties.
+     *
+     * @param FootnoteProperties $properties
+     */
+    public static function setDefaultFootnoteProperties(FootnoteProperties $properties)
+    {
+        self::$defaultFootnoteProperties = $properties;
+    }
+
+    /**
+     * Get default Footnote properties
+     *
+     * @return FootnoteProperties
+     */
+    public static function getDefaultFootnoteProperties()
+    {
+        return self::$defaultFootnoteProperties;
+    }
+
+    /**
+     * Set default Endnote properties.
+     *
+     * @param FootnoteProperties $properties
+     */
+    public static function setDefaultEndnoteProperties(FootnoteProperties $properties)
+    {
+        self::$defaultEndnoteProperties = $properties;
+    }
+
+    /**
+     * Get default Endnote properties
+     *
+     * @return FootnoteProperties
+     */
+    public static function getDefaultEndnoteProperties()
+    {
+        return self::$defaultEndnoteProperties;
+    }
 }