Feature #5080 / Best Practice: Dynamic PDF Letter - add to manual.rst

extension/Documentation/Manual.rst

@@ -4482,15 +4482,15 @@ Join mode: strip whitespace
 '''''''''''''''''''''''''''
 
 Ending a line with a '\' forces the removing off all leading and trailing whitespaces in that line and do not insert an
-extra space in between. E.g.: :
+extra space in between. E.g.: ::
 
-    10.sql = SELECT 'hello world', 'd:final.pdf   \
+    10.sql = SELECT 'hello world', 'd:final.pdf \
                                     |p:id=export  \
                                     |t:Download' AS _pdf \
 
 Results to: `10.sql = SELECT 'hello world', 'd:final.pdf|p:id=export|t:Download' AS _pdf`
 
-Note: the `\` does not force the joining, it only removes the whitespaces.
+Note: the '\' does not force the joining, it only removes the whitespaces.
 
 To get the same result, the following is also possible: ::
 
@@ -5021,6 +5021,99 @@ Example `_pdf`, `_zip`: ::
 Use the `--print-media-type` as wkthml option to access the page with media type 'printer'. Depending on the website
 configuration this switches off navigation and background images.
 
+Rendering 'official' look-alike PDF letters
+'''''''''''''''''''''''''''''''''''''''''''
+
+`wkhtmltopdf`, with the header and footer options, can be used to render multi page PDF letters (repeating header,
+pagination) in combination with dynamic content. Such PDFs might look-alike official letters, together with logo and signature.
+
+Best practice:
+
+#. Create a clean (=no menu, no website layout) letter layout in a separated T3 branch: ::
+
+	page = PAGE
+	page.typeNum = 0
+	page.includeCSS {
+	  10 = typo3conf/ext/qfq/Resources/Public/Css/qfq-letter.css
+	}
+
+	// Grant access to any logged in user or specific development IPs
+	[usergroup = *] || [IP = 127.0.0.1,192.168.1.* ]
+	  page.10 < styles.content.get
+	[else]
+	  page.10 = TEXT
+	  page.10.value = access forbidden
+	[global]
+
+#. Create a T3 `body` page (e.g. page alias: 'letterbody') with some content. Example static HTML content: ::
+
+	<div class="letter-receiver">
+	  <p>Address</p>
+	</div>
+	<div class="letter-sender">
+	 <p><b>firstName name</b><br>
+	  Phone +00 00 000 00 00<br>
+	  Fax +00 00 000 00 00<br>
+	 </p>
+	</div>
+
+	<div class="letter-date">
+	  Zurich, 01.12.2017
+	</div>
+
+	<div class="letter-body">
+	 <h1>Subject</h1>
+
+	 <p>Dear Mrs...</p>
+	 <p>Lucas ipsum dolor sit amet organa solo skywalker darth c-3p0 anakin jabba mara greedo skywalker.</p>
+
+	 <div class="letter-no-break">
+	 <p>Regards</p>
+	 <p>Company</p>
+	 <img class="letter-signature" src="">
+	 <p>Firstname Name<br>Function</p>
+	 </div>
+	</div>
+
+#. Create a T3 letter-`header` page (e.g. page alias: 'letterheader') , with only the header information: ::
+
+		<header>
+		<img src="fileadmin/logo.png" class="letter-logo">
+
+		<div class="letter-unit">
+		  <p class="letter-title">Department</p>
+		  <p>
+			 Company name<br>
+			 Company department<br>
+			 Street<br>
+			 City
+		  </p>
+		</div>
+		</header>
+
+#. Create a) a link (Report) to the PDF letter or b) attach the PDF (on the fly rendered) to a mail. Both will call the
+   `wkhtml` via the `download` mode and forwards the necessary parameter.
+
+Report: ::
+
+  sql = SELECT CONCAT('d:Letter.pdf|t:',p.firstName, ' ', p.name,
+                       '|p:id=letterbody&pId=', p.id, '&_sip=1&--margin-top=50mm&--margin-bottom=20mm&',
+                               '--header-html={{BASE_URL_PRINT:Y}}?id=letterheader&',
+                               '--footer-right="Seite: [page]/[toPage]"&',
+                               '--footer-font-size=8&--footer-spacing=10') AS _pdf
+                FROM Person AS p ORDER BY p.id
+
+
+Sendmail. Parameter: ::
+
+	sendMailAttachment={{SELECT 'd:Letter.pdf|t:', p.firstName, ' ', p.name, '|p:id=letterbody&pId=', p.id, '&_sip=1&--margin-top=50mm&--margin-bottom=20mm&--header-html={{BASE_URL_PRINT:Y}}?id=letterheader&--footer-right="Seite: [page]/[toPage]"&--footer-font-size=8&--footer-spacing=10' FROM Person AS p WHERE p.id={{id:S}}
+
+Replace the static content elements from 2. and 3. by QFQ Content elements as needed: ::
+
+  10.sql = SELECT '<div class="letter-receiver"><p>', p.name AS '_+br', p.street AS '_+br', p.city AS '_+br', '</p>'
+            FROM Person AS p WHERE p.id={{pId:S}}
+
+
 Export area
 '''''''''''
 
@@ -5283,10 +5376,12 @@ Easily create Email links.
 Column: _sendmail
 ^^^^^^^^^^^^^^^^^
 
-t:<TO:email[,email]>|F:<FROM:email>|s:<subject>|b:<body>
- [|c:<CC:email[,email]]>[|B:<BCC:email[,email]]>[|F:<REPLY-TO:email>]
- [|a:<flag autosubmit: on /off>][|g:<grid>][|x:<xId>][|y:<xId2>][|z:<xId3>]
- [|C][d:<filename of the attachment>][|F:<file to attach>][|u:<url>][|p:<T3 uri>]
+::
+
+	t:<TO:email[,email]>|F:<FROM:email>|s:<subject>|b:<body>
+	 [|c:<CC:email[,email]]>[|B:<BCC:email[,email]]>[|F:<REPLY-TO:email>]
+	 [|a:<flag autosubmit: on /off>][|g:<grid>][|x:<xId>][|y:<xId2>][|z:<xId3>]
+	 [|C][d:<filename of the attachment>][|F:<file to attach>][|u:<url>][|p:<T3 uri>]
 
 Send text emails. Every mail will be logged in the table `mailLog`. Attachments are supported.
 

less/qfq-letter.css.less

-// Letter
+// PDF Letter classes
 
 body {
   font-family: Arial, sans-serif;