PDF Letter Page Setup

[Marty]

I've added code to the PDF letter creation form to allow page setup configuration, and I would like to contribute it for inclusion in the CiviCRM code base. Page setup includes fields to select the page size (letter, legal, etc), orientation (portrait, landscape), and margins (top, bottom, left, right).  I've attached a screen shot of the new fields as implemented.

Ideally, it would be nice to save the page setup when saving PDF letter templates so that loading the template would automatically load the corresponding page setttings.  This has not been implemented, and I'm looking for feedback on how important it is and how to save the settings in the database (new table?).  Currently, the PDF letter creation form loads with default settings that were previously hardcoded (letter, portrait, 0.75 inch margins).

I think the new capability is beneficial even without being able to save the settings, so I can submit the code if this is of interest to people.

[xavier]

Neat,

It would be useful to store in the template (don't know the code, no idea if it's easy or not). Have you looked at that already ?

As for the default values, you can store them in the option table (you define an option group, then store the key values). I think the option lists are a standard admin interface that you can easily reuse.

X+

[Donald Lobo]

1. i think having configurable defaults (and storing them in an "option group") would be a good thing

2. i think allowing this to be modified at runtime whenever we generate a PDF would be awesome. I was playing with those settings when doing some PDF generation yesterday

lobo

[Marty]

The allowable values for page size and orientation are defined by the dompdf package, but I can certainly add them to the option_group and option_value tables and then pull from there when populating the selection lists.  The only thing I'll need help with is info about how to add the new table entries to database during the install/upgrade process.  When looking at the SVN repository, it wasn't clear to me which files are involved, and I couldn't find any info about the process for adding new database entries in the forums.

I do think that allowing the page settings to be saved along with the PDF template is an important capability.  For example, if an admin creates a template to print envelopes, we don't want the user to have to remember and reconfigure the page settings each time they go to print the envelopes. Simply loading the template would load the corresponding page settings as well.

To accomplish this, I think I need to create a new db table with rows containg the page settings and indexed by template ID.  The page settings would be saved when the template is saved on the PDF letter creation page.  When the template is deleted then the corresponding page settings row would be deleted as well, although I'm not knowledgable about foreign keys and whether or not that happens autommatically.

[xavier]

The allowable values for page size and orientation are defined by the dompdf package, but I can certainly add them to the option_group and option_value tables and then pull from there when populating the selection lists.  The only thing I'll need help with is info about how to add the new table entries to database during the install/upgrade process.  When looking at the SVN repository, it wasn't clear to me which files are involved, and I couldn't find any info about the process for adding new database entries in the forums.

You define it at two places:
xml/templates/civicrm_data.tpl  (for an install)

and in CRM/Upgrade/Incremental/sql/3.2.x

Find an example with civicrm_option_group and civicrm_option_value and do the same

you'll need to run GenCode.php see if the sql generated looks ok, and run upgrade (to test the upgrade).

I do think that allowing the page settings to be saved along with the PDF template is an important capability.  For example, if an admin creates a template to print envelopes, we don't want the user to have to remember and reconfigure the page settings each time they go to print the envelopes. Simply loading the template would load the corresponding page settings as well.

To accomplish this, I think I need to create a new db table with rows containg the page settings and indexed by template ID.  The page settings would be saved when the template is saved on the PDF letter creation page.  When the template is deleted then the corresponding page settings row would be deleted as well, although I'm not knowledgable about foreign keys and whether or not that happens autommatically.

Don't know if it wouldn't be better to store it where the pdf tempate is stored. Have you looked at the code and do you know ?

X+

[Marty]

Templates are stored in the civicrm_msg_templates table.  I could add the new page setting fields to this table if that's acceptable.  Since templates can be used for either email or PDF letters, the page setting fields would only apply when used for PDF letters.  I think it does make sense to store the settings along with the template.  Is there someone who could approve this?  If so, I'll go ahead and develop the code.

I see that I can add the new fields to the civicrm_msg_table by editing the file xml/schema/Core/MessageTemplates.xml.  Is this file used to build the database during an install?  I assume I use the ALTER TABLE directive to add the new columns in CRM/Upgrade/Incremental/sql/3.2.x.mysql.tpl for an upgrade.

Thanks for your help!

[Donald Lobo]

do we want to restrict PDF settings to templates only? Also wont most templates share a small set of PDF settings?

How about this approach for now:

1. store the set of PDF settings in some table (maybe in the option group table in a serialized manner?). with this we'll also have one default PDF setting

2. in message templates add a column to point to which PDF setting to use. if unset, the default PDF setting is used

3. if we need to use a PDF setting in other places, we can refer to the set in 1 and/or embed a column in the relevant table

seems to me a bit more scalable

lobo

[SarahG (FountainTribe)]

Marty - This enhancement to PDFs looks fantastic. Thanks for developing this.  Can you share the code you have so far?

[Dave Greenberg]

I agree with Lobo that having a default PDF Format setting, and being able to share settings between templates makes sense. In order to prevent adding more complexity to the PDF letter creation UI, I would suggest keeping the add / edit format UI in the Admin interface (under Configure menu).

So we deliver a default PDF "Letter Orientation" format (using the existing hard-coded values). Then admins can define additional settings. Would be nice to store these as option_value table rows in a new option_group. However not sure where to put the serialized properties (value column makes sense - it's currently varchar 64 so might need to increase size).

When creating a PDF letter, user has a message template dropdown (if any exist) and a Format dropdown. If they pick a message template which is already linked to a "format" (option_value row) - it gets selected in the dropdown. Else the default format is selected. They can over-ride the pre-selected format if needed (with another defined format). If they select "Update Message Template" checkbox - the linkage between template and format is updated.

Hopefully the various formats can be labeled in a way that's useful / clear for user to select. If folk think it's important - the actual format values (margins etc.) could be displayed (read-only) next to the dropdown as a value is selected (or "browsed" in the dropdown).

[SarahG (FountainTribe)]

Why should the margin values be read only?  It would improve the usability if the end-user could experiment with the margin settings without leaving the screen.  Perhaps a small link that opens a dialog/area for people that want to change the margins, then they can continue their letter.

[xavier]

Why should the margin values be read only? 

Because that's how content is on a select ?

I don't know if you've seen the need, but the default pdf class might be too simple on some cases, eg. if you want to put a logo and this and that. What we did for the namebadge is that you can override the pdf generator.

Beside the paper format and margins, being able to set a class eg "MyCustomLetter" (if empty, calls the default class CRM_Contact_Form_Task_PDFLetterCommon, if not, load the file CRM/Contact/Form/Task/PDF/MyCustomLetter.php and instanciate CRM_Contact_Form_Task_PDF_MyCustomLetter

X+

[Dave Greenberg]

Why should the margin values be read only?  It would improve the usability if the end-user could experiment with the margin settings without leaving the screen.  Perhaps a small link that opens a dialog/area for people that want to change the margins, then they can continue their letter.

I was thinking it would be a bit simpler if the UI for managing the settings was NOT part of the letter writing workflow. If you allow the user to modify / experiment with the settings on the PDF letter form - then you would also need to provide UI for them to save those settings - either updating the existing "format" OR creating a new one. Adding this one top of the Update / Create New version of the message template UI seems like putting a lot of stuff on that form.

That said, if folks whose clients use this a lot think it's necessary to give the end-user that level of flexibility - then we just need to make sure it's done in such a way that it doesn't add complexity to the standard workflow.

[Donald Lobo]

i think its marty's call on how much time he/she wants to invest in the workflow. Obvioulsy allowing inline ajax editing of the PDF format settings will take more time but also a lot more user friendly.

i think the overall point is we need a shared set of "PDF settings" that multiple message templates can use and having a default PDF setting

lobo

[Eileen]

Hi,

Just want to flag that if you set up an admin settings form for pdf settings you  might want to include mailing label settings as well. I note a few people have had to modify the defaults & there have been a few patches over-time on mailing label settings & it would make more sense maintained in the DB than code (not a big prioritity but it may make sense to do it at the same time)

[Marty]

Hi Eileen,

What specific label settings would you like to make configurable?  I'm in the process of coding a PDF Settings admin form that contains a section for PDF Page Formats, and I can add another section for PDF Label Settings if you would like.  Let me know and I'll post a screen image of the form for review.

Marty