The cursor method of Docxpresso offers you complete control over the position of the document cursor so you may include content anywhere in your template.
When you use a custom template with Docxpresso by default the cursor is always located at the end of the document. This implies that unless you “move the cursor” with the help of the cursor method all of the content you insert will show up at the end of the document.
Although the default option may serve you well the majority of times you may often need to insert content elsewhere in you document and that is where the cursor method comes to your rescue.
You may locate the cursor before or after any paragraph or table in your template with the help of the various method options that we pass to describe.
The public API of the cursor method can be summarized as follows:
public cursor ([$options])
- $options (type: array).
This array has the following available keys and values:
- needle (type: string). If not empty, the (first, if match is not set) node containing it will be chosen as the reference node.
- element (type: string, default: paragraph). It sets the type of the reference node. It can be paragraph or table.
- match (type: integer, default: 1). If there is more than one node matching the conditions this parameter selects the node given by its order of ocurrence.
- position (type: string, default: before). It can be before (the cursor is located before the reference node), after (the cursor is located just after the reference node) or end (end of the document).
In order to illustrate the functionality we will now run an examples of the cursor method with the help of a simple template that includes three paragraphs and a table.
<?php /** * This sample script sets the cursor at different points * of the document and inserts some simple content */ require_once 'pathToDOCXPRESSO/CreateDocument.inc'; $doc = new DocxpressocreateDocument(array('template' => 'template_cursor_sample.odt')); $format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf //include a simple paragraph at the end of the document $doc->paragraph() ->text(array('text' => 'A paragraph at the very end of the document.')); //with all default options the cursor is located before the first paragraph $doc->cursor(); $doc->paragraph() ->text(array('text' => 'The first text included before the first paragraph (we use all default options).')); //locate the cursor after the paragraph containing the word 'Second' $doc->cursor(array ('needle' => 'Second', 'position' => 'after')); $doc->paragraph() ->text(array('text' => 'Now we include this text just after the paragraph containing the word "Second".')); //locate the cursor before the first table $doc->cursor(array ('element' => 'table')); $doc->paragraph() ->text(array('text' => 'Now some text before the first table.')); //locate the cursor within a table cell $doc->cursor(array ('needle' => 'Cell 1 2')); $doc->paragraph() ->text(array('text' => 'This goes at the beginning of the first row second col cell.')); //and back to the end of the document $doc->cursor(array ('position' => 'end')); $doc->paragraph() ->text(array('text' => 'The end.')); //include in the render method the path where you want your document to be saved $doc->render('cursor_sample' . $format); //echo a link to the generated document echo 'You may download the generated document from the link below:<br/>'; echo '<a href="' . 'cursor_sample' . $format . '">Download document</a>';
It is important to point out that after setting the cursor anywhere in the document one is only allowed to insert “document level elements” like paragraphs, headings, tables, etcetera and not directly “subelements” like table rows or table cell or plain text. If you need to do so you should use the replace and clone methods.