addText

addText

TRIAL / ADVANCED / PREMIUM

Inserts a paragraph into a Word document.

Description
public addText ( mixed $paragraphContents [, array $paragraphOptions = array()] )

This method allows the insertion of a paragraph into a Word document.

You may include in your paragraph:

  • multiple runs of text with diverse formatting
  • inline and floating images
  • inline and floating charts
  • footnotes and endnotes
  • all kinds of different line breaks (line, column, page)
  • all kind of different tabs (light, right, center with leading characters or not)
  • links and bookmarks
  • page numbers
  • date and hour
  • form elements
  • shapes
  • inline HTML content

You may, in general, insert any "inline". If you try to insert a block type element, like a table, its inline contents will be extracted and inserted ignoring the containing block element.

Parameters

paragraphContents

This could be:

  • a simple string of text.
  • a WordFragment.
  • an array. Each of the elements of this array may be a WordFragment or an array with the following keys and values (required options are shown with yellow background):
Key Type Description
text string The text to be inserted.
bold bool If true the text will be shown in bold characters.
caps bool If true displays text in capital letters.
characterBorder array Adds a border to the character. Keys and values: 'type' => none, single, double, dashed..., 'color' => ffffff, ff0000, 'spacing'=> 0, 1, 2..., 'width' => in eights of a point.
color string Hexadecimal color value: 'FF0000', '000000'...
columnBreak string Inserts a column break.
Possible values are: before, after or both.
doubleStrikeThrough bool If true displays text in doubleStrikeThrough.
em string Emphasis mark type: 'none', 'dot', 'circle', 'comma', 'underDot'.
emboss bool Emboss style.
font string or array
string type: font family: 'Arial', Calibri'...

array type:
  • ascii
  • hAnsi
  • eastAsia
  • cs
fontSize int Font size in points.
highlightColor string Highlights the run of text.
The available colors are: black, blue, cyan, green, magenta, red, yellow, white, darkBlue, darkCyan, darkGreen, darkMagenta, darkRed, darkYellow, darkGray, lightGray, none.
italic bool If true displays the text in italics.
lang array Lang options: val, eastAsia and bidi keys.
lineBreak string Inserts a line break. Possible values are: before, after or both.
noProof bool Ignore spelling and grammar errors.
outline bool Outline style.
position int Position value. Positive value for raised and negative value for lowered.
rStyle string Character style to be used.
rtl bool Sets to true for right to left languages like Hebrew or Arabic.
scaling int Scaling value, 100 is the default value.
shadow bool Shadow style.
smallCaps bool If true displays text in small capital letters.
spaces int Number of additional leading empty spaces before the current run of text.
spacing int character spacing, positive value for expanded and negative value for condensed.
strikeThrough bool If true displays text in strikethrough.
subscript bool If true displays text in subscript.
superscript bool If true displays text in superscript.
tab bool Inserts a tab.
underline string Underlines text. Possible values are: single, words, double, dotted, dash and wave.
underlineColor string Underlines text with a color: 'FF0000', '000000'...
vanish bool Uses a vanish style.

paragraphOptions

The possible keys and values are:

Key Type Description
pStyle string Paragraph style to be used.
backgroundColor string Hexadecimal color value: FF0000, 000000...
bidi bool Sets to true for right to left languages like Hebrew or Arabic.
bold bool If true the text will be shown in bold characters.
border string Available values are:
  • none (default)
  • double
  • dashed
  • outset
  • inset
  • threeDEmboss
  • threeDEngrave
You can access to the complete list in: Border Styles.
borderBottom string Overwrites the general border type for the bottom border of the paragraph.
borderLeft string Overwrites the general border type for the left border of the paragraph.
borderTop string Overwrites the general border type for the top border of the paragraph.
borderRight string Overwrites the general border type for the right border of the paragraph.
borderColor string Hexadecimal color value: FF0000, 000000...
borderBottomColor string Overwrites the general border color for the bottom border of the paragraph.
borderLeftColor string Overwrites the general border color for the left border of the paragraph.
borderTopColor string Overwrites the general border color for the top border of the paragraph.
borderRightColor string Overwrites the general border color for the right border of the paragraph.
borderSpacing int Separation between border and text in points.
borderBottomSpacing int Overwrites the general border spacing for the bottom border of the paragraph.
borderLeftSpacing int Overwrites the general border spacing for the left border of the paragraph.
borderTopSpacing int Overwrites the general border spacing for the top border of the paragraph.
borderRightSpacing int Overwrites the general border spacing for the right border of the paragraph.
borderWidth int Border width in eigths of a point.
borderBottomWidth int Overwrites the general border width for the bottom border of the paragraph.
borderLeftWidth int Overwrites the general border width for the left border of the paragraph.
borderTopWidth int Overwrites the general border width for the top border of the paragraph.
borderRightWidth int Overwrites the general border width for the right border of the paragraph.
caps bool If true displays text in capital letters.
color string Hexadecimal color value: 'FF0000', '000000'...
contextualSpacing bool If true ignores spacing above and below the paragraph whenever the neighbouring paragraphs use the same Word style (false by default).
doubleStrikeThrough bool If true displays text in doubleStrikeThrough.
em string Emphasis mark type: 'none', 'dot', 'circle', 'comma', 'underDot'.
emboss bool Emboss style.
firstLineIndent int First line indentation in twentieths of a point (twips).
font string Font family: 'Arial', Calibri'...
fontSize int Font size in points.
hanging int Paragraph hanging in twentieths of a point (twips).
headingLevel int The heading level if you want this paragraph to be a heading.
italic bool If true displays the text in italics.
indentLeft int Left margin in points.
indentRight int Right margin in points.
keepLines bool Keeps (whenever possible) all the current paragraph lines on the same page.
keepNext bool Keeps (whenever possible) in the same page the current paragraph with next paragraph.
lineSpacing int 120, 240 (standard), 360, 480... (in twentieths of a point).
noProof bool Ignore spelling and grammar errors.
outline bool Outline style.
pageBreakBefore bool If true forces a page break before the paragraph.
parseLineBreaks bool If true (default is false) parses the line breaks to include them in the Word document.
parseTabs bool If true (default is false) parses the tabs to include them in the Word document as w:tab tags.
position int Position value. Positive value for raised and negative value for lowered.
rtl bool Sets to true for right to left languages like Hebrew or Arabic.
scaling int Scaling value, 100 is the default value.
shadow bool Shadow style.
smallCaps bool If true displays text in small capital letters.
spacingBottom int Bottom padding in twentieths of a point.
spacingTop int Top padding in twentieths of a point.
strikeThrough bool If true displays text in strikethrough.
suppressAutoHyphens bool Suppress hyphenation.
suppressLineNumbers bool Suppress line numbers.
tabPositions array Each entry is an associative array with the following keys and values:
  • 'type' (string) can be clear, left (default), center, right, decimal, bar and num.
  • 'leader' (string) can be none (default), dot, hyphen, underscore, heavy and middleDot.
  • 'position' (int) given in twentieths of a point.
If there is a tab and the tabPositions array is not defined the standard tab position (default of 708) will be used.
textAlign string Text alignment within paragraph. Possible values are: left, center, right, both and distribute.
textDirection string Text flow direction within a table cell. Possible values are: lrTb, tbRl, btLr, lrTbV, tbRlV and tbLrV.
underline string Underlines text. Possible values are: single, words, double, dotted, dash and wave.
underlineColor string Underlines text with a color: 'FF0000', '000000'...
vanish bool Uses a vanish style.
widowControl bool Prevents Word from printing the last line of a paragraph by itself at the top of the page (widow) or the first line of a paragraph at the bottom of a page (orphan).
wordWrap bool Allows line breaking at character level (default value is false).
Code samples

Example #1

x
 
1
require_once 'classes/CreateDocx.php';
2
3
$docx = new CreateDocx();
4
5
$text = 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, ' .
6
'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut ' .
7
'enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut' .
8
'aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit ' .
9
'in voluptate velit esse cillum dolore eu fugiat nulla pariatur. ' .
10
'Excepteur sint occaecat cupidatat non proident, sunt in culpa qui ' .
11
'officia deserunt mollit anim id est laborum.';
12
13
$paragraphOptions = array(
14
    'bold' => true,
15
    'font' => 'Arial'
16
);
17
18
$docx->addText($text, $paragraphOptions);
19
20
$docx->createDocx('output');
21

The resulting Word document looks like:

Example #2

31
 
1
require_once 'classes/CreateDocx.php';
2
3
$docx = new CreateDocx();
4
5
// a paragraph composed of two runs of text with different properties
6
$text = array();
7
$text[] =
8
array(
9
    'text' => 'We know this looks ugly',
10
    'underline' => 'single'
11
);
12
13
$text[] =
14
array(
15
    'text' => ' but we only want to illustrate some of the functionality of the addText method.',
16
    'bold' => true
17
);
18
19
// add some borders to the paragraph to illustrate that functionality
20
$paragraphOptions = array(
21
    'border' => 'double',
22
    'borderColor' => 'b70000',
23
    'borderWidth' => 12,
24
    'borderSpacing' => 8,
25
    'borderTopColor' => '000000',
26
);
27
28
$docx->addText($text, $paragraphOptions);
29
30
$docx->createDocx('output');
31

The resulting Word document looks like:

Example #3

57
 
1
require_once 'classes/CreateDocx.php';
2
3
$docx = new CreateDocx();
4
5
// create a Word fragment with an image
6
$image = new WordFragment($docx);
7
$imageOptions = array(
8
    'src' => '/img/image.png',
9
    'scaling' => 50,
10
    'float' => 'right',
11
    'textWrap' => 1 ,
12
);
13
$image->addImage($imageOptions);
14
15
// create a Word fragment with a link
16
$link = new WordFragment($docx);
17
$linkOptions = array(
18
    'url'=> 'http://www.google.es',
19
    'color' => '0000FF',
20
    'underline' => 'single',
21
);
22
$link->addLink('link to Google', $linkOptions);
23
24
// create a Word fragment with a footnote
25
$footnote = new WordFragment($docx);
26
$footnote->addFootnote(
27
    array(
28
        'textDocument' => 'here it is',
29
        'textFootnote' => 'This is the footnote text.',
30
    )
31
);
32
33
//now we insert the different runs of text with created content and some text
34
$text = array();
35
36
$text[] = $image;
37
$text[] = array(
38
    'text' => 'I am going to write a link: ',
39
    'bold' => true,
40
);
41
$text[] = $link;
42
$text[] =array(
43
    'text' => ' to illustrate how to include links. ',
44
);
45
$text[] = array(
46
    'text' => ' As you may see it is extremely simple to do so and it can be done with any other Word element. For example to include  a footnote is also as simple as this: ',
47
);
48
$text[] = $footnote;
49
$text[] = array(
50
    'text' => ' , as you may check there is a footnote at the bootom of the page. ',
51
    'color' => 'B70000',
52
);
53
54
$docx->addText($text);
55
56
$docx->createDocx('output');
57

The resulting Word document looks like:

Example #4

53
 
1
require_once 'classes/CreateDocx.php';
2
3
$docx = new CreateDocx();
4
5
$docx->addText('Some examples that illustrate how to inclueded tabbed text in your Word document:');
6
7
// first example
8
$tabs = array();
9
$tabs[] = array('position' => 2000);
10
$tabs[] = array('position' => 4000);
11
$tabs[] = array('position' => 6000);
12
13
$options = array('tabPositions' => $tabs);
14
15
$text = array();
16
$text[] = array('text' => 'one');
17
$text[] = array('text' => 'two', 'tab' => true);
18
$text[] = array('text' => 'three', 'tab' => true);
19
20
$docx->addText($text, $options);
21
22
// second example
23
$tabs = array();
24
$tabs[] = array('position' => 1000);
25
$tabs[] = array('position' => 3000);
26
$tabs[] = array('type' => 'center', 'leader' => 'dot', 'position' => 4000);
27
28
$options = array('tabPositions' => $tabs);
29
30
$text = array();
31
$text[] = array('text' => 'one');
32
$text[] = array('text' => 'two', 'tab' => true);
33
$text[] = array('text' => 'three', 'tab' => true);
34
35
$docx->addText($text, $options);
36
37
// third example
38
$tabs = array();
39
$tabs[] = array('position' => 1500);
40
$tabs[] = array('position' => 5000);
41
$tabs[] = array('type' => 'center', 'leader' => 'dot', 'position' => 7000);
42
43
$options = array('tabPositions' => $tabs);
44
45
$text = array();
46
$text[] = array('text' => 'one', 'tab' => true);
47
$text[] = array('text' => 'two', 'tab' => true);
48
$text[] = array('text' => 'three', 'tab' => true);
49
50
$docx->addText($text, $options);
51
52
$docx->createDocx('output');
53

The resulting Word document looks like:

Release notes
  • phpdocx 16.0:
    • suppressAutoHyphens option.
    • supported applying disabled styles (using false as value): keepLines, keepNext and pageBreakBefore.
  • phpdocx 15.0:
    • font option allows using an array to set all font types (ascii, hAnsi, eastAsia, cs).
    • supported applying disabled styles (using false as value): bold, italic, bidi, caps, smallCaps, widowControl and wordWrap.
  • phpdocx 14.5:
    • parseTabs option.
  • phpdocx 12.5:
    • emboss, noProof, outline, shadow and suppressLineNumbers options.
  • phpdocx 12.0:
    • improved working with East Asian fonts.
    • parseLineBreaks option.
  • phpdocx 7.5:
    • doubleStrikeThrough, vanish, scaling, position, underlineColor, spacing and characterBorder styles.
  • phpdocx 7.0:
    • superscript, subscript and strikeThrough styles.
  • phpdocx 5.5:
    • em option.
­
­