Practical phppptx

Working with templates

Introduction

Making a presentation from scratch can get complicated when, for example, you aim for a very elaborated design of the file or if you want to customize its content.

To simplify the presentation creation process, phppptx allows to use templates. In phppptx a template is a PPTX file, which contains one or multiple variables to be replaced.

To work with templates you have to use the class CreatePptxFromTemplate, which provides all necessary methods to modify presentations.

Template methods replace variables (template placeholders) in slides (default), notesSlides, slideLayouts and slideMasters targets.

Setting up the template

By default, phppptx uses the symbol '$' to wrap the variables to be replaced. Therefore, to define a variable with the name SIGN, add it to the presentation by writing $SIGN$.

If you prefer to work with another symbol, call the method setTemplateSymbol. For example, to use '#' as symbol for templates, apply the code:

$pptx->setTemplateSymbol('#');

Instead of using just one symbol, '${ }' and other symbols can also be used to wrap placeholders:

$pptx->setTemplateSymbol('${', '}');

Loading the template

Create a new object using the class CreatePptxFromTemplate:

require_once 'classes/CreatePptx.php';

$pptx = new CreatePptxFromTemplate('template.pptx');

Now, replace the contents of this $pptx object.

Texts

The easiest element for replacing a placeholder is a string. replaceVariableText is the method to be used:

public function replaceVariableText($variables, $options = array())

The available parameters are:

$variables: placeholders to be replaced
$options: it's an array which can have these keys:
- 'activeSlide' (bool): if true, get only the active slide. Default as false.
- 'target' (string): slides (default), notesSlides, slideLayouts, slideMasters.

E.g., to replace VAR_1 and VAR_2 placeholders with new texts:

$variables = array('VAR_1' => 'New value 1', 'VAR_2' => 'New value 2');

$pptx->replaceVariableText($variables);

Images

Images can be set to be replaced adding a placeholder in the alternate text option. In order to do this, just right click on it, open the image properties and search for the field alternate text (this name may vary in each version of MS PowerPoint). Type in this field the name of the placeholder, for example: $IMAGE$.

To replace an image, use the replaceVariableImage method:

public function replaceVariableImage($variables, $options = array())

The available parameters are:

$variables: placeholders to be replaced
$options: it's an array which can have these keys:
- 'activeSlide' (bool): if true, get only the active slide. Default as false.
- 'mime' (string): forces a mime (image/jpg, image/jpeg, image/png, image/gif, image/webp).
- 'target' (string): slides (default), slideLayouts, slideMasters.

E.g., to replace the image with placeholder $IMAGE_1$:

$pptx->replaceVariableImage(array('IMAGE_1' => 'image.png'));

Audios

Just like with images, audio files can be replaced with new contents by defining a placeholder in the field alternate text when doing right click on it. The replaceVariableAudio method allows to replace audios:

public function replaceVariableAudio($variables, $options = array())

The available parameters are:

$variables: placeholders to be replaced
$options: it's an array which can have these keys:
- 'activeSlide' (bool): if true, get only the active slide. Default as false.
- 'image' (string): use a custom image as audio image.
- 'mime' (string): forces a mime (audio/mpeg, audio/x-wav, audio/x-ms-wma, audio/unknown).
- 'target' (string): slides (default), slideLayouts, slideMasters.

E.g., this replaces the AUDIO_1 placeholder with a new audio:

$variables = array('AUDIO_1' => 'audio.mp3');

$pptx->replaceVariableAudio($variables);

Videos

Video placeholders work in the same way as audios. A placeholder must be added in the field alternate text. The replaceVariableVideo method allows to replace videos:

public function replaceVariableVideo($variables, $options = array())

The available parameters are:

$variables: placeholders to be replaced
$options: it's an array which can have these keys:
- 'activeSlide' (bool): if true, get only the active slide. Default as false.
- 'image' (string): use a custom image as video image.
- 'mime' (string): forces a mime (video/mp4, video/x-msvideo, video/x-ms-wmv, video/unknown).
- 'target' (string): slides (default), slideLayouts, slideMasters.

E.g., this replaces the VAR_1 placeholder with a new video:

$variables = array('VIDEO_1' => 'video.mkv');

$pptx->replaceVariableVideo($variables);

Lists

Replacing lists is as simple as adding a list with a single element in the template which contains the placeholder. When adding the new values, lists elements remain intact.

To add values to a list, use the replaceVariableList method:

public function replaceVariableList($variable, $listValues, $options = array())

The available parameters are:

$variable: list placeholder
$listValues: array with the values to add
$options: it's an array which can have these keys:
- 'activeSlide' (bool): if true, get only the active slide. Default as false.
- 'target' (string): slides (default), slideLayouts, slideMasters.

E.g., replace VAR_LIST:

$items = array('First item', 'Second item', array('Subitem A', 'Subitem B', 'Subitem C', array('Subitem C.1', 'Subitem C.2'), 'Subitem D'), 'Third item');

$pptx->replaceVariableList('VAR_LIST', $items);

Tables

Just like with the lists, tables can be added to the template by making a table with the chosen styles and defining a row with the variables to replace. This row will be replaced with as many rows as needed with new values, keeping the original table styles.

To add values to a table, use the replaceVariableTable method:

public function replaceVariableTable($variables, $options = array())

The available parameters are:

$variables: multidimensional array with the table placeholders and its values. For each position of the array, a new row is created in the table.
$options: it's an array which can have these keys:
- 'activeSlide' (bool): if true, get only the active slide. Default as false.
- 'target' (string): slides (default), slideLayouts, slideMasters.

E.g., this replaces a table with placeholders:

$items = array(
    array(
        'ITEM' => 'Product A',
        'REFERENCE' => '107AW3',
        'DETAILS' => 'Details A',
    ),
    array(
        'ITEM' => 'Product B',
        'REFERENCE' => '204RS67O',
        'DETAILS' => 'Details B',
    ),
    array(
        'ITEM' => 'Product C',
        'REFERENCE' => '25GTR56',
        'DETAILS' => 'Details C',
    )
);

$pptx->replaceVariableTable($items);

Adding new contents

The CreatePptxFromTemplate class inherits CreatePptx, so all methods available in this class can be used to add new contents, change settings and other tasks when using PPTX templates.

This is the code sample to add a text in a new text box:

$pptx = new CreatePptxFromTemplate('template.pptx');

$position = array(
    'coordinateX' => 770000,
    'coordinateY' => 507000,
    'sizeX' => 7000000,
    'sizeY' => 450000,
    'textBoxStyles' => array(
        'border' => array(
            'color' => 'FF0000',
            'dash' => 'dash',
            'width' => 48575,
        ),
    ),
);
$content = array(
    'text' => 'New content',
);
$pptx->addText($content, array('new' => $position));

$pptx->savePptx('output');

Removing placeholders

Sometimes there's no need to replace every text placeholder, and some of them remain unused in the template. To delete placeholders, call removeVariableText:

public function removeVariableText($variables, $options = array())

The available options are:

$variables: array of placeholders to remove
$options: it's an array which can have these keys:
- 'activeSlide' (bool): if true, get only the active slide. Default as false.
- 'target' (string): slides (default).

E.g., to delete the placeholders HEADER_TITLE and HEADER_CUSTOM in the headers target:

$pptx->removeVariableText(array('VAR_TITLE'));

Other methods are available to remove audio placeholders (removeVariableAudio), image placeholders (removeVariableImage) and video placeholders (removeVariableVideo).

The removeShapeSlide method allows to delete preset placeholder positions from the layout. This is a useful feature for deleting the placeholders defined in the layouts so they are not displayed in the presentation when they are not required to appear.

Tips and Tricks

How to retrieve variables with getTemplateVariables: this method informs at any time which placeholders haven't been replaced. getTemplateVariables sends back an array with the variables by target.

Working with prefixes allows to carry an extensive control of every placeholder, divided by groups of work, and even permits to classify them by substitution priority. This makes easier its further replacement and deletion.

Contents with multiple styles and advanced contents can be added using PptxFragments with the following methods: replaceVariablePptxFragment, replaceVariableList, and replaceVariableTable

Next - Images, audios and videos