Brak opisu

elements.rst 17KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512
  1. .. _elements:
  2. Elements
  3. ========
  4. Below are the matrix of element availability in each container. The
  5. column shows the containers while the rows lists the elements.
  6. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  7. | Num | Element | Section | Header | Footer | Cell | Text Run | Footnote |
  8. +=======+=================+===========+==========+==========+=========+============+============+
  9. | 1 | Text | v | v | v | v | v | v |
  10. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  11. | 2 | Text Run | v | v | v | v | - | - |
  12. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  13. | 3 | Link | v | v | v | v | v | v |
  14. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  15. | 4 | Title | v | ? | ? | ? | ? | ? |
  16. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  17. | 5 | Preserve Text | ? | v | v | v\* | - | - |
  18. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  19. | 6 | Text Break | v | v | v | v | v | v |
  20. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  21. | 7 | Page Break | v | - | - | - | - | - |
  22. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  23. | 8 | List | v | v | v | v | - | - |
  24. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  25. | 9 | Table | v | v | v | v | - | - |
  26. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  27. | 10 | Image | v | v | v | v | v | v |
  28. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  29. | 11 | Watermark | - | v | - | - | - | - |
  30. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  31. | 12 | Object | v | v | v | v | v | v |
  32. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  33. | 13 | TOC | v | - | - | - | - | - |
  34. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  35. | 14 | Footnote | v | - | - | v\*\* | v\*\* | - |
  36. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  37. | 15 | Endnote | v | - | - | v\*\* | v\*\* | - |
  38. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  39. | 16 | CheckBox | v | v | v | v | - | - |
  40. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  41. | 17 | TextBox | v | v | v | v | - | - |
  42. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  43. | 18 | Field | v | v | v | v | v | v |
  44. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  45. | 19 | Line | v | v | v | v | v | v |
  46. +-------+-----------------+-----------+----------+----------+---------+------------+------------+
  47. Legend:
  48. - ``v`` Available
  49. - ``v*`` Available only when inside header/footer
  50. - ``v**`` Available only when inside section
  51. - ``-`` Not available
  52. - ``?`` Should be available
  53. Texts
  54. -----
  55. Text can be added by using ``addText`` and ``addTextRun`` method.
  56. ``addText`` is used for creating simple paragraphs that only contain
  57. texts with the same style. ``addTextRun`` is used for creating complex
  58. paragraphs that contain text with different style (some bold, other
  59. italics, etc) or other elements, e.g. images or links. The syntaxes are
  60. as follow:
  61. .. code-block:: php
  62. $section->addText($text, [$fontStyle], [$paragraphStyle]);
  63. $textrun = $section->addTextRun([$paragraphStyle]);
  64. Text styles
  65. ~~~~~~~~~~~
  66. You can use the ``$fontStyle`` and ``$paragraphStyle`` variable to
  67. define text formatting. There are 2 options to style the inserted text
  68. elements, i.e. inline style by using array or defined style by adding
  69. style definition.
  70. Inline style examples:
  71. .. code-block:: php
  72. $fontStyle = array('name' => 'Times New Roman', 'size' => 9);
  73. $paragraphStyle = array('align' => 'both');
  74. $section->addText('I am simple paragraph', $fontStyle, $paragraphStyle);
  75. $textrun = $section->addTextRun();
  76. $textrun->addText('I am bold', array('bold' => true));
  77. $textrun->addText('I am italic', array('italic' => true));
  78. $textrun->addText('I am colored', array('color' => 'AACC00'));
  79. Defined style examples:
  80. .. code-block:: php
  81. $fontStyle = array('color' => '006699', 'size' => 18, 'bold' => true);
  82. $phpWord->addFontStyle('fStyle', $fontStyle);
  83. $text = $section->addText('Hello world!', 'fStyle');
  84. $paragraphStyle = array('align' => 'center');
  85. $phpWord->addParagraphStyle('pStyle', $paragraphStyle);
  86. $text = $section->addText('Hello world!', 'pStyle');
  87. Font style
  88. ^^^^^^^^^^
  89. Available font styles:
  90. - ``name`` Font name, e.g. *Arial*
  91. - ``size`` Font size, e.g. *20*, *22*,
  92. - ``hint`` Font content type, *default*, *eastAsia*, or *cs*
  93. - ``bold`` Bold, *true* or *false*
  94. - ``italic`` Italic, *true* or *false*
  95. - ``superScript`` Superscript, *true* or *false*
  96. - ``subScript`` Subscript, *true* or *false*
  97. - ``underline`` Underline, *dash*, *dotted*, etc.
  98. - ``strikethrough`` Strikethrough, *true* or *false*
  99. - ``doubleStrikethrough`` Double strikethrough, *true* or *false*
  100. - ``color`` Font color, e.g. *FF0000*
  101. - ``fgColor`` Font highlight color, e.g. *yellow*, *green*, *blue*
  102. - ``bgColor`` Font background color, e.g. *FF0000*
  103. - ``smallCaps`` Small caps, *true* or *false*
  104. - ``allCaps`` All caps, *true* or *false*
  105. Paragraph style
  106. ^^^^^^^^^^^^^^^
  107. Available paragraph styles:
  108. - ``align`` Paragraph alignment, *left*, *right* or *center*
  109. - ``spaceBefore`` Space before paragraph
  110. - ``spaceAfter`` Space after paragraph
  111. - ``indent`` Indent by how much
  112. - ``hanging`` Hanging by how much
  113. - ``basedOn`` Parent style
  114. - ``next`` Style for next paragraph
  115. - ``widowControl`` Allow first/last line to display on a separate page,
  116. *true* or *false*
  117. - ``keepNext`` Keep paragraph with next paragraph, *true* or *false*
  118. - ``keepLines`` Keep all lines on one page, *true* or *false*
  119. - ``pageBreakBefore`` Start paragraph on next page, *true* or *false*
  120. - ``lineHeight`` text line height, e.g. *1.0*, *1.5*, ect...
  121. - ``tabs`` Set of custom tab stops
  122. Titles
  123. ~~~~~~
  124. If you want to structure your document or build table of contents, you
  125. need titles or headings. To add a title to the document, use the
  126. ``addTitleStyle`` and ``addTitle`` method.
  127. .. code-block:: php
  128. $phpWord->addTitleStyle($depth, [$fontStyle], [$paragraphStyle]);
  129. $section->addTitle($text, [$depth]);
  130. Its necessary to add a title style to your document because otherwise
  131. the title won't be detected as a real title.
  132. Links
  133. ~~~~~
  134. You can add Hyperlinks to the document by using the function addLink:
  135. .. code-block:: php
  136. $section->addLink($linkSrc, [$linkName], [$fontStyle], [$paragraphStyle]);
  137. - ``$linkSrc`` The URL of the link.
  138. - ``$linkName`` Placeholder of the URL that appears in the document.
  139. - ``$fontStyle`` See "Font style" section.
  140. - ``$paragraphStyle`` See "Paragraph style" section.
  141. Preserve texts
  142. ~~~~~~~~~~~~~~
  143. The ``addPreserveText`` method is used to add a page number or page
  144. count to headers or footers.
  145. .. code-block:: php
  146. $footer->addPreserveText('Page {PAGE} of {NUMPAGES}.');
  147. Breaks
  148. ------
  149. Text breaks
  150. ~~~~~~~~~~~
  151. Text breaks are empty new lines. To add text breaks, use the following
  152. syntax. All paramaters are optional.
  153. .. code-block:: php
  154. $section->addTextBreak([$breakCount], [$fontStyle], [$paragraphStyle]);
  155. - ``$breakCount`` How many lines
  156. - ``$fontStyle`` See "Font style" section.
  157. - ``$paragraphStyle`` See "Paragraph style" section.
  158. Page breaks
  159. ~~~~~~~~~~~
  160. There are two ways to insert a page breaks, using the ``addPageBreak``
  161. method or using the ``pageBreakBefore`` style of paragraph.
  162. :: code-block:: php
  163. \\$section->addPageBreak();
  164. Lists
  165. -----
  166. To add a list item use the function ``addListItem``.
  167. Basic usage:
  168. .. code-block:: php
  169. $section->addListItem($text, [$depth], [$fontStyle], [$listStyle], [$paragraphStyle]);
  170. Parameters:
  171. - ``$text`` Text that appears in the document.
  172. - ``$depth`` Depth of list item.
  173. - ``$fontStyle`` See "Font style" section.
  174. - ``$listStyle`` List style of the current element TYPE\_NUMBER,
  175. TYPE\_ALPHANUM, TYPE\_BULLET\_FILLED, etc. See list of constants in
  176. PHPWord\_Style\_ListItem.
  177. - ``$paragraphStyle`` See "Paragraph style" section.
  178. Advanced usage:
  179. You can also create your own numbering style by changing the
  180. ``$listStyle`` parameter with the name of your numbering style.
  181. .. code-block:: php
  182. $phpWord->addNumberingStyle(
  183. 'multilevel',
  184. array('type' => 'multilevel', 'levels' => array(
  185. array('format' => 'decimal', 'text' => '%1.', 'left' => 360, 'hanging' => 360, 'tabPos' => 360),
  186. array('format' => 'upperLetter', 'text' => '%2.', 'left' => 720, 'hanging' => 360, 'tabPos' => 720),
  187. )
  188. )
  189. );
  190. $section->addListItem('List Item I', 0, null, 'multilevel');
  191. $section->addListItem('List Item I.a', 1, null, 'multilevel');
  192. $section->addListItem('List Item I.b', 1, null, 'multilevel');
  193. $section->addListItem('List Item II', 0, null, 'multilevel');
  194. Level styles:
  195. - ``start`` Starting value
  196. - ``format`` Numbering format
  197. bullet\|decimal\|upperRoman\|lowerRoman\|upperLetter\|lowerLetter
  198. - ``restart`` Restart numbering level symbol
  199. - ``suffix`` Content between numbering symbol and paragraph text
  200. tab\|space\|nothing
  201. - ``text`` Numbering level text e.g. %1 for nonbullet or bullet
  202. character
  203. - ``align`` Numbering symbol align left\|center\|right\|both
  204. - ``left`` See paragraph style
  205. - ``hanging`` See paragraph style
  206. - ``tabPos`` See paragraph style
  207. - ``font`` Font name
  208. - ``hint`` See font style
  209. Tables
  210. ------
  211. To add tables, rows, and cells, use the ``addTable``, ``addRow``, and
  212. ``addCell`` methods:
  213. .. code-block:: php
  214. $table = $section->addTable([$tableStyle]);
  215. $table->addRow([$height], [$rowStyle]);
  216. $cell = $table->addCell($width, [$cellStyle]);
  217. Table style can be defined with ``addTableStyle``:
  218. .. code-block:: php
  219. $tableStyle = array(
  220. 'borderColor' => '006699',
  221. 'borderSize' => 6,
  222. 'cellMargin' => 50
  223. );
  224. $firstRowStyle = array('bgColor' => '66BBFF');
  225. $phpWord->addTableStyle('myTable', $tableStyle, $firstRowStyle);
  226. $table = $section->addTable('myTable');
  227. Table, row, and cell styles
  228. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  229. Table styles:
  230. - ``width`` Table width in percent
  231. - ``bgColor`` Background color, e.g. '9966CC'
  232. - ``border(Top|Right|Bottom|Left)Size`` Border size in twips
  233. - ``border(Top|Right|Bottom|Left)Color`` Border color, e.g. '9966CC'
  234. - ``cellMargin(Top|Right|Bottom|Left)`` Cell margin in twips
  235. Row styles:
  236. - ``tblHeader`` Repeat table row on every new page, *true* or *false*
  237. - ``cantSplit`` Table row cannot break across pages, *true* or *false*
  238. - ``exactHeight`` Row height is exact or at least
  239. Cell styles:
  240. - ``width`` Cell width in twips
  241. - ``valign`` Vertical alignment, *top*, *center*, *both*, *bottom*
  242. - ``textDirection`` Direction of text
  243. - ``bgColor`` Background color, e.g. '9966CC'
  244. - ``border(Top|Right|Bottom|Left)Size`` Border size in twips
  245. - ``border(Top|Right|Bottom|Left)Color`` Border color, e.g. '9966CC'
  246. - ``gridSpan`` Number of columns spanned
  247. - ``vMerge`` *restart* or *continue*
  248. Cell span
  249. ~~~~~~~~~
  250. You can span a cell on multiple columns by using ``gridSpan`` or
  251. multiple rows by using ``vMerge``.
  252. .. code-block:: php
  253. $cell = $table->addCell(200);
  254. $cell->getStyle()->setGridSpan(5);
  255. See ``Sample_09_Tables.php`` for more code sample.
  256. Images
  257. ------
  258. To add an image, use the ``addImage`` method to sections, headers,
  259. footers, textruns, or table cells.
  260. .. code-block:: php
  261. $section->addImage($src, [$style]);
  262. - source String path to a local image or URL of a remote image
  263. - styles Array fo styles for the image. See below.
  264. Examples:
  265. .. code-block:: php
  266. $section = $phpWord->addSection();
  267. $section->addImage(
  268. 'mars.jpg',
  269. array(
  270. 'width' => 100,
  271. 'height' => 100,
  272. 'marginTop' => -1,
  273. 'marginLeft' => -1,
  274. 'wrappingStyle' => 'behind'
  275. )
  276. );
  277. $footer = $section->addFooter();
  278. $footer->addImage('http://example.com/image.php');
  279. $textrun = $section->addTextRun();
  280. $textrun->addImage('http://php.net/logo.jpg');
  281. Image styles
  282. ~~~~~~~~~~~~
  283. Available image styles:
  284. - ``width`` Width in pixels
  285. - ``height`` Height in pixels
  286. - ``align`` Image alignment, *left*, *right*, or *center*
  287. - ``marginTop`` Top margin in inches, can be negative
  288. - ``marginLeft`` Left margin in inches, can be negative
  289. - ``wrappingStyle`` Wrapping style, *inline*, *square*, *tight*,
  290. *behind*, or *infront*
  291. Watermarks
  292. ~~~~~~~~~~
  293. To add a watermark (or page background image), your section needs a
  294. header reference. After creating a header, you can use the
  295. ``addWatermark`` method to add a watermark.
  296. .. code-block:: php
  297. $section = $phpWord->addSection();
  298. $header = $section->addHeader();
  299. $header->addWatermark('resources/_earth.jpg', array('marginTop' => 200, 'marginLeft' => 55));
  300. Objects
  301. -------
  302. You can add OLE embeddings, such as Excel spreadsheets or PowerPoint
  303. presentations to the document by using ``addObject`` method.
  304. .. code-block:: php
  305. $section->addObject($src, [$style]);
  306. Table of contents
  307. -----------------
  308. To add a table of contents (TOC), you can use the ``addTOC`` method.
  309. Your TOC can only be generated if you have add at least one title (See
  310. "Titles").
  311. .. code-block:: php
  312. $section->addTOC([$fontStyle], [$tocStyle], [$minDepth], [$maxDepth]);
  313. - ``$fontStyle``: See font style section
  314. - ``$tocStyle``: See available options below
  315. - ``$minDepth``: Minimum depth of header to be shown. Default 1
  316. - ``$maxDepth``: Maximum depth of header to be shown. Default 9
  317. Options for ``$tocStyle``:
  318. - ``tabLeader`` Fill type between the title text and the page number.
  319. Use the defined constants in PHPWord\_Style\_TOC.
  320. - ``tabPos`` The position of the tab where the page number appears in
  321. twips.
  322. - ``indent`` The indent factor of the titles in twips.
  323. Footnotes & endnotes
  324. --------------------
  325. You can create footnotes with ``addFootnote`` and endnotes with
  326. ``addEndnote`` in texts or textruns, but it's recommended to use textrun
  327. to have better layout. You can use ``addText``, ``addLink``,
  328. ``addTextBreak``, ``addImage``, ``addObject`` on footnotes and endnotes.
  329. On textrun:
  330. .. code-block:: php
  331. $textrun = $section->addTextRun();
  332. $textrun->addText('Lead text.');
  333. $footnote = $textrun->addFootnote();
  334. $footnote->addText('Footnote text can have ');
  335. $footnote->addLink('http://test.com', 'links');
  336. $footnote->addText('.');
  337. $footnote->addTextBreak();
  338. $footnote->addText('And text break.');
  339. $textrun->addText('Trailing text.');
  340. $endnote = $textrun->addEndnote();
  341. $endnote->addText('Endnote put at the end');
  342. On text:
  343. .. code-block:: php
  344. $section->addText('Lead text.');
  345. $footnote = $section->addFootnote();
  346. $footnote->addText('Footnote text.');
  347. The footnote reference number will be displayed with decimal number
  348. starting from 1. This number use ``FooterReference`` style which you can
  349. redefine by ``addFontStyle`` method. Default value for this style is
  350. ``array('superScript' => true)``;
  351. Checkboxes
  352. ----------
  353. Checkbox elements can be added to sections or table cells by using
  354. ``addCheckBox``.
  355. .. code-block:: php
  356. $section->addCheckBox($name, $text, [$fontStyle], [$paragraphStyle])
  357. - ``$name`` Name of the check box.
  358. - ``$text`` Text following the check box
  359. - ``$fontStyle`` See "Font style" section.
  360. - ``$paragraphStyle`` See "Paragraph style" section.
  361. Textboxes
  362. ---------
  363. To be completed
  364. Fields
  365. ------
  366. To be completed
  367. Line
  368. ------
  369. Line elements can be added to sections by using ``addLine``.
  370. .. code-block:: php
  371. $linestyle = array('weight' => 1, 'width' => 100, 'height' => 0, 'color' => 635552);
  372. $section->addLine($lineStyle)
  373. Available line style attributes:
  374. - ``weight`` Line width in twips
  375. - ``color`` Defines the color of stroke
  376. - ``dash`` Line types: dash, rounddot, squaredot, dashdot, longdash, longdashdot, longdashdotdot
  377. - ``beginArrow`` Start type of arrow: block, open, classic, diamond, oval
  378. - ``endArrow`` End type of arrow: block, open, classic, diamond, ovel
  379. - ``width`` Line-object width in pt
  380. - ``height`` Line-object height in pt
  381. - ``flip`` Flip the line element: true, false