Paragraphs

Paragraphs are arguably the most important component of any document. Docxpresso pays special attention to this core element and offers its users powerful tools that allows them to gain full control of their content and styling.

Paragraphs may contain, among others the following structural elements:

• formatted text,
• links and bookmarks,
• tabs,
• line breaks,
• inline or floating images,
• footnotes and endnotes,
• fields,
• and math equations.

It is, of course, outside the scope of this section to discuss in details all these possibilities that are carefully described elsewhere in the documentation, but we believe it is worth to start by pointing out the breadth of capabilities of Docxpresso to this regard.

The paragraph method of Docxpresso is the one responsible to offer us a wrapping element for all the above content and functionality.

Its public API is fairly simple:

The relevant CSS style type styles that one may apply to a paragraph include (where ‘*’ in this context stands for top, right, bottom or left):

• Background:
  • background: shorthand for background properties.
  • background-color: sets the background color.
  • background-image: sets the background image.
  • background-position: sets the position of the background image.
  • background-repeat: specifies if the background image will repeat or not.
• Borders:
  • border: shorthand for border properties.
  • border-color: sets the border color.
  • border-style: sets the border line style.
  • border-width: sets the border width.
  • border-*-color: sets only the border color of one side.
  • border-*-style: sets only the border line style of one side.
  • border-*-width: sets only the border width of one side.
• Alignment:
  • text-align: specifies the horizontal alignment of text.
  • vertical-align: specifies the vertical alignment of text.
• Structural:
  • line-height: specifies the paragraph line height.
  • page-break-before: specifies if a page break should occur before the paragrah.
  • page-break-after: specifies if a page break should occur after the paragrah.
  • page-break-inside: specifies if a page break is allowed within the paragraph.
  • orphans: specifies if orphan lines are allowed within the paragraph.
  • widows: specifies if widow lines are allowed within the paragraph.
• Margins, paddings and indents:
  • margin: specifies all margin widths in one shot.
  • margin-*: specifies one margin at a time.
  • padding: specifies all padding widths in one shot.
  • padding-*: specifies one padding at a time.
  • text-indent: specifies the indentation of the first line.
• Other:
  • direction or writing-mode: sets the text direction.

If you wish to control other propeties like width, height or float you need to wrap the paragraph within, for example, a textbox (see Textboxes for further details).

Besides this paragraph properties one may also set paragraph wide text properties that may be later overridden or not by the specific elements that we will insert within our paragraph. Although they are also described in the API of the text method we include them here for your convenience:

• Background:
  • background-color: sets the text background color.
• Font:
  • font: shorthand for font properties.
  • font-family: sets the font to be used.
  • font-size: sets the font size.
  • font-style: sets the font style.
  • font-variant: sets the font variant.
  • font-weight: specifies how thick the characters should be displayed.
  • font-kerning: specifies the kerning information.
  • letter-spacing: increases or decreases the separation among characters in the text.
  • color: sets the font color.
• Other:
  • hyphens: specifies if hyphens are or are not used.
  • text-decoration: specifies the decoration added to the text.
  • text-decoration-color: sets the color of the text decoration.
  • text-decoration-line: specifices the line type used for the text decoration.
  • text-decoration-style: specifies how the text decoration line will be displayed.
  • text-shadow: applies a shadow to the text.
  • text-transform: specifies the capitalization of text.

Well, enough for the theory let us now dirty a little bit our hands (or keyboards).

Let us start by inserting a simple paragraph with just plain text and a few formatting options:

<?php
/**
 * This sample script inserts a simple paragraph
 */
require_once 'pathToDOCXRESSO/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph
$style = 'text-indent: 1cm; font-family: Arial; color: #444444';
$text = 'This is a ver simple paragraph in Arial font and color #444444 with text indent of 1cm. ';
$text .= 'If we build the paragraph in this way all the text has to share the same styling properties.';
$doc->paragraph(array('text' => $text, 'style' => $style));
$doc->render('simple_paragraph' . $format);   
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'simple_paragraph' . $format . '">Download document</a>'; 

DOWNLOAD:

So far so good but how should we procced if we wish to build more sophisticated paragraphs?

Although is not our to intention to predate the contents of other sections of the documentation let us insert the same paragraph as before but using a different style for the second sentence in the paragraph:

<?php
/**
 * This sample script inserts a paragraph with some extra formatting in a run of text
 */
require_once 'pathToDOCXRESSO/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a paragraph
$style = 'text-indent: 1cm; font-family: Arial; color: #444444';
$text = 'This is a ver simple paragraph in Arial font and color #444444 with text indent of 1cm. ';
$text2 = 'If we build the paragraph in this way NOT all the text has to share the same styling properties.';
$doc->paragraph(array('text' => $text, 'style' => $style))
        ->text(array('text' => $text2, 'style' => 'font-style: italic; text-decoration: underline'));
$doc->render('simple_paragraph_2' . $format);   
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'simple_paragraph_2' . $format . '">Download document</a>'; 

DOWNLOAD:

Notice how the styles cascade from the paragraph to the different runs of text greatly simplifying the construction of sophisticated paragraphs.

One could have obtained the same result with this somehow more elegant code of which we only include the relevant chunk:

$pStyle = 'text-indent: 1cm; font-family: Arial; color: #444444';
$tStyle = 'font-style: italic; text-decoration: underline';
$text = 'This is a ver simple paragraph in Arial font and color #444444 with text indent of 1cm. ';
$text2 = 'If we build the paragraph in this way NOT all the text has to share the same styling properties.';
$doc->paragraph()->style($pStyle)
        ->text(array('text' => $text))
        ->text(array('text' => $text2))->style($tStyle);  

Let us finish this section by building a more sophisticated example although we will defer the detail explanation of each element of the code to their respective section in the documentation:

<?php
/**
 * This sample script inserts a more complex paragraph
 */
require_once 'pathToDOCXRESSO/CreateDocument.inc';
$doc = new DocxpressoCreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a complex paragraph
$doc->paragraph()->style('text-indent: 1cm; font-family: Arial; font-size: 11pt;')
        ->text(array('text' => 'Let us build a paragraph with a few different elements. '))
        ->image(array('src' => 'Docxpresso.png'))->style('float: right; margin: 0 0 10pt 10pt')
        ->text(array('text' => 'We include an image drawn by our website illustrator '))
        ->text(array('text' => 'Pablo Matera '))->style('font-weight: bold; color: #b70000')
        ->text(array('text' => 'as well as a '))
        ->link(array('text' => 'clickable link', 'url' => 'http://Docxpresso.com'))->end('link')
        ->text(array('text' => ' to our website.'));
$doc->render('paragraph' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'paragraph' . $format . '">Download document</a>'; 

DOWNLOAD:

The rendering of floating images in RTF is quite poor when using Libre Office as conversion engine. You may obtain better results with Open Office if RTF is your target document format.

Advanced topic: MS Word “Box model”

If your document target format is Word (.doc, .docx) you may need to take into account the following considerations.

The way that recent versions of Word handle margin and padding for paragraphs should be taken into account when determining the CSS like padding and margin styles properties of Docxpresso.

Recent versions of MS Word will add the left and right padding to the dimensions of the paragraph “invading” the margins of the document page if necessary, i.e. when the paragraph left and/or right margins are smaller than the corresponding paddings.

This behaviour is different that the one used for ODF and PDF documents so it should be taken into account when the target document formats rae .doc or .docx.

If you set the option ‘legacy’ to true in the render method you may safely ignore this issue although different problems may pop up.