diff --git a/docs/changes/1.x/1.5.0.md b/docs/changes/1.x/1.5.0.md index b96865bada..2a8643516c 100644 --- a/docs/changes/1.x/1.5.0.md +++ b/docs/changes/1.x/1.5.0.md @@ -11,9 +11,10 @@ ### Miscellaneous - Update phpstan/phpstan requirement from ^0.12.88 || ^1.0.0 to ^0.12.88 || ^1.0.0 || ^2.0.0 by [@dependabot](https://github.com/dependabot) & [@Progi1984](https://github.com/Progi1984) in [#2736](https://github.com/PHPOffice/PHPWord/pull/2736) +- Updated usage documentation, particularly in the style section, by [@rasamassen](https://github.com/rasamassen) in [#2831](https://github.com/PHPOffice/PHPWord/pull/2831) ### Deprecations ### BC Breaks -### Notes \ No newline at end of file +### Notes diff --git a/docs/index.md b/docs/index.md index 211fc31a79..8fa043951f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -43,31 +43,31 @@ Below are the supported features for each file formats. | Features | | OOXML | ODF | RTF | HTML | PDF | |---------------------------|----------------------|--------|-------|-------|--------|--------| -| **Document Properties** | Standard | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | -| | Custom | :material-check: | :material-check: | | | | -| **Element Type** | Text | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | -| | Text Run | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | -| | Title | :material-check: | :material-check: | | :material-check: | :material-check: | -| | Link | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | -| | Preserve Text | :material-check: | | | | | -| | Text Break | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | -| | Page Break | :material-check: | | :material-check: | | | -| | List | :material-check: | :material-check: | | | | -| | Table | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | -| | Image | :material-check: | :material-check: | :material-check: | :material-check: | | -| | Object | :material-check: | | | | | -| | Watermark | :material-check: | | | | | -| | Table of Contents | :material-check: | | | | | -| | Header | :material-check: | | | | | -| | Footer | :material-check: | | | | | -| | Footnote | :material-check: | | | :material-check: | | -| | Endnote | :material-check: | | | :material-check: | | -| | Comments | :material-check: | | | | | -| **Graphs** | 2D basic graphs | :material-check: | | | | | +| **Document Properties** | Standard | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | Custom | :white_check_mark: | :white_check_mark: | | | | +| **Element Type** | Text | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | Text Run | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | Title | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | Link | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | Preserve Text | :white_check_mark: | | | | | +| | Text Break | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | Page Break | :white_check_mark: | | :white_check_mark: | | | +| | List | :white_check_mark: | :white_check_mark: | | | | +| | Table | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | Image | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | +| | Object | :white_check_mark: | | | | | +| | Watermark | :white_check_mark: | | | | | +| | Table of Contents | :white_check_mark: | | | | | +| | Header | :white_check_mark: | | | | | +| | Footer | :white_check_mark: | | | | | +| | Footnote | :white_check_mark: | | | :white_check_mark: | | +| | Endnote | :white_check_mark: | | | :white_check_mark: | | +| | Comments | :white_check_mark: | | | | | +| **Graphs** | 2D basic graphs | :white_check_mark: | | | | | | | 2D advanced graphs | | | | | | -| | 3D graphs | :material-check: | | | | | -| **Math** | OMML support | :material-check: | | | | | -| | MathML support | | :material-check: | | | | +| | 3D graphs | :white_check_mark: | | | | | +| **Math** | OMML support | :white_check_mark: | | | | | +| | MathML support | | :white_check_mark: | | | | | **Bonus** | Encryption | | | | | | | | Protection | | | | | | @@ -76,31 +76,31 @@ Below are the supported features for each file formats. | Features | | OOXML | DOC | ODF | RTF | HTML | |---------------------------|----------------------|--------|-------|-------|-------|-------| -| **Document Properties** | Standard | :material-check: | | | | | -| | Custom | :material-check: | | | | | -| **Element Type** | Text | :material-check: | :material-check: | :material-check: | :material-check: | :material-check: | -| | Text Run | :material-check: | | | | | -| | Title | :material-check: | | :material-check: | | | -| | Link | :material-check: | :material-check: | | | | -| | Preserve Text | :material-check: | | | | | -| | Text Break | :material-check: | :material-check: | | | | -| | Page Break | :material-check: | | | | | -| | List | :material-check: | | :material-check: | | :material-check: | -| | Table | :material-check: | | | | :material-check: | -| | Image | :material-check: | :material-check: | | | | +| **Document Properties** | Standard | :white_check_mark: | | | | | +| | Custom | :white_check_mark: | | | | | +| **Element Type** | Text | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | Text Run | :white_check_mark: | | | | | +| | Title | :white_check_mark: | | :white_check_mark: | | | +| | Link | :white_check_mark: | :white_check_mark: | | | | +| | Preserve Text | :white_check_mark: | | | | | +| | Text Break | :white_check_mark: | :white_check_mark: | | | | +| | Page Break | :white_check_mark: | | | | | +| | List | :white_check_mark: | | :white_check_mark: | | :white_check_mark: | +| | Table | :white_check_mark: | | | | :white_check_mark: | +| | Image | :white_check_mark: | :white_check_mark: | | | | | | Object | | | | | | | | Watermark | | | | | | | | Table of Contents | | | | | | -| | Header | :material-check: | | | | | -| | Footer | :material-check: | | | | | -| | Footnote | :material-check: | | | | | -| | Endnote | :material-check: | | | | | -| | Comments | :material-check: | | | | | +| | Header | :white_check_mark: | | | | | +| | Footer | :white_check_mark: | | | | | +| | Footnote | :white_check_mark: | | | | | +| | Endnote | :white_check_mark: | | | | | +| | Comments | :white_check_mark: | | | | | | **Graphs** | 2D basic graphs | | | | | | | | 2D advanced graphs | | | | | | | | 3D graphs | | | | | | -| **Math** | OMML support | :material-check: | | | | | -| | MathML support | | :material-check: | | | | +| **Math** | OMML support | :white_check_mark: | | | | | +| | MathML support | | :white_check_mark: | | | | | **Bonus** | Encryption | | | | | | | | Protection | | | | | | diff --git a/docs/usage/elements/index.md b/docs/usage/elements/index.md index 6106c8914b..adc5569014 100644 --- a/docs/usage/elements/index.md +++ b/docs/usage/elements/index.md @@ -1,34 +1,68 @@ # Elements +Elements are objects representing the various parts of a document. Elements can be [containers](containers.md) for other elements. + +## Basic Example + +``` php +addSection(); +$table = $section->addTable(); + +// Elements are added to containers without creating variables. +$section->addTitle(0, 'Hello, World!'); +$section->addText('How are you doing?'); + +``` + +## PHPWord Elements Below are the matrix of element availability in each container. The column shows the containers while the rows lists the elements. -| Num | Element | Section | Header | Footer | Cell | Text Run | Footnote | -|-------|-----------------|-----------|----------|----------|---------|------------|------------| -| 1 | [Text](text.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| 2 | Text Run | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :red_circle: | -| 3 | [Link](link.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| 4 | [Title](title.md) | :white_check_mark: | :question: | :question: | :question: | :question: | :question: | -| 5 | [Preserve Text](preservetext.md) | :question: | :white_check_mark: | :white_check_mark: | :material-check-decagram-outline: | :red_circle: | :red_circle: | -| 6 | [Text Break](textbreak.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| 7 | [Page Break](pagebreak.md) | :white_check_mark: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | -| 8 | [List](list.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :red_circle: | -| 9 | [Table](table.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :red_circle: | -| 10 | [Image](image.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| 11 | [Watermark](watermark.md) | :red_circle: | :white_check_mark: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | -| 12 | [OLEObject](oleobject.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| 13 | [TOC](toc.md) | :white_check_mark: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | -| 14 | [Footnote](note.md) | :white_check_mark: | :red_circle: | :red_circle: | :material-check-decagram: | :material-check-decagram: | :red_circle: | -| 15 | [Endnote](note.md) | :white_check_mark: | :red_circle: | :red_circle: | :material-check-decagram: | :material-check-decagram: | :red_circle: | -| 16 | [CheckBox](checkbox.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | -| 17 | [TextBox](textbox.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :red_circle: | -| 18 | [Field](field.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| 19 | [Line](line.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| 20 | [Chart](chart.md) | :white_check_mark: | | | :white_check_mark: | | | +| | [Section](..containers.md) | [Header](..containers.md) | [Footer](..containers.md) | [Cell](table.md)
[Text Box](textbox.md) | [Text Run](text.md)
[List Item Run](list.md) | [Endnote](note.md)
[Footnote](note.md) | +|---|---|---|---|---|---|---| +| Bookmark | :question: | :question: | :question: | :question: | :question: | :question: | +| [Chart](chart.md) | :white_check_mark: | :question: | :question: | :white_check_mark: | :question: | :red_circle: | :question: | +| [CheckBox](checkbox.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | +| [Endnote](note.md) | :white_check_mark: | :red_circle: | :red_circle: | :ballot_box_with_check: | :ballot_box_with_check: | :red_circle: | +| [Field](field.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| [Footer](..containers.md) | :white_check_mark: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | +| FormField | :question: | :question: | :question: | :question: | :question: | :question: | +| [Footnote](note.md) | :white_check_mark: | :red_circle: | :red_circle: | :ballot_box_with_check: | :ballot_box_with_check: | :red_circle: | +| [Formula](formula.md) | :question: | :question: | :question: | :question: | :question: | :question: | +| [Header](..containers.md) | :white_check_mark: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | +| [Image](image.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| [Line](line.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| [Link](link.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| [List Item](list.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :red_circle: | +| [List Item Run](list.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :red_circle: | +| [OLEObject](oleobject.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| [Page Break](pagebreak.md) | :white_check_mark: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | +| [Preserve Text](preservetext.md) | :question: | :white_check_mark: | :white_check_mark: | :heavy_check_mark: | :red_circle: | :red_circle: | +| [Ruby](ruby.md) | :question: | :question: | :question: | :question: | :question: | :question: | +| SDT | :question: | :question: | :question: | :question: | :question: | :question: | +| Shape | :question: | :question: | :question: | :question: | :question: | :question: | +| [TOC](toc.md) | :white_check_mark: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | +| [Table](table.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :red_circle: | +| [Text](text.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| [Text Break](textbreak.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| [Text Box](textbox.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :red_circle: | +| [Text Run](text.md) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :red_circle: | :white_check_mark: | +| [Title](title.md) | :white_check_mark: | :question: | :question: | :question: | :question: | :question: | +| [Watermark](watermark.md) | :red_circle: | :white_check_mark: | :red_circle: | :red_circle: | :red_circle: | :red_circle: | Legend: - :white_check_mark: : Available. -- :material-check-decagram-outline: : Available only when inside header/footer. -- :material-check-decagram: : Available only when inside section. +- :heavy_check_mark: : Available only when inside header/footer. +- :ballot_box_with_check: : Available only when inside section. - :red_circle: : Not available. -- :question: : Should be available. \ No newline at end of file +- :question: : Should be available. + +# Unique Elements +See each of the following elements for details on how to use them. + +- [Row](table.md) and [Cell](table.md) can only be added to a [Table](table.md). +- [Comment](comment.md) +- [Track Change](trackchanges.md) diff --git a/docs/usage/elements/section.md b/docs/usage/elements/section.md new file mode 100644 index 0000000000..67461497aa --- /dev/null +++ b/docs/usage/elements/section.md @@ -0,0 +1,15 @@ +# Section + +Sections are the basic containers for most elements within a document. Sections can be added using the `addSection` method. + +``` php +addSection([$sectionStyle]); +$section->addText('Hello, World!'); +``` + +For available styling options, see [`Styles > Section`](../styles/section.md). + +See [`Sample_03_Sections`](/samples/Sample_03_Sections.php) for more code samples. diff --git a/docs/usage/introduction.md b/docs/usage/introduction.md index 19d6aff51f..88414951ac 100644 --- a/docs/usage/introduction.md +++ b/docs/usage/introduction.md @@ -74,319 +74,15 @@ $objWriter->save('helloWorld.html'); /* Note: we skip PDF, because "HTML-to-PDF" approach is used to create PDF documents. */ ``` -## PHPWord Settings - -The ``PhpOffice\PhpWord\Settings`` class provides some options that will -affect the behavior of PHPWord. Below are the options. - -### XML Writer compatibility - -This option sets [XMLWriter::setIndent](http://www.php.net/manual/en/function.xmlwriter-set-indent.php) and [XMLWriter::setIndentString](http://www.php.net/manual/en/function.xmlwriter-set-indent-string.php>). The default value of this option is ``true`` (compatible), which is [required for OpenOffice](https://github.com/PHPOffice/PHPWord/issues/103) to render OOXML document correctly. You can set this option to ``false`` during development to make the resulting XML file easier to read. - -``` php -setDefaultFontName('Times New Roman'); -$phpWord->setDefaultFontColor('FF0000'); -$phpWord->setDefaultFontSize(12); -``` - -Or you can specify Asian Font - -``` php -setDefaultAsianFontName('標楷體'); -``` - -## Document settings - -Settings for the generated document can be set using ``$phpWord->getSettings()`` - -### Magnification Setting - -The default zoom value is 100 percent. This can be changed either to another percentage - -``` php -getSettings()->setZoom(75); -``` - -Or to predefined values ``fullPage``, ``bestFit``, ``textFit`` - -``` php -getSettings()->setZoom(Zoom::BEST_FIT); -``` - -### Mirroring the Page Margins - -Use mirror margins to set up facing pages for double-sided documents, such as books or magazines. - -``` php -getSettings()->setMirrorMargins(true); -``` - -!!! note annotate "Don't forget to set both paper size and page size" - - For example, to print a document on A4 paper (landscape) and fold it into A5 pages (portrait), use this section style: - - ``` php - getSettings()->setMirrorMargins(true); - $phpWord->addSection([ - 'paperSize' => 'A4', - 'orientation' => 'landscape', - 'pageSizeW' => Converter::cmToTwip(14.85), - 'pageSizeH' => Converter::cmToTwip(21), - ]); - ``` - -### Printing as folded booklet - -Use book-fold printing to set up documents to be printed as foldable pages. - -``` php -getSettings()->setBookFoldPrinting(true); -``` - -### Spelling and grammatical checks - -By default spelling and grammatical errors are shown as soon as you open a word document. -For big documents this can slow down the opening of the document. You can hide the spelling and/or grammatical errors with: - -``` php -getSettings()->setHideGrammaticalErrors(true); -$phpWord->getSettings()->setHideSpellingErrors(true); -``` - -You can also specify the status of the spell and grammar checks, marking spelling or grammar as dirty will force a re-check when opening the document. - -``` php -setGrammar(\PhpOffice\PhpWord\ComplexType\ProofState::CLEAN); -$proofState->setSpelling(\PhpOffice\PhpWord\ComplexType\ProofState::DIRTY); - -$phpWord->getSettings()->setProofState($proofState); -``` - -### Track Revisions - -Track changes can be activated using ``setTrackRevisions``, you can furture specify - -- Not to use move syntax, instead moved items will be seen as deleted in one place and added in another -- Not track formatting revisions - -``` php -getSettings()->setTrackRevisions(true); -$phpWord->getSettings()->setDoNotTrackMoves(true); -$phpWord->getSettings()->setDoNotTrackFormatting(true); -``` - -### Decimal Symbol - -The default symbol to represent a decimal figure is the ``.`` in english. In french you might want to change it to ``,`` for instance. - -``` php -getSettings()->setDecimalSymbol(','); -``` - -### Document Language - -The default language of the document can be change with the following. - -``` php -getSettings()->setThemeFontLang(new Language(Language::FR_BE)); -``` - -``Language`` has 3 parameters, one for Latin languages, one for East Asian languages and one for Complex (Bi-Directional) languages. -A couple of language codes are provided in the ``PhpOffice\PhpWord\Style\Language`` class but any valid code/ID can be used. - -In case you are generating an RTF document the language need to be set differently. - -``` php -setLangId(Language::EN_GB_ID); -$phpWord->getSettings()->setThemeFontLang($lang); -``` - -## Document information - -You can set the document information such as title, creator, and company -name. Use the following functions: - -``` php -getDocInfo(); -$properties->setCreator('My name'); -$properties->setCompany('My factory'); -$properties->setTitle('My title'); -$properties->setDescription('My description'); -$properties->setCategory('My category'); -$properties->setLastModifiedBy('My name'); -$properties->setCreated(mktime(0, 0, 0, 3, 12, 2014)); -$properties->setModified(mktime(0, 0, 0, 3, 14, 2014)); -$properties->setSubject('My subject'); -$properties->setKeywords('my, key, word'); -``` - -## Measurement units - -The base length unit in Open Office XML is twip. Twip means "TWentieth -of an Inch Point", i.e. 1 twip = 1/1440 inch. - -You can use PHPWord helper functions to convert inches, centimeters, or -points to twip. - -``` php -addParagraphStyle('My Style', array( - 'spaceAfter' => \PhpOffice\PhpWord\Shared\Converter::pointToTwip(6)) -); - -$section = $phpWord->addSection(); -$sectionStyle = $section->getStyle(); -// half inch left margin -$sectionStyle->setMarginLeft(\PhpOffice\PhpWord\Shared\Converter::inchToTwip(.5)); -// 2 cm right margin -$sectionStyle->setMarginRight(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(2)); -``` - -## Document protection - -The document (or parts of it) can be password protected. - -``` php -getSettings()->getDocumentProtection(); -$documentProtection->setEditing(DocProtect::READ_ONLY); -$documentProtection->setPassword('myPassword'); -``` - -## Automatically Recalculate Fields on Open - -To force an update of the fields present in the document, set updateFields to true - -``` php -getSettings()->setUpdateFields(true); -``` - -## Hyphenation - -Hyphenation describes the process of breaking words with hyphens. There are several options to control hyphenation. - -### Auto hyphenation - -To automatically hyphenate text set ``autoHyphenation`` to ``true``. - -``` php -getSettings()->setAutoHyphenation(true); -``` - -### Consecutive Hyphen Limit - -The maximum number of consecutive lines of text ending with a hyphen can be controlled by the ``consecutiveHyphenLimit`` option. -There is no limit if the option is not set or the provided value is ``0``. - -``` php -getSettings()->setConsecutiveHyphenLimit(2); -``` - -### Hyphenation Zone - -The hyphenation zone (in *twip*) is the allowed amount of whitespace before hyphenation is applied. -The smaller the hyphenation zone the more words are hyphenated. Or in other words, the wider the hyphenation zone the less words are hyphenated. - -``` php -getSettings()->setHyphenationZone(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(1)); -``` - -### Hyphenate Caps - -To control whether or not words in all capital letters shall be hyphenated use the `doNotHyphenateCaps` option. - -``` php -getSettings()->setDoNotHyphenateCaps(true); -``` +## Using PHPWord + +You may load documents into PHPWord using: +- [Readers](readers.md). Read in an existing document. +- [Templates](template.md). Read in an existing document with {template} fields. + +You may output documents from PHPWord using: +- [Settings](settings.md). Manipulate the document settings. +- [Containers](containers.md). Add containers, such as sections, headers, and footers. +- [Elements](elements/index.md). Add elements to containers, such as text, tables, and charts. +- [Styles](styles/index.md). Adjust the styles of elements. +- [Writers](writers.md). Write the resulting document to a file. diff --git a/docs/usage/settings.md b/docs/usage/settings.md new file mode 100644 index 0000000000..9f3f1a33ef --- /dev/null +++ b/docs/usage/settings.md @@ -0,0 +1,316 @@ +## PHPWord Settings + +The ``PhpOffice\PhpWord\Settings`` class provides some options that will +affect the behavior of PHPWord. Below are the options. + +### XML Writer compatibility + +This option sets [XMLWriter::setIndent](http://www.php.net/manual/en/function.xmlwriter-set-indent.php) and [XMLWriter::setIndentString](http://www.php.net/manual/en/function.xmlwriter-set-indent-string.php>). The default value of this option is ``true`` (compatible), which is [required for OpenOffice](https://github.com/PHPOffice/PHPWord/issues/103) to render OOXML document correctly. You can set this option to ``false`` during development to make the resulting XML file easier to read. + +``` php +setDefaultFontName('Times New Roman'); +$phpWord->setDefaultFontColor('FF0000'); +$phpWord->setDefaultFontSize(12); +``` + +Or you can specify Asian Font + +``` php +setDefaultAsianFontName('標楷體'); +``` + +## Document settings + +Settings for the generated document can be set using ``$phpWord->getSettings()`` + +### Magnification Setting + +The default zoom value is 100 percent. This can be changed either to another percentage + +``` php +getSettings()->setZoom(75); +``` + +Or to predefined values ``fullPage``, ``bestFit``, ``textFit`` + +``` php +getSettings()->setZoom(Zoom::BEST_FIT); +``` + +### Mirroring the Page Margins + +Use mirror margins to set up facing pages for double-sided documents, such as books or magazines. + +``` php +getSettings()->setMirrorMargins(true); +``` + +!!! note annotate "Don't forget to set both paper size and page size" + + For example, to print a document on A4 paper (landscape) and fold it into A5 pages (portrait), use this section style: + + ``` php + getSettings()->setMirrorMargins(true); + $phpWord->addSection([ + 'paperSize' => 'A4', + 'orientation' => 'landscape', + 'pageSizeW' => Converter::cmToTwip(14.85), + 'pageSizeH' => Converter::cmToTwip(21), + ]); + ``` + +### Printing as folded booklet + +Use book-fold printing to set up documents to be printed as foldable pages. + +``` php +getSettings()->setBookFoldPrinting(true); +``` + +### Spelling and grammatical checks + +By default spelling and grammatical errors are shown as soon as you open a word document. +For big documents this can slow down the opening of the document. You can hide the spelling and/or grammatical errors with: + +``` php +getSettings()->setHideGrammaticalErrors(true); +$phpWord->getSettings()->setHideSpellingErrors(true); +``` + +You can also specify the status of the spell and grammar checks, marking spelling or grammar as dirty will force a re-check when opening the document. + +``` php +setGrammar(\PhpOffice\PhpWord\ComplexType\ProofState::CLEAN); +$proofState->setSpelling(\PhpOffice\PhpWord\ComplexType\ProofState::DIRTY); + +$phpWord->getSettings()->setProofState($proofState); +``` + +### Track Revisions + +Track changes can be activated using ``setTrackRevisions``, you can furture specify + +- Not to use move syntax, instead moved items will be seen as deleted in one place and added in another +- Not track formatting revisions + +``` php +getSettings()->setTrackRevisions(true); +$phpWord->getSettings()->setDoNotTrackMoves(true); +$phpWord->getSettings()->setDoNotTrackFormatting(true); +``` + +### Decimal Symbol + +The default symbol to represent a decimal figure is the ``.`` in english. In french you might want to change it to ``,`` for instance. + +``` php +getSettings()->setDecimalSymbol(','); +``` + +### Document Language + +The default language of the document can be change with the following. + +``` php +getSettings()->setThemeFontLang(new Language(Language::FR_BE)); +``` + +``Language`` has 3 parameters, one for Latin languages, one for East Asian languages and one for Complex (Bi-Directional) languages. +A couple of language codes are provided in the ``PhpOffice\PhpWord\Style\Language`` class but any valid code/ID can be used. + +In case you are generating an RTF document the language need to be set differently. + +``` php +setLangId(Language::EN_GB_ID); +$phpWord->getSettings()->setThemeFontLang($lang); +``` + +## Document information + +You can set the document information such as title, creator, and company +name. Use the following functions: + +``` php +getDocInfo(); +$properties->setCreator('My name'); +$properties->setCompany('My factory'); +$properties->setTitle('My title'); +$properties->setDescription('My description'); +$properties->setCategory('My category'); +$properties->setLastModifiedBy('My name'); +$properties->setCreated(mktime(0, 0, 0, 3, 12, 2014)); +$properties->setModified(mktime(0, 0, 0, 3, 14, 2014)); +$properties->setSubject('My subject'); +$properties->setKeywords('my, key, word'); +``` + +## Measurement units + +The base length unit in Open Office XML is twip. Twip means "TWentieth +of an Inch Point", i.e. 1 twip = 1/1440 inch. + +You can use PHPWord helper functions to convert inches, centimeters, or +points to twip. + +``` php +addParagraphStyle('My Style', array( + 'spaceAfter' => \PhpOffice\PhpWord\Shared\Converter::pointToTwip(6)) +); + +$section = $phpWord->addSection(); +$sectionStyle = $section->getStyle(); +// half inch left margin +$sectionStyle->setMarginLeft(\PhpOffice\PhpWord\Shared\Converter::inchToTwip(.5)); +// 2 cm right margin +$sectionStyle->setMarginRight(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(2)); +``` + +## Document protection + +The document (or parts of it) can be password protected. + +``` php +getSettings()->getDocumentProtection(); +$documentProtection->setEditing(DocProtect::READ_ONLY); +$documentProtection->setPassword('myPassword'); +``` + +## Automatically Recalculate Fields on Open + +To force an update of the fields present in the document, set updateFields to true + +``` php +getSettings()->setUpdateFields(true); +``` + +## Hyphenation + +Hyphenation describes the process of breaking words with hyphens. There are several options to control hyphenation. + +### Auto hyphenation + +To automatically hyphenate text set ``autoHyphenation`` to ``true``. + +``` php +getSettings()->setAutoHyphenation(true); +``` + +### Consecutive Hyphen Limit + +The maximum number of consecutive lines of text ending with a hyphen can be controlled by the ``consecutiveHyphenLimit`` option. +There is no limit if the option is not set or the provided value is ``0``. + +``` php +getSettings()->setConsecutiveHyphenLimit(2); +``` + +### Hyphenation Zone + +The hyphenation zone (in *twip*) is the allowed amount of whitespace before hyphenation is applied. +The smaller the hyphenation zone the more words are hyphenated. Or in other words, the wider the hyphenation zone the less words are hyphenated. + +``` php +getSettings()->setHyphenationZone(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(1)); +``` + +### Hyphenate Caps + +To control whether or not words in all capital letters shall be hyphenated use the `doNotHyphenateCaps` option. + +``` php +getSettings()->setDoNotHyphenateCaps(true); +``` diff --git a/docs/usage/simpletypes/border.md b/docs/usage/simpletypes/border.md new file mode 100644 index 0000000000..357da66225 --- /dev/null +++ b/docs/usage/simpletypes/border.md @@ -0,0 +1,33 @@ +# Border Style + +## Constants +- `SINGLE`. A single line. +- `DASH_DOT_STROKED`. A line with a series of alternating thin and thick strokes +- `DASHED`. A dashed line +- `DASH_SMALL_GAP`. A dashed line with small gaps +- `DOT_DASH`. A line with alternating dots and dashes +- `DOT_DOT_DASH`. A line with a repeating dot - dot - dash sequence +- `DOTTED`. A dotted line +- `DOUBLE`. A double line +- `DOUBLE_WAVE`. A double wavy line +- `INSET`. An inset set of lines +- `NIL`. No border +- `NONE`. No border +- `OUTSET`. An outset set of lines +- `THICK`. A single line +- `THICK_THIN_LARGE_GAP`. A thick line contained within a thin line with a large-sized intermediate gap +- `THICK_THIN_MEDIUM_GAP`. A thick line contained within a thin line with a medium-sized intermediate gap +- `THICK_THIN_SMALL_GAP`. A thick line contained within a thin line with a small intermediate gap +- `THIN_THICK_LARGE_GAP`. A thin line contained within a thick line with a large-sized intermediate gap +- `THIN_THICK_MEDIUM_GAP`. A thick line contained within a thin line with a medium-sized intermediate gap +- `THIN_THICK_SMALL_GAP`. A thick line contained within a thin line with a small intermediate gap +- `THIN_THICK_THIN_LARGE_GAP`. A thin-thick-thin line with a large gap +- `THIN_THICK_THIN_MEDIUM_GAP`. A thin-thick-thin line with a medium gap +- `THIN_THICK_THIN_SMALL_GAP`. A thin-thick-thin line with a small gap +- `THREE_D_EMBOSS`. A three-staged gradient line, getting darker towards the paragraph +- `THREE_D_ENGRAVE`. A three-staged gradient like, getting darker away from the paragraph +- `TRIPLE`. A triple line +- `WAVE`. A wavy line + +## Used In +- [`Style > Border`](../styles/border.md). diff --git a/docs/usage/simpletypes/jc.md b/docs/usage/simpletypes/jc.md new file mode 100644 index 0000000000..e3cfc43923 --- /dev/null +++ b/docs/usage/simpletypes/jc.md @@ -0,0 +1,24 @@ +# Justification + +## Constants +- `START`. Commonly known as *left*. +- `CENTER`. +- `END`. Commonly known as *right*. +- `BOTH`. Commonly known as *justify*. +- `NUM_TAB`. +- `DISTRIBUTE`. +- `THAI_DISTRIBUTE`. +- `HIGH_KASHIDA`. +- `MEDIUM_KASHIDA`. +- `LOW_KASHIDA`. + +Deprecated +- `LEFT`. +- `RIGHT`. +- `JUSTIFY`. + +## Used In +- [`Style > Frame`](../styles/frame.md). +- [`Style > NumberingLevel`](../styles/numberinglevel.md). +- [`Style > Paragraph`](../styles/paragraph.md). +- [`Style > Table`](../styles/table.md). diff --git a/docs/usage/simpletypes/jctable.md b/docs/usage/simpletypes/jctable.md new file mode 100644 index 0000000000..79ac507870 --- /dev/null +++ b/docs/usage/simpletypes/jctable.md @@ -0,0 +1,9 @@ +# Table Justification + +## Constants +- `START`. Commonly known as *left*. +- `CENTER`. +- `END`. Commonly known as *right*. + +## Used In +- [`Style > Table`](../styles/table.md). diff --git a/docs/usage/simpletypes/linespacingrule.md b/docs/usage/simpletypes/linespacingrule.md new file mode 100644 index 0000000000..201e79dc9a --- /dev/null +++ b/docs/usage/simpletypes/linespacingrule.md @@ -0,0 +1,10 @@ +# Line Spacing Rule + +## Constants +- `AUTO`. +- `EXACT`. +- `AT_LEAST`. + +## Used In +- [`Style > Paragraph`](../styles/paragraph.md). +- [`Style > Spacing`](../styles/spacing.md). diff --git a/docs/usage/simpletypes/numberformat.md b/docs/usage/simpletypes/numberformat.md new file mode 100644 index 0000000000..227bd9a486 --- /dev/null +++ b/docs/usage/simpletypes/numberformat.md @@ -0,0 +1,72 @@ +# Number Format + +## Constants +- `NONE`. No Numbering. +- `BULLET`. Bullet. +- `UPPER_ROMAN`. Uppercase Roman Numerals. +- `LOWER_ROMAN`. Lowercase Roman Numerals. +- `UPPER_LETTER`. Uppercase Latin Alphabet. +- `LOWER_LETTER`. Lowercase Latin Alphabet. +- `ORDINAL`. Ordinal. +- `ORDINAL_TEXT`. Ordinal Text. +- `CARDINAL_TEXT`. Cardinal Text. +- `HEX`. Hexadecimal Numbering. +- `CHICAGO`. Chicago Manual of Style. + +### Decimal +- `DECIMAL`. Decimal Numbers. +- `DECIMAL_ZERO`. Initial Zero Arabic Numerals. +- `DECIMAL_FULL_WIDTH`. Double Byte Arabic Numerals. +- `DECIMAL_FULL_WIDTH2`. Double Byte Arabic Numerals Alternate. +- `DECIMAL_HALF_WIDTH`. Single Byte Arabic Numerals. +- `DECIMAL_ENCLOSED_CIRCLE`. Decimal Numbers Enclosed in a Circle. +- `DECIMAL_ENCLOSED_FULL_STOP`. Decimal Numbers Followed by a Period. +- `DECIMAL_ENCLOSED_PAREN`. Decimal Numbers Enclosed in Parenthesis. +- `DECIMAL_ENCLOSED_CIRCLE_CHINESE`. Decimal Numbers Enclosed in a Circle. +- `NUMBER_IN_DASH`. Number With Dashes. + +### Ideograph +- `IDEOGRAPH_DIGITAL`. Ideographs. +- `IDEOGRAPHENCLOSEDCIRCLE`. Ideographs Enclosed in a Circle. +- `IDEOGRAPH_TRADITIONAL`. Traditional Ideograph Format. +- `IDEOGRAPH_ZODIAC`. Zodiac Ideograph Format. +- `IDEOGRAPH_ZODIAC_TRADITIONAL`. Traditional Zodiac Ideograph Format. +- `IDEOGRAPH_LEGAL_TRADITIONAL`. Traditional Legal Ideograph Format. + +### Non-Roman Systems +- `AIUEO`. AIUEO Order Hiragana. +- `AIUEO_FULL_WIDTH`. Full-Width AIUEO Order Hiragana. +- `IROHA`. Iroha Ordered Katakana. +- `IROHA_FULL_WIDTH `. Full-Width Iroha Ordered Katakana. +- `JAPANESE_COUNTING`. Japanese Counting System. +- `JAPANESE_LEGAL`. Japanese Legal Numbering. +- `JAPANESE_DIGITAL_TEN_THOUSAND`. Japanese Digital Ten Thousand Counting System. +- `CHINESE_COUNTING`. Chinese Counting System. +- `CHINESE_LEGAL_SIMPLIFIED`. Chinese Legal Simplified Format. +- `CHINESE_COUNTING_THOUSAND`. Chinese Counting Thousand System. +- `GANADA`. Korean Ganada Numbering. +- `CHOSUNG`. Korean Chosung Numbering. +- `KOREAN_DIGITAL`. Korean Digital Counting System. +- `KOREAN_COUNTING`. Korean Counting System. +- `KOREAN_LEGAL`. Korean Legal Numbering. +- `KOREAN_DIGITAL2`. Korean Digital Counting System Alternate. +- `VIETNAMESE_COUNTING`. Vietnamese Numerals. +- `RUSSIAN_LOWER`. Lowercase Russian Alphabet. +- `RUSSIAN_UPPER`. Uppercase Russian Alphabet. +- `HEBREW1`. Hebrew Numerals. +- `HEBREW2`. Hebrew Alphabet. +- `ARABIC_ALPHA`. Arabic Alphabet. +- `ARABIC_ABJAD`. Arabic Abjad Numerals. +- `HINDI_VOWELS`. Hindi Vowels. +- `HINDI_CONSONANTS`. Hindi Consonants. +- `HINDI_NUMBERS`. Hindi Numbers. +- `HINDI_COUNTING`. Hindi Counting System. +- `THAI_LETTERS`. Thai Letters. +- `THAI_NUMBERS`. Thai Numerals. +- `THAI_COUNTING`. Thai Counting System. +- `TAIWANESE_COUNTING`. Taiwanese Counting System. +- `TAIWANESE_COUNTING_THOUSAND`. Taiwanese Counting Thousand System. +- `TAIWANESE_DIGITAL`. Taiwanese Digital Counting System. + +## Used In +- [`Style > NumberingLevel`](../styles/numberinglevel.md). diff --git a/docs/usage/simpletypes/tblwidth b/docs/usage/simpletypes/tblwidth new file mode 100644 index 0000000000..a155ab8f29 --- /dev/null +++ b/docs/usage/simpletypes/tblwidth @@ -0,0 +1,10 @@ +# Table Width + +## Constants +- `NIL`. No width. +- `AUTO`. Automatically determined width. +- `PERCENT`. Width in fiftieths of a percent. +- `TWIP`. Width in twentieths of a point. + +## Used In +- [`Style > Table`](../styles/table.md). diff --git a/docs/usage/simpletypes/textalignment.md b/docs/usage/simpletypes/textalignment.md new file mode 100644 index 0000000000..7b321ff9a0 --- /dev/null +++ b/docs/usage/simpletypes/textalignment.md @@ -0,0 +1,11 @@ +# Text Alignment + +## Constants +- `TOP`. Align Text at Top. +- `CENTER`. Align Text at Center. +- `BASELINE`. Align Text at Baseline. +- `BOTTOM`. Align Text at Bottom. +- `AUTO`. Automatically Determine Alignment. + +## Used In +- [`Style > Paragraph`](../styles/paragraph.md). diff --git a/docs/usage/simpletypes/verticaljc.md b/docs/usage/simpletypes/verticaljc.md new file mode 100644 index 0000000000..cac2db631a --- /dev/null +++ b/docs/usage/simpletypes/verticaljc.md @@ -0,0 +1,11 @@ +# Vertical Justification + +## Constants +- `TOP`. +- `CENTER`. +- `BOTH`. +- `BOTTOM`. + +## Used In +- [`Style > Cell`](../styles/cell.md). +- [`Style > Section`](../styles/section.md). diff --git a/docs/usage/styles/border.md b/docs/usage/styles/border.md new file mode 100644 index 0000000000..cf01410483 --- /dev/null +++ b/docs/usage/styles/border.md @@ -0,0 +1,25 @@ +# Border Styles + +``` php + 10, 'borderColor' => '#FF0000', 'margin' => 50]; +$phpWord->addTableStyle($tableStyleName, $tableStyle) +$table = $section->addTable($tableStyleName); +``` + +See [`Sample_03_Sections`](/samples/Sample_03_Sections.php) and [`Sample_09_Tables`](/samples/Sample_09_Tables.php) for more code samples. + +## Options +- `border(Top|Right|Bottom|Left)Size`. Border size in *twip*. +- `border(Top|Right|Bottom|Left)Color`. Border color, eg '9966CC'. +- `border(Top|Right|Bottom|Left)Style`. Border style. + * See [`SimpleType > Border`](../simpletypes/border.md) class constants for possible values. +- `margin(Top|Right|Bottom|Left)`. Page margin in *twip*. `1440` is default. + +## Used In +- [`Style > Cell`](../styles/table.md). +- [`Style > Paragraph`](../styles/paragraph.md). +- [`Style > Section`](../styles/section.md). +- [`Style > Table`](../styles/table.md). diff --git a/docs/usage/styles/font.md b/docs/usage/styles/font.md index 921dc7fd85..dbb77dea41 100644 --- a/docs/usage/styles/font.md +++ b/docs/usage/styles/font.md @@ -1,28 +1,82 @@ -# Font - -Available Font style options: - -- ``allCaps``. All caps, *true* or *false*. -- ``bgColor``. Font background color, e.g. *FF0000*. -- ``bold``. Bold, *true* or *false*. -- ``color``. Font color, e.g. *FF0000*. -- ``doubleStrikethrough``. Double strikethrough, *true* or *false*. -- ``fgColor``. Font highlight color, e.g. *yellow*, *green*, *blue*. - See ``\PhpOffice\PhpWord\Style\Font::FGCOLOR_...`` class constants for possible values -- ``hint``. Font content type, *default*, *eastAsia*, or *cs*. -- ``italic``. Italic, *true* or *false*. -- ``name``. Font name, e.g. *Arial*. -- ``rtl``. Right to Left language, *true* or *false*. -- ``size``. Font size, e.g. *20*, *22*. -- ``smallCaps``. Small caps, *true* or *false*. -- ``strikethrough``. Strikethrough, *true* or *false*. -- ``subScript``. Subscript, *true* or *false*. -- ``superScript``. Superscript, *true* or *false*. -- ``underline``. Underline, *single*, *dash*, *dotted*, etc. - See ``\PhpOffice\PhpWord\Style\Font::UNDERLINE_...`` class constants for possible values -- ``lang``. Language, either a language code like *en-US*, *fr-BE*, etc. or an object (or as an array) if you need to set eastAsian or bidirectional languages - See ``\PhpOffice\PhpWord\Style\Language`` class for some language codes. -- ``position``. The text position, raised or lowered, in half points -- ``hidden``. Hidden text, *true* or *false*. -- ``whiteSpace``. How white space is handled when generating html/pdf. Possible values are *pre-wrap* and *normal* (other css values for white space are accepted, but are not expected to be useful). -- ``fallbackFont``. Fallback generic font for html/pdf. Possible values are *sans-serif*, *serif*, and *monospace* (other css values for generic fonts are accepted). +# Font Styles + +``` php +addFontStyle('title', ['color' => '#FF0000', 'size' => 32]); +$section->addText('Hello, World!', 'title'); + +``` + +``` php + 'Arial', 'bold' => true, 'underline' => FontStyle::UNDERLINE_DASH]; +$section->addText('Hello, World!', $fontStyle); + +``` + +See [`Sample_01_SimpleText`](/samples/Sample_01_SimpleText.php) for more code samples. + +## Constants +- Underline + * `UNDERLINE_NONE` + * `UNDERLINE_DASH`, `UNDERLINE_DASHHEAVY`, + * `UNDERLINE_DASHLONG`, `UNDERLINE_DASHLONGHEAVY` + * `UNDERLINE_SINGLE`, `UNDERLINE_DOUBLE`, `UNDERLINE_HEAVY` + * `UNDERLINE_DOTDASH`, `UNDERLINE_DOTDASHHEAVY` + * `UNDERLINE_DOTDOTDASH`, `UNDERLINE_DOTDOTDASHHEAVY` + * `UNDERLINE_DOTTED`, `UNDERLINE_DOTTEDHEAVY` + * `UNDERLINE_WAVY`, `UNDERLINE_WAVYDOUBLE`, `UNDERLINE_WAVYHEAVY` + * `UNDERLINE_WORDS` +- Foreground Color + * `FGCOLOR_YELLOW`, `FGCOLOR_LIGHTGREEN`, `FGCOLOR_CYAN`, `FGCOLOR_MAGENTA`, `FGCOLOR_BLUE`, `FGCOLOR_RED` + * `FGCOLOR_DARKBLUE`, `FGCOLOR_DARKCYAN`, `FGCOLOR_DARKGREEN`, `FGCOLOR_DARKMAGENTA`, `FGCOLOR_DARKRED`, `FGCOLOR_DARKYELLOW` + * `FGCOLOR_DARKGRAY`, `FGCOLOR_LIGHTGRAY`, `FGCOLOR_BLACK` + +## Options +- `allCaps`. All caps, *true* or *false*. +- `bgColor`. Font background color, e.g. *FF0000*. +- `bold`. Bold, *true* or *false*. +- `color`. Font color, e.g. *FF0000*. +- `doubleStrikethrough`. Double strikethrough, *true* or *false*. +- `fallbackFont`. Fallback generic font. Possible values are *serif*, *sans-serif*, *monospace*, *cursive*, *fantasy*, *system-ui*, *math*, *emoji*, and *fangsong*. +- `fgColor`. Font highlight color, e.g. *yellow*, *green*, *blue*. + * See constants above for possible values. +- `hidden`. Hidden text, *true* or *false*. +- `hint`. Font content type, *default*, *eastAsia*, or *cs*. +- `italic`. Italic, *true* or *false*. +- `kerning`. Font kerning: halfpoint. +- `lang`. Language, either a language code like *en-US*, *fr-BE*, etc. or an object (or as an array) if you need to set eastAsian or bidirectional languages + * See [`Style > Language`](../styles/language.md) class for some language codes. +- `lineHeight`. Line height. +- `paragraph`. Paragraph. + * See [`Style > Paragraph`](../styles/paragraph.md). +- `name`. Font name, e.g. *Arial*. +- `noProof`. Disable AutoCorrect, *true* or *false*. +- `position`. The text position, raised or lowered, in half points +- `rtl`. Right to Left language, *true* or *false*. +- `scale`. Expande/compress text. +- `shading`. Shading. +- `size`. Font size, e.g. *20*, *22*. +- `smallCaps`. Small caps, *true* or *false*. +- `spacing`. Characters spacing adjustment in *twip*. +- `strikethrough`. Strikethrough, *true* or *false*. +- `subScript`. Subscript, *true* or *false*. +- `superScript`. Superscript, *true* or *false*. +- `underline`. Underline, *single*, *dash*, *dotted*, etc. `UNDERLINE_NONE` is default. + * See constants above for possible values. +- `whiteSpace`. How white space is handled when generating html/pdf. Possible values are *pre-wrap* and *normal* (other css values for white space are accepted, but are not expected to be useful). + +## Used In +- [`Element > CheckBox`](../elements/checkbox.md). +- [`Element > Field`](../elements/field.md). +- [`Element > FormField`](../elements/formfield.md). +- [`Element > Link`](../elements/link.md). +- [`Element > ListItem`](../elements/list.md). +- [`Element > PreserveText`](../elements/preservetext.md). +- [`Element > SDT`](../elements/sdt.md). +- [`Element > Text`](../elements/text.md). +- [`Element > TextBreak`](../elements/textbreak.md). +- [`Element > TOC`](../elements/toc.md). diff --git a/docs/usage/styles/indentation.md b/docs/usage/styles/indentation.md new file mode 100644 index 0000000000..78aa318fd1 --- /dev/null +++ b/docs/usage/styles/indentation.md @@ -0,0 +1,23 @@ +# Indentation Styles + +``` php +addParagraphStyle('line', ['indentation' => ['left' => 240, 'right' => 120]]); +$section->addText('Hello, World!', null, 'line'); + +``` + +See [`Sample_08_ParagraphPagination`](/samples/Sample_08_ParagraphPagination.php) for more code samples. + +## Options +- `left`. Left indentation in *twip*. +- `right`. Right indentation in *twip*. +- `firstLine`. Additional first line indentation in *twip*. +- `firstLineChars`. Additional first line chars indentation in *twip*. +- `hanging`. Indentation removed from first line *twip*. + +*Warning*: `firstLine[Chars]` and `hanging` cannot be used together. + +## Used In +- [`Style > Paragraph`](../styles/paragraph.md). diff --git a/docs/usage/styles/index.md b/docs/usage/styles/index.md new file mode 100644 index 0000000000..23ceeab890 --- /dev/null +++ b/docs/usage/styles/index.md @@ -0,0 +1,96 @@ +# Styles + +Styles can be added to various elements either by including them with the element or by adding the style to the PHPWord document. + +## Basic Example + +``` php +addFontStyle('subtitle', + array('name' => 'Arial', 'size' => 24, 'color' => '1B2232', 'bold' => true), + array('spacing' => 480, 'lineHeight' => 2, 'align' => JcType::Both), +); + +// Set the styles when adding an element. +$sectionStyle = ['paperSize' => 'Letter', 'vAlign' => VerticalType::CENTER]; +$section = $phpWord->addSection($sectionStyle); + +// Use a document level style. +$section->addText('Hello, World!', 'subtitle'); + +``` + +## Document Styles + +Document styles can be set by using the following functions. + +``` php +setDefaultFontName('Times New Roman'); +$phpWord->setDefaultFontColor('FF0000'); +$phpWord->setDefaultFontSize(12); +$phpWord->setDefaultAsianFontName('標楷體'); +$phpWord->setDefaultParagraphStyle($paragraphStyle); + +// Add Styles +$phpWord->addParagraphStyle($name, $paragraphStyle); +$phpWord->addFontStyle($name, $fontStyle, [$paragraphStyle]); +$phpWord->addLinkStyle($name, $linkStyle); +$phpWord->addNumberingStyle($name, $numberingStyle); +$phpWord->addTitleStyle($depth, $fontStyle, [$paragraphStyle]); +$phpWord->addTableStyle($name, $tableStyle, [$firstRowStyle]); + +``` +- `$name`. Name of the style. + * The names of all styles must be unique, regardless of style type. + * The names *normal*, *title*, and *heading* (including *heading_#*, where # is the `$depth`) are reserved. Use `setDefaultParagraphStyle` and `addTitleStyle` to set those names. +- `$depth`. Outline level of Title. See [`Elements > Title`](elements/title.md). +- `$fontStyle`. See [`Styles > Font`](styles/font.md). +- `$linkStyle`. See [`Styles > Link`](styles/link.md). +- `$numberingStyle`. See [`Styles > Numbering`](styles/numbering.md). +- `$paragraphStyle`. See [`Styles > Paragraph`](styles/paragraph.md). +- `$tableStyle`. See [`Styles > Table`](styles/table.md). +- `$firstRowStyle`. See [`Styles > Row`](styles/table.md). + +When adding font and paragraph styles, consider adding them in the following order to improve the end experience: +- Titles, using `addTitleStyle()`. +- Font and paragraph style combinations, using `addFontStyle()`. +- Paragraph styles based on other styles, using `addParagraphStyle()` with the `basedOn` keyword. +- Unique font and paragraph styles, using `addFontStyle()` and `addParagraphStyle()`. + +## PHPWord Style Classes +- [`Style > Border`](styles/border.md). +- [`Style > Cell`](styles/table.md). +- [`Style > Chart`](styles/chart.md). +- `Style > Extrusion`. +- `Style > Fill`. +- [`Style > Font`](styles/font.md). +- `Style > Frame`. +- [`Style > Image`](styles/image.md). +- [`Style > Indentation`](styles/indentation.md). +- [`Style > Language`](styles/language.md). +- `Style > Line`. +- [`Style > LineNumbering`](styles/linenumbering.md). +- [`Style > ListItem`](styles/list.md). +- [`Style > Numbering`](styles/numbering.md). +- `Style > NumberingLevel`. +- `Style > Outline`. +- [`Style > Paper`](styles/paper.md). +- [`Style > Paragraph`](styles/paragraph.md). +- [`Style > Row`](styles/table.md). +- [`Style > Section`](styles/section.md). +- `Style > Shading`. +- `Style > Shadow`. +- `Style > Shape`. +- `Style > Spacing`. +- `Style > TOC`. +- [`Style > Tab`](styles/tab.md). +- [`Style > Table`](styles/table.md). +- [`Style > TablePosition`](styles/table.md). +- `Style > TextBox`. + diff --git a/docs/usage/styles/language.md b/docs/usage/styles/language.md new file mode 100644 index 0000000000..948f61daa3 --- /dev/null +++ b/docs/usage/styles/language.md @@ -0,0 +1,16 @@ +# Language + +## Constants +- Languages + * `EN_US`, `EN_GB`, `FR_FR`, `FR_BE`, `FR_CH`, `ES_ES`, `DE_DE`, `DE_CH` + * `HE_IL`, `IT_IT`, `IT_CH`, `JA_JP`, `KO_KR`, `HI_IN`, `PT_BR`, `NL_NL` + * `SV_SE`, `UK_UA`, `RU_RU` + +## Options +- `langId`. Used for RTF document generation. +- `latin`. +- `eastAsia`. +- `bidirectional`. + +## Used In +- [`Style > Font`](../styles/font.md). diff --git a/docs/usage/styles/linenumbering.md b/docs/usage/styles/linenumbering.md new file mode 100644 index 0000000000..5fb7be254a --- /dev/null +++ b/docs/usage/styles/linenumbering.md @@ -0,0 +1,16 @@ +# Line Numbering + +## Constants + * `LINE_NUMBERING_CONTINUOUS` + * `LINE_NUMBERING_NEW_PAGE` + * `LINE_NUMBERING_NEW_SECTION` + +## Options +- `start`. Starting Value. `1` is default. +- `increment`. Increments. `1` is default. +- `distance`. Distance between text and line numbering in *twip*. +- `restart`. Line numbering restart setting. + * See constants above for possible values. + +## Used In +- [`Style > Section`](../styles/section.md). diff --git a/docs/usage/styles/list.md b/docs/usage/styles/list.md new file mode 100644 index 0000000000..55466a6f23 --- /dev/null +++ b/docs/usage/styles/list.md @@ -0,0 +1,29 @@ +# ListItem Styles + +``` php + ListStyle::TYPE_NUMBER_NESTED]; +$section->addListItem('List Item 1', 0, null, $listStyle); +``` + +See [`Sample_14_ListItem`](/samples/Sample_14_ListItem.php) for more code samples. + +## Constants +- `TYPE_SQUARE_FILLED`. +- `TYPE_BULLET_FILLED`. +- `TYPE_BULLET_EMPTY`. +- `TYPE_NUMBER`. +- `TYPE_NUMBER_NESTED`. L1: 1., L2: 1.1., L3: 1.1.1. etc. +- `TYPE_ALPHANUM`. L1: Decimal, L2: LowerLetter, L3: LowerRoman repeat. + +## Options +- `listType`. Predefined numbering styles. + * See constants above for possible values. +- `numStyle`. + * See [`Styles > Numbering`](../styles/numbering.md) for possible values. + +## Used In +- [`Element > ListItem`](../elements/list.md). +- [`Element > ListItemRun`](../elements/list.md). diff --git a/docs/usage/styles/numbering.md b/docs/usage/styles/numbering.md new file mode 100644 index 0000000000..e199ad470d --- /dev/null +++ b/docs/usage/styles/numbering.md @@ -0,0 +1,46 @@ +# Numbering Styles + +``` php +addNumberingStyle( + 'numberssAndLetters', + [ + 'type' => 'hybridMultilevel', + 'levels' => [ + ['format' => 'decimal', 'text' => '%1.', 'left' => 360, 'hanging' => 360, 'tabPos' => 360], + ['format' => 'upperLetter', 'text' => '%2.', 'left' => 720, 'hanging' => 360, 'tabPos' => 720], + ], + ] +); + +``` + +See [`Sample_14_ListItem`](/samples/Sample_14_ListItem.php) for more code samples. + +## Options +- `type`. List type, *singleLevel*, *multilevel*, or *hybridMultilevel*. + * `singleLevel` is a list with only a single level, such as a simple bullet or numbered list. + * `multilevel` is a list that can have multiple levels, but all levels use the same type of formatting (e.g., all bullets or all numbers). + * `hybridMultilevel` is a list that can have multiple levels, with different levels potentially using different formatting (e.g., some levels with bullets and others with numbers or letters). +- `levels`. The style for each level of the list. See below. + +## Level Options +- `align`. Same as alignment. +- `alignment`. Supports all alignment modes since 1st Edition of ECMA-376 standard up till ISO/IEC 29500:2012. + * See [`SimpleType > Jc`](../simpletypes/jc.md) for possible values. +- `font`. Font name, e.g. `Arial`. +- `format`. Numbering format. + * See [`SimpleType > NumberFormat`](../simpletypes/numberformat.md). +- `hanging`. Hanging in `twip`. +- `hint`. Font content type, `default`, `eastAsia`, or `cs`. +- `left`. Left in `twip`. +- `restart`. Restart numbering level symbol. +- `start`. Starting value. `1` is default. +- `suffix`. Content between numbering symbol and paragraph text, `tab`, `space`, or `nothing`. `tab` is default. +- `tabPos`. Tab position in `twip`. +- `text`. Numbering level text e.g. %1 for nonbullet or bullet character. + +## Used In +- [`Styles > ListItem`](../styles/list.md). +- [`Styles > Paragraph`](../styles/paragraph.md). diff --git a/docs/usage/styles/numberinglevel.md b/docs/usage/styles/numberinglevel.md deleted file mode 100644 index 392e820048..0000000000 --- a/docs/usage/styles/numberinglevel.md +++ /dev/null @@ -1,16 +0,0 @@ -# Numbering level - -Available NumberingLevel style options: - -- ``alignment``. Supports all alignment modes since 1st Edition of ECMA-376 standard up till ISO/IEC 29500:2012. - See ``\PhpOffice\PhpWord\SimpleType\Jc`` class constants for possible values. -- ``font``. Font name. -- ``format``. Numbering format bullet\|decimal\|upperRoman\|lowerRoman\|upperLetter\|lowerLetter. -- ``hanging``. See paragraph style. -- ``hint``. See font style. -- ``left``. See paragraph style. -- ``restart``. Restart numbering level symbol. -- ``start``. Starting value. -- ``suffix``. Content between numbering symbol and paragraph text tab\|space\|nothing. -- ``tabPos``. See paragraph style. -- ``text``. Numbering level text e.g. %1 for nonbullet or bullet character. \ No newline at end of file diff --git a/docs/usage/styles/paper.md b/docs/usage/styles/paper.md new file mode 100644 index 0000000000..cfb17e8b7d --- /dev/null +++ b/docs/usage/styles/paper.md @@ -0,0 +1,9 @@ +# Paper + +## Options +- `size`. Page size. `A4` is default. Possible values include: + * `A3`, `A4`, `A5`, `B5` + * `Letter`, `Legal`, `Folio` + +## Used In +- [`Style > Section`](../styles/section.md). diff --git a/docs/usage/styles/paragraph.md b/docs/usage/styles/paragraph.md index f51d5ba030..139acee402 100644 --- a/docs/usage/styles/paragraph.md +++ b/docs/usage/styles/paragraph.md @@ -1,29 +1,75 @@ -# Paragraph - -Available Paragraph style options: - -- ``alignment``. Supports all alignment modes since 1st Edition of ECMA-376 standard up till ISO/IEC 29500:2012. - See ``\PhpOffice\PhpWord\SimpleType\Jc`` class constants for possible values. -- ``basedOn``. Parent style. -- ``hanging``. Hanging indentation in *half inches*. -- ``indent``. Indent (left indentation) in *half inches*. -- ``indentation``. An array of indentation key => value pairs in *twip*. Supports *left*, *right*, *firstLine*, *firstLineChars* and *hanging* indentation. - See ``\PhpOffice\PhpWord\Style\Indentation`` for possible identation types. -- ``keepLines``. Keep all lines on one page, *true* or *false*. -- ``keepNext``. Keep paragraph with next paragraph, *true* or *false*. -- ``lineHeight``. Text line height, e.g. *1.0*, *1.5*, etc. -- ``next``. Style for next paragraph. -- ``pageBreakBefore``. Start paragraph on next page, *true* or *false*. -- ``spaceBefore``. Space before paragraph in *twip*. -- ``spaceAfter``. Space after paragraph in *twip*. -- ``spacing``. Space between lines in *twip*. If spacingLineRule is auto, 240 (height of 1 line) will be added, so if you want a double line height, set this to 240. -- ``spacingLineRule``. Line Spacing Rule. *auto*, *exact*, *atLeast* - See ``\PhpOffice\PhpWord\SimpleType\LineSpacingRule`` class constants for possible values. -- ``suppressAutoHyphens``. Hyphenation for paragraph, *true* or *false*. -- ``tabs``. Set of custom tab stops. -- ``widowControl``. Allow first/last line to display on a separate page, *true* or *false*. -- ``contextualSpacing``. Ignore Spacing Above and Below When Using Identical Styles, *true* or *false*. -- ``bidi``. Right to Left Paragraph Layout, *true* or *false*. -- ``shading``. Paragraph Shading. -- ``textAlignment``. Vertical Character Alignment on Line. - See ``\PhpOffice\PhpWord\SimpleType\TextAlignment`` class constants for possible values. \ No newline at end of file +# Paragraph Styles + +``` php +addParagraphStyle('header', ['align' => 'center', 'spaceAfter' => 240]); +$section->addText('Hello, World!', null, 'header'); + +``` + +``` php + JcType::BOTH, 'keepNext' => true]; +$section->addText('Hello, World!', null, $paragraphStyle); + +``` + +See [`Sample_01_SimpleText`](/samples/Sample_01_SimpleText.php) and [`Sample_08_ParagraphPagination`](/samples/Sample_08_ParagraphPagination.php) for more code samples. + +## Constants +- `LINE_HEIGHT` = `240` + +## Options +- `align`. Same as alignment. +- `alignment`. Supports all alignment modes since 1st Edition of ECMA-376 standard up till ISO/IEC 29500:2012. + * See [`SimpleType > Jc`](../simpletypes/jc.md) for possible values. +- `basedOn`. Parent style. +- `bidi`. Right to Left Paragraph Layout, *true* or *false*. +- `contextualSpacing`. Ignore Spacing Above and Below When Using Identical Styles, *true* or *false*. +- `indentation`. An array of indentation key => value pairs in *twip*. Supports *left*, *right*, *firstLine*, *firstLineChars* and *hanging* indentation. + * See [`Style > Indentation`](../styles/indentation.md) for possible identation types. +- `indentHanging`. Hanging indentation in *half inches*. +- `indentFirstLine`. First line indentation in *half inches*. +- `indentFirstLineChars`. First line character indentation in *half inches*. +- `indentLeft`. Left indentation in *half inches*. +- `indentRight`. Right indentation in *half inches*. +- `keepLines`. Keep all lines on one page, *true* or *false*. +- `keepNext`. Keep paragraph with next paragraph, *true* or *false*. +- `lineHeight`. Text line height, e.g. *1.0*, *1.5*, etc. +- `next`. Style for next paragraph. +- `numLevel`. Numbering level. `0` is default. +- `numStyle`. Numbering style name + * See [`Style > Numbering`](../styles/numbering.md). +- `pageBreakBefore`. Start paragraph on next page, *true* or *false*. +- `shading`. Paragraph Shading. +- `spaceAfter`. Space after paragraph in *twip*. +- `spaceBefore`. Space before paragraph in *twip*. +- `spacing`. Space between lines in *twip*. If spacingLineRule is auto, 240 (height of 1 line) will be added, so if you want a double line height, set this to 240. +- `spacingLineRule`. Line Spacing Rule. *auto*, *exact*, *atLeast* + * See [`SimpleType > LineSpacingRule`](../simpletypes/linespacingrule.md) class constants for possible values. +- `suppressAutoHyphens`. Hyphenation for paragraph, *true* or *false*. Only matters if [`Settings > AutoHyphenation](..settings.md) is *true*. +- `tabs`. Set of custom tab stops. + * See [`Style > Tab`](../styles/tab.md). +- `widowControl`. Allow first/last line to display on a separate page, *true* or *false*. +- `textAlignment`. Vertical Character Alignment on Line. + * See [`SimpleType > TextAlignment`](/docs/usage/simpletypes/textalignment.md) class constants for possible values. + +### Extends Border +- See [`Style > Border`](../styles/border.md) for additional options. + +## Used In +- [`Element > CheckBox`](../elements/checkbox.md). +- [`Element > Endnote`](../elements/endnote.md). +- [`Element > Footnote`](../elements/footnote.md). +- [`Element > FormField`](../elements/formfield.md). +- [`Element > Link`](../elements/link.md). +- [`Element > ListItem`](../elements/list.md). +- [`Element > ListItemRun`](../elements/list.md). +- [`Element > PreserveText`](../elements/preservetext.md). +- [`Element > SDT`](../elements/sdt.md). +- [`Element > Text`](../elements/text.md). +- [`Element > TextBreak`](../elements/textbreak.md). +- [`Element > TextRun`](../elements/text.md). diff --git a/docs/usage/styles/section.md b/docs/usage/styles/section.md index 2be22e8077..61ab196200 100644 --- a/docs/usage/styles/section.md +++ b/docs/usage/styles/section.md @@ -1,28 +1,42 @@ -# Section +# Section Styles -Available Section style options: +``` php + 'Letter', 'vAlign' => VerticalType::CENTER]; +$section = $phpWord->addSection($sectionStyle); +``` + +See [`Sample_03_Sections`](/samples/Sample_03_Sections.php) for more code samples. + +## Constants +- Orientation + * `ORIENTATION_PORTRAIT` + * `ORIENTATION_LANDSCAPE` + +## Options +- `breakType`. Section break type (`nextPage`, `nextColumn`, `continuous`, `evenPage`, `oddPage`). +- `colsNum`. Number of columns. `1` is default. +- `colsSpace`. Spacing between columns. `720` is default. +- `footerHeight`. Spacing to bottom of footer. `720` is default. +- `gutter`. Page gutter spacing. `0` is default. +- `headerHeight`. Spacing to top of header. `720` is default. +- `lineNumbering`. Line numbering. + * See [`Style > LineNumbering`](../styles/linenumbering.md) for possible values. +- `orientation`. Page orientation. `ORIENTATION_PORTRAIT` is default. + * **IMPORTANT**: Orientation must be set *after* paperSize, pageSizeH, and pageSizeW to work. + * See constants above for possible values. +- `pageNumberingStart`. Starting page number. +- `pageSizeH`. Page height in *twip*. `16837.79527559` is default. +- `pageSizeW`. Page width in *twip*. `11905.511811024` is default. +- `paperSize`. Paper size. `A4` is default. + * See [`Style > Paper`](../styles/paper.md) for possible values +- `vAlign`. Vertical page alignment. + * See [`SimpleType > VerticalJc`](../simpletypes/verticaljc.md) for possible values. + +### Extends Border +- See [`Style > Border`](../styles/border.md) for additional options. + +## Used In +- [`Element > Section`](../elements/section.md). diff --git a/docs/usage/styles/tab.md b/docs/usage/styles/tab.md new file mode 100644 index 0000000000..104201c034 --- /dev/null +++ b/docs/usage/styles/tab.md @@ -0,0 +1,48 @@ +# Tab Style + +``` php +addParagraphStyle( + 'tabStyle', + [ + 'tabs' => [ + new TabStyle(TabStyle::TAB_STOP_LEFT, 1440, TabStyle::TAB_LEADER_DOT), + new TabStyle(TabStyle::TAB_STOP_CENTER, 5000), + new TabStyle(TabStyle::TAB_STOP_RIGHT, 9340), + ], + ] +); + +``` + +See [`Sample_02_TabStops`](/samples/Sample_02_TabStops.php) for more code samples. + +## Constants +- Tab Stop + * `TAB_STOP_CLEAR` + * `TAB_STOP_LEFT` + * `TAB_STOP_CENTER` + * `TAB_STOP_RIGHT` + * `TAB_STOP_DECIMAL` + * `TAB_STOP_BAR` + * `TAB_STOP_NUM` + +- Tab Leader + * `TAB_LEADER_NONE` + * `TAB_LEADER_DOT` + * `TAB_LEADER_HYPHEN` + * `TAB_LEADER_UNDERSCORE` + * `TAB_LEADER_HEAVY` + * `TAB_LEADER_MIDDLEDOT` + +## Options +- `type`. Stop type. `TAB_STOP_CLEAR` is default. + * See constants above for possible values. +- `leader`. Tab leader character. `TAB_LEADER_NONE` is default. + * See constants above for possible values. +- `position`. Tab stop position in *twip*. + +## Used In +- [`Style > Paragraph`](../styles/paragraph.md). diff --git a/docs/usage/styles/table.md b/docs/usage/styles/table.md index 1f82f3c638..0a21ca2e05 100644 --- a/docs/usage/styles/table.md +++ b/docs/usage/styles/table.md @@ -1,49 +1,92 @@ -# Table - -Available Table style options: - -- ``alignment``. Supports all alignment modes since 1st Edition of ECMA-376 standard up till ISO/IEC 29500:2012. - See ``\PhpOffice\PhpWord\SimpleType\JcTable`` and ``\PhpOffice\PhpWord\SimpleType\Jc`` class constants for possible values. -- ``bgColor``. Background color, e.g. '9966CC'. -- ``border(Top|Right|Bottom|Left)Color``. Border color, e.g. '9966CC'. -- ``border(Top|Right|Bottom|Left)Size``. Border size in *twip*. -- ``cellMargin(Top|Right|Bottom|Left)``. Cell margin in *twip*. -- ``indent``. Table indent from leading margin. Must be an instance of ``\PhpOffice\PhpWord\ComplexType\TblWidth``. -- ``width``. Table width in Fiftieths of a Percent or Twentieths of a Point. -- ``unit``. The unit to use for the width. One of ``\PhpOffice\PhpWord\SimpleType\TblWidth``. Defaults to *auto*. -- ``layout``. Table layout, either *fixed* or *autofit* See ``\PhpOffice\PhpWord\Style\Table`` for constants. -- ``cellSpacing`` Cell spacing in *twip* -- ``position`` Floating Table Positioning, see below for options -- ``bidiVisual`` Present table as Right-To-Left - -Floating Table Positioning options: - -- ``leftFromText`` Distance From Left of Table to Text in *twip* -- ``rightFromText`` Distance From Right of Table to Text in *twip* -- ``topFromText`` Distance From Top of Table to Text in *twip* -- ``bottomFromText`` Distance From Top of Table to Text in *twip* -- ``vertAnchor`` Table Vertical Anchor, one of ``\PhpOffice\PhpWord\Style\TablePosition::VANCHOR_*`` -- ``horzAnchor`` Table Horizontal Anchor, one of ``\PhpOffice\PhpWord\Style\TablePosition::HANCHOR_*`` -- ``tblpXSpec`` Relative Horizontal Alignment From Anchor, one of ``\PhpOffice\PhpWord\Style\TablePosition::XALIGN_*`` -- ``tblpX`` Absolute Horizontal Distance From Anchorin *twip* -- ``tblpYSpec`` Relative Vertical Alignment From Anchor, one of ``\PhpOffice\PhpWord\Style\TablePosition::YALIGN_*`` -- ``tblpY`` Absolute Vertical Distance From Anchorin *twip* - -Available Row style options: - -- ``cantSplit``. Table row cannot break across pages, *true* or *false*. -- ``exactHeight``. Row height is exact or at least. -- ``tblHeader``. Repeat table row on every new page, *true* or *false*. - -Available Cell style options: - -- ``bgColor``. Background color, e.g. '9966CC'. -- ``border(Top|Right|Bottom|Left)Color``. Border color, e.g. '9966CC'. -- ``border(Top|Right|Bottom|Left)Size``. Border size in *twip*. -- ``border(Top|Right|Bottom|Left)Style``. Border style. You can use constants from ``\PhpOffice\PhpWord\SimpleType\Border`` -- ``gridSpan``. Number of columns spanned. -- ``textDirection(btLr|tbRl)``. Direction of text. - You can use constants ``\PhpOffice\PhpWord\Style\Cell::TEXT_DIR_BTLR`` and ``\PhpOffice\PhpWord\Style\Cell::TEXT_DIR_TBRL`` -- ``valign``. Vertical alignment, *top*, *center*, *both*, *bottom*. -- ``vMerge``. *restart* or *continue*. -- ``width``. Cell width in *twip*. \ No newline at end of file +# Table, Row, and Cell + +``` php + '006699', 'borderSize' => 6, 'cellMargin' => 50]; +$firstRowStyle = ['bgColor' => '66BBFF']; +$phpWord->addTableStyle('myTable', $tableStyle, $firstRowStyle); +$table = $section->addTable('myTable'); + +``` + +See [`Sample_09_Tables`](/samples/Sample_09_Tables.php) and [`Sample_21_TableRowRules`](/samples/Sample_21_TableRowRules.php) for more code samples. + +## Table Constants +- Layout + * `LAYOUT_AUTO`. AutoFit table layout. + * `LAYOUT_FIXED`. Fixed width table layout. + +## Table Options +- `align`. Same as alignment. +- `alignment`. Supports all alignment modes since 1st Edition of ECMA-376 standard up till ISO/IEC 29500:2012. + * See [`SimpleType > JcTable`](../simpletypes/jctable.md) and [`SimpleType > Jc`](../simpletypes/jc.md) for possible values. +- `bidiVisual` Present table as Right-To-Left +- `bgColor`. Background color, e.g. *9966CC*. +- `border(Top|Right|Bottom|Left|InsideH|InsideV)Color`. Border color, e.g. '9966CC'. +- `border(Top|Right|Bottom|Left|InsideH|InsideV)Size`. Border size in *twip*. +- `cellMargin(Top|Right|Bottom|Left)`. Cell margin in *twip*. +- `cellSpacing` Cell spacing in *twip* +- `columnWidths` Array of widths for each column. +- `indent`. Table indent from leading margin. Must be an instance of `\PhpOffice\PhpWord\ComplexType\TblWidth`. +- `layout`. Table layout, either *fixed* or *autofit*. Defaults to *autofit*. + * See constants above for possible values. +- `position` Floating Table Positioning, see below for options +- `shading`. Table Shading. +- `width`. Table width in Fiftieths of a Percent or Twentieths of a Point. +- `unit`. The unit to use for the width. Defaults to *auto*. + * See [`SimpleType > TblWidth`](../simpletypes/tblwidth.md) and [`SimpleType > TblWidth`](../simpletypes/tblwidth.md) for possible values. + +### Extends Border +- See [`Style > Border`](../styles/border.md) for additional options. + +## Floating Table Positioning Options +- `leftFromText` Distance From Left of Table to Text in *twip* +- `rightFromText` Distance From Right of Table to Text in *twip* +- `topFromText` Distance From Top of Table to Text in *twip* +- `bottomFromText` Distance From Top of Table to Text in *twip* +- `vertAnchor` Table Vertical Anchor, one of `\PhpOffice\PhpWord\Style\TablePosition::VANCHOR_*` +- `horzAnchor` Table Horizontal Anchor, one of `\PhpOffice\PhpWord\Style\TablePosition::HANCHOR_*` +- `tblpXSpec` Relative Horizontal Alignment From Anchor, one of `\PhpOffice\PhpWord\Style\TablePosition::XALIGN_*` +- `tblpX` Absolute Horizontal Distance From Anchorin *twip* +- `tblpYSpec` Relative Vertical Alignment From Anchor, one of `\PhpOffice\PhpWord\Style\TablePosition::YALIGN_*` +- `tblpY` Absolute Vertical Distance From Anchorin *twip* + +## Row Options +- `cantSplit`. Table row cannot break across pages, *true* or *false*. Default is *false*. +- `exactHeight`. Row height is exact or at least. Default is *false*. +- `tblHeader`. Repeat table row on every new page, *true* or *false*. Default is *false*. + +## Cell Constants +- Text Direction + * `TEXT_DIR_LRTB`. Left to Right, Top to Bottom. + * `TEXT_DIR_TBRL`. Top to Bottom, Right to Left. + * `TEXT_DIR_BTLR`. Bottom to Top, Left to Right. + * `TEXT_DIR_LRTBV`. Left to Right, Top to Bottom Rotated. + * `TEXT_DIR_TBRLV`. Top to Bottom, Right to Left Rotated. + * `TEXT_DIR_TBLRV`. Top to Bottom, Left to Right Rotated. +- Vertical merge (rowspan). + * `VMERGE_RESTART`. + * `VMERGE_CONTINUE`. +- Default Border Color. + * `DEFAULT_BORDER_COLOR`. *000000*. + +## Cell Options +- `bgColor`. Background color, e.g. '9966CC'. +- `gridSpan`. Number of columns spanned. +- `noWrap`. Prevent text from wrapping in the cell. Default is *true*. +- `padding(Top|Right|Bottom|Left)`. Cell padding in *twip*. +- `shading`. Cell Shading. +- `textDirection`. Direction of text. + * See constants above for possible values. +- `valign`. Vertical alignment, *top*, *center*, *both*, *bottom*. +- `vMerge`. *restart* or *continue*. +- `width`. Cell width in *twip*. +- `unit`. The unit to use for the width. Defaults to *auto*. + * See [`SimpleType > TblWidth`](../simpletypes/tblwidth.md) and [`SimpleType > TblWidth`](../simpletypes/tblwidth.md) for possible values. + +### Extends Border +- See [`Style > Border`](../styles/border.md) for additional options. + +## Used In +- [`Element > Table`](../elements/table.md).