The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
PDF-Collage-0.002
River stage zero No dependents
/ PDF::Collage::Template

NAME

PDF::Collage::Template - A single template for PDF::Collage

SYNOPSIS

   use PDF::Collage::Template;
   my $pc = PDF::Collage::Template->new(%args);
   my $pdf = $pc->render(\%data);
   $pdf->saveas('/path/to/file.pdf');

DESCRIPTION

This module implements a class that allows loading a template (as a sequence of commands for basic PDF manipulation) and then "render" this template over and over, based on different data for filling in the form.

The input format requires the presence of key commands, associated to an array reference of "commands".

Each such command is a hash reference, containing at least a key op which tells which kind of command should be executed. The command kinds are described in the following sub-sections.

All commands are applied in sequence during a call to "render".

add-image

   {
      op => 'add-image',
      page => 1,
      path => '/path/to/image.png',
      x => 10,
      y => 30,
      width => 10,
      height => 10,
   }

Add an image. See PDF::Build for the supported formats.

add-page

   { op => 'add-page' }

Add an empty page at the end.

   { op => 'add-page', page => 1 }

Add an empty page as page number 1.

   {
      op => 'add-page',
      page => 2,
      'from-path' => '/some/file.pdf',
      'from-page' => 3
   }

Get page 3 from file /some/file.pdf and add it as page 2 in the PDF that is built.

Key from-path can also be abbreviated as from.

add-text

   {
      op => 'add-text',
      page => 1,
      font => 'DejaVuSans.ttf',
      'font-size' => 12,
      text => 'whatever',
      align => 'start', # also 'middle' or 'end'
      x => 10,
      y => 20,
   }

Place a text label on the PDF.

The font key can be replaced with font-family.

There are three ways of defining the text:

text

This text is taken verbatim and has precedence over other alternatives;

text-template

This text is expanded using Template::Perlish with the data passed to "render". It takes precedence over "text-variable".

text-variable

This is meant to be a variable that is expanded using Template::Perlish on the data provided.

The align is optional and defaults to start, which for western fonts means that the X coordinate marks the starting position of the first character of the string, which is then rendered to the right of that coordinate. Alternative values are middle and end, which do what they imply regarding horizontal alighment of the rendered string.

log

   {
      op => 'log',
      level => 'info',
      message => 'whatever!',
   }

Print a log message. If Log::Any is available, it will use it; otherwise, warn is used.

set-defaults

   {
      op => 'set-default',
      font => 'DejaVuSans.ttf',
      'font-size' => 12,
   }

Set some defaults that will be used in following commands. This allows e.g. to set the same font once and for all for all "add-text" commands, or the font size.

INTERFACE

This module has an object-oriented interface.

Constructor

new

   my $pct = PDF::Collage::Template->new(%args);
   my $pct = PDF::Collage::Template->new(\%args);

Build a new object. The input arguments can be key-value pairs or a has reference, supporting the same keys as the accessors "commands", "functions", and "metadata".

Returns a PDF::Collage::Template object.

Accesssors

commands

   my $array_ref = $obj->commands;

An array reference containing the list of commands to apply for generating a new PDF during "render".

functions

   my $hash_ref = $obj->functions;

A hash reference with functions that will be injected into the Template::Perlish namespace when expanding all templates during the call to "render".

metadata

   my $hash_ref = $obj->metadata;

Additional metadata, represented by a hash reference. Not used by the module, but kept for ease of manipulation.

Methods

render

   my $pdf = $obj->render(\%data);

Use the provided hash reference to expand all applicable Template::Perlish templates and then use them while applying "commands" to generate the PDF.

Returns a PDF::Builder object.

AUTHOR

Flavio Poletti <flavio@polettix.it>

COPYRIGHT AND LICENSE

Copyright 2023 by Flavio Poletti <flavio@polettix.it>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.