Příručka M4 PDF rozšíření

Úvod

Modul M4 PDF rozšíření umožňuje nahradit vestavěné generování PDF dokumentů a přidává nové možnosti vytváření dokumentů v administraci prostřednictvím uživatelských šablon. Vše s plnou podporou UTF-8 kódování a s možností použít nelatinská písma.

Vlastnosti

  • vytváření neomezeného počtu PDF výstupů pomocí Smarty šablon
  • PDF dokumenty pro jeden záznam nebo více vybraných záznamů
  • rozšířený výběr produktů z více kategorií
  • volitelné náhrada vestavěných PDF dokumentů
  • pomocí šablon lze vytvářet stránkové dokumenty i seznamy
  • změna vzhledu dokumentů pomocí CSS stylu šablony
  • v dokumentech mohou být obrázky, rejstříky, hlavičky, patičky, vodoznaky, čárové kódy
  • podpora pro výstup uživatelsky přidaných polí do databáze
  • plná podpora UTF-8
  • podpora nelatinských fontů
  • multijazyková podpora uživatelských textů v šablonách
  • vzorové šablony pro snazší návrh
  • pro ladění šablon je k dispozici šablona zobrazující předávaná data
  • modul nevyžaduje zásah do jádra PrestaShopu™

Jak modul funguje

Modul pracuje ve dvou módech. Oba módy se liší pouze způsobem vyvolání. Používají stejné zdroje dat a mohou používat stejné šablony. V prvním módu je možné PDF dokumenty vytvářet v administraci modulu.

Ve druhém módu se PDF dokument vytvoří jako náhrada v jednom z 8 případů vytváření PDF dokumentů v PrestaShopu™. Tyto možnosti je možné jednotlivě zapnout v konfiguraci modulu.

Způsob aktivace a vytváření PDF dokumentů ukazuje následující schéma. Prvním krokem je získání nebo výběr požadovaných dat. Data se načtou do zvolené Smarty šablony. Šablona data zpracuje a ve formě HTML stránky je předá knihovně mPDF, která vytvoří PDF dokument.

Další informace o použitých knihovnách:
Smarty - http://www.smarty.net/docs.php
mPDF - http://mpdf1.com/manual/

Zdroje dat

Zdrojů dat je k dispozici 5. Odpovídají přesně volbám v konfiguraci modulu. S těmito daty dokáže modul pracovat a vytvářet z nich výstupy:

  • Katalog
  • Zákazníci
  • Objednávky
  • Objednávky s položkami
  • Dobropisy s položkami

Všechny zdroje dat poskytují seznam záznamů. Objednávky s položkami a dobropisy s položkami navíc poskytují související položky. Toho lze využít pro vytváření faktur, dodacích listů a dobropisů.

Šablony

Šablony jsou Smarty šablony. Musí se jednat o plnohodnotný HTML dokument se značkami <head> a <body>. Šablony jsou umístěny v podadresáři /tpl modulu (/modules/m4pdf/tpl). Součástí modulu jsou Ladící šablona a Testovací šablona, vhodné pro první seznámení s možnostmi šablon.

Šablona může obsahovat 4 základní části. Jednotlivé části jsou zvýrazněny na ukázce jednoduché šablony.

A. Označení šablon

Pro identifikaci šablony a určení, jestli lze šablonu použít pro určitý zdroj dat, musí každá šablona obsahovat komentář s prvky name a data. Prvek name představuje název šablony. Prvek data popisuje zdroj dat, pro který je šablona určena. Platné zdroje dat jsou:

  • customer - zákazníci
  • order - objednávky
  • order+detail - objednávky s položkami
  • orderslip+detail - dobropisy s položkami
  • product - zboží

a

  • * - všechny zdroje bez rozdílu (používá například ladící šablona)

Označení šablony s prvky name a data se musí vyskytovat na začátku šablony jako HTML komentář (uvozené <!-- a -->) a nesmí být na více než 5 řádcích.

B. Funkce Smarty

V ukázce je ve druhé části uvedena funkce Smarty {assign}, která proměnné použité v šabloně přiřazuje hodnotu. Tato část je nepovinná. Ani v případě, že chcete v šabloně použít funkce Smarty, nemusíte je umisťovat v tomto místě. Tuto možnost zmiňujeme, protože umístění konstant nebo jiného kódu v tomto místě je přehledné.

C. Definice stylu

Pro přehledné definování stylu zobrazení je vhodné použít CSS styl. Celý blok se stylem musí být uzavřen do dvojitých značek {literal}<style> a </style>{/literal}. Definice stylu není povinná.

Formát stránky, její orientace a okraje se definují pravidlem @page. Toto i další podporovaná pravidla jsou popsána v manuálu knihovny mPDF na stránce User's Guide >> CSS & Stylesheets >> Supported CSS.

D. Obsah šablony

Vlastní obsah šablony je umístěn mezi značkami <body> a </body>. Kromě textu můžete použít tabulky, obrázky, prvky formuláře a obsah formátovat pomocí HTML značek a CSS stylů. Jejich přehled najdete v manuálu knihovny mPDF na stránce User's Guide >> HTML support >> HTML Tags.

Hlavička, patička, rejstřík a jiné prvky

Knihovna mPDF umožňuje přidat do výsledného dokumentu prvky, které nelze vytvořit pomocí standardních HTML značek. Používá k tomu vlastní značky. Zde jsou některé z nich:

  • <annotation> - Přidá do dokumentu vysvětlivku
  • <barcode> - Přidá do dokumentu čárový kód
  • <columnbreak> - Začne nový sloupec
  • <columns> - Nastavuje použití sloupců na stránce
  • <dottab> - Vloží tečky směrem k napravo zarovnanému textu
  • <formfeed> - Přidá novou stránku při zachování platných HTML značek a CSS stylů
  • <htmlpagefooter> - Definuje a pojmenovává HTML patičku
  • <htmlpageheader> - Definuje a pojmenovává HTML hlavičku
  • <pagebreak> - Přidá novou stránku
  • <tocentry> - Vloží značku pro obsah
  • <tocpagebreak> - Vloží obsah
  • <watermarkimage> - Nastaví obrázek pro vodoznak
  • <watermarktext> - Nastaví text pro vodoznak

Všechny značky jsou popsané v manuálu mPDF na stránce Reference >> HTML control tags.

Překlad textů šablon

Překlad vícejazyčných textů lze provést pomocí administračních nástrojů PrestaShopu™. V administraci zvolte Nástroje >> Překlady, v bloku Upravit překlady vyberte Překlady modulů a zvolte jazyk pro překlad.

Na další stránce se objeví k překladu všechny moduly PrestaShopu™. Jsou mezi nimi také všechny šablony, stejně jako administrační rozhraní vlastního modulu. Pro snadnou identifikaci šablon je vhodné používat pro všechny šablony jednotný prefix, např. m4. Takto lze měnit všechny texty v šablonách, které používají Smarty syntaxi {l s='text k překladu'}.