Utwórz plik PDF z dowolnej encji w Drupalu - Przegląd modułu Entity Print

04.06.2021

Tworzenie dynamicznego pliku PDF jest jednym z najważniejszych punktów projektu. Najważniejsze jest znalezienie odpowiedniego rozwiązania, które spełni twoje oczekiwania i wymagania. W tym artykule pokażemy ci jeden z najpopularniejszych modułów Drupala do generowania plików PDF, który będzie pomocny przy generowaniu, przeglądaniu lub pobieraniu raportów, artykułów i faktur w formacie PDF.

Daty

Pierwsza wersja modułu została wydana 22 stycznia 2015 roku, a ostatnia aktualizacja – 18 czerwca 2020 roku. Moduł może być instalowany w:

Drupalu 7 (7.x-1.5 stabilna wersja wydania),
Drupalu 8 i 9 (8.x-2.2 stabilna wersja wydania).

Wszystkie stabilne wydania tego projektu są objęte polityką security advisory.

Popularność modułu

Według danych dotyczących użytkowania ze strony internetowej modułu, obecnie korzysta z niego około 12 tysięcy witryn.

Twórcy modułu

Moduł został stworzony i jest utrzymywany przez benjy'ego.

Do czego używany jest moduł?

Entity Print umożliwia wydrukowanie (zapisanie) dowolnej encji drupalowej (Drupal 7 i 8) lub View (jedynie Drupal 8+) do pliku PDF. Wykorzystuje silniki PDF oparte na popularnych bibliotekach PHP, takich jak Dompdf, Phpwkhtmltopdf i TCPDF.

Unboxing

Aby zainstalować Entity Print, przejdź do strony modułu lub zrób to za pomocą composera:
```
composer require "drupal/entity_print 2.x" 
```
Zainstaluj Dompdf, uruchamiając composer require
```
composer require "dompdf/dompdf:0.8.0"
```

Dodatkowo możesz zainstalować silniki Wkhtmltopdf i TCPDF.

composer require "mikehaertl/phpwkhtmltopdf ~2.1" 
composer require "tecnickcom/tcpdf ~6"

Włącz moduł Entity Print.
Przyznaj uprawnienia do pobierania plików PDF użytkownikom niebędącym administratorami.
Opcjonalnie możesz włączyć moduł Entity Print Views.

Ustawienia instalacji modułu Drupala Entity Print

Skonfiguruj Entity Print

Sprawdźmy, co ten moduł pozwala skonfigurować.

Enable Default CSS - udostępnij kilka bardzo podstawowych stylów.
Force Download - zmuś przeglądarkę do pobrania pliku PDF.
PDF - wybierz domyślny silnik PDF dla drukowania.
Paper Size - zmień rozmiar kartki, na której wydrukujesz plik PDF.
Paper Orientation - zmień orientację na poziomą lub pionową.
Enable HTML5 Parser - Dompdf nie działa, jeśli ta opcja nie jest włączona.
Disable Log - wyłącz logowanie Dompdf do log.html w katalogu tymczasowym Drupala.
Enable Remote URLs - ta opcja musi być włączona, aby CSS i Images działały, chyba że ręcznie manipulujesz źródłem.
SSL CONFIGURATION - ta opcja może być potrzebna jedynie do programowania, na produkcji nie należy jej zmieniać.
HTTP AUTHENTICATION - jeśli Twoja witryna obsługuje HTTP Authentication, możesz ustawić nazwę użytkownika/hasło.
EPub - wybierz domyślny silnik EPub dla drukowania (obecnie ta opcja nie jest obsługiwana, możesz śledzić otwarte zgłoszenie).
Word Document - wybierz domyślny silnik Word Document dla drukowania (obecnie ta opcja również nie jest obsługiwana, możesz obserwować otwarte zgłoszenie).

Preferowanym silnikiem PDF jest Dompdf, który jest (głównie) zgodnym z CSS 2.1 układem HTML i silnikiem renderującym napisanym w PHP. Jest to silnik renderujący oparty na stylach, więc będzie pobierał i odczytywał zewnętrzne arkusze stylów, wbudowane tagi stylów i atrybuty stylów poszczególnych elementów HTML. Obsługuje również większość prezentacyjnych atrybutów HTML.

Zastosowanie modułu

Po poprawnym skonfigurowaniu modułu i ustawieniu wszystkich uprawnień, możemy przystąpić do eksportowania encji i widoków do pliku PDF.

Eksportowanie encji

Entity Print dodaje wyłączone pole do trybów widoku każdego typu treści. Pole ma domyślną wartość etykiety „View PDF”. Aby to pole było widoczne dla dowolnego typu zawartości, włącz je na stronie Manage Display

(/admin/structure/types/manage/[content_type]/display).

Włączanie pola View PDF na stronie Manage Display w module Entity Print

Od teraz do naszego typu treści będziemy mieli dodany przycisk przeglądania PDF. Przycisk URL to: https://example.com/print/pdf/[entity_type]/[entity_id] (i.e. https://example.com/print/pdf/node/1)

Oto plik PDF, który chcemy zapisać lub wydrukować:

Przykład pliku PDF, który możemy zapisać albo wydrukować, w module Drupala Entity Print.

Eksportowanie Views

Po włączeniu modułu Entity Print Views, można dodać globalną opcję „Print” do nagłówka lub stopki View. Przycisk URL wygląda w ten sposób: https://example.com/print/view/pdf/[view_id]/[display_id]

Dodawanie globalnej opcji Print do nagłówka View w module Entity Print

Debugowanie

W celu łatwego i szybkiego debugowania, Entity Print udostępnia nam wersję HTML encji przesłanych do silnika PDF. URL wygląda prawie tak samo jak wyżej, ale z dołączonym /debug. Np. https://example.com/print/pdf/[entity_type]/[entity_id]/debug.

Jak ukryć link View PDF w wyeksportowanym pliku

Domyślnie link „View PDF” jest także dodawany do pliku PDF. Aby go usunąć, przejdź do strony Manage Display dla określonego typu treści. W sekcji Custom Display Settings musisz włączyć tryb widoku PDF.

Indywidualne ustawienia wyświetlania w module Entity Print

Możesz teraz wyłączyć pole Entity Print w tym trybie widoku. Następnym razem, gdy będziesz eksportował plik PDF, nie będziesz miał dołączonego linku „View PDF”.

Domyślnie tryb widoku PDF jest instalowany jedynie dla nodów. W przypadku, kiedy masz jakiekolwiek niestandardowe encje, musisz najpierw utworzyć tryb widoku PDF dla określonego typu encji poprzez „admin/structure/display-mode/view”. Możesz mu nadać dowolną nazwę, ale pamiętaj, że nazwa urządzenia powinna brzmieć „pdf”, ponieważ zostanie automatycznie poprzedzona nazwą encji.

Stylizowanie pliku PDF z twojego motywu

Poniższe przykłady pokazują, jak zarejestrować pliki CSS entity_print z pliku your_theme_name.info.yml. Możesz to zrobić dla dowolnego typu encji, a nawet widoku.

#Dodaj bibliotekę css do wszystkich nodów:

entity_print: 
node: 
all: 'YOUR_THEME_NAME/print-styling'

#Dodaj bibliotekę css do encji noda, ale wyłącznie pakiety artykułów:

entity_print: 
node: 
article: 'YOUR_THEME_NAME/print-styling'

#Dodaj bibliotekę css do wszystkich widoków:

entity_print: 
view: 
all: 'YOUR_THEME_NAME/print-styling'

Nie zapomnij zdefiniować biblioteki CSS w swoim YOUR_THEME_NAME.libraries.yml:

print-styling: version: VERSION css: theme: css/print-style.css: { }

Modyfikowanie szablonów

Dostępne są wszystkie standardowe sposoby nadpisywania szablonów. Korzystając z sugestii hooków motywu, możesz utworzyć szablon Twig i zmodyfikować treść dowolnej konkretnej encji (np. node--blog-post--pdf.html.twig). W tym szablonie możesz zmodyfikować znaczniki tak jak zwykle, używając {{content.field_example}} lub {{node.field_example}}.

Możesz modyfikować dane wyjściowe HTML całego szablonu Entity Print. Po prostu skopiuj plik entity-print.html.twig z jego podstawowej lokalizacji do swojego folderu z motywami. Korzystając z sugestii hooków motywu, możesz również utworzyć plik entity-print--node--[content-type].html.twig.

<html>
 <head>
   <meta charset="utf-8">
   <title>{{ title }}</title>
   {{ entity_print_css }}
 </head>
 <body>
   <div class="page">
     {{ content }}
   </div>
 </body>
</html>

Upewnij się, że tag zawsze zawiera {{entity_print_css}} w twoim niestandardowym pliku szablonu Twig. W przeciwnym razie niestandardowe biblioteki CSS nie będą działały.

Niestandardowe silniki PDF

Warto wspomnieć, że silniki PDF modułu Entity Print da się podłączać. Oznacza to, że możesz łatwo wprowadzić własne silniki. W tym celu musisz utworzyć klasę w your_module_name/src/Plugin/EntityPrint/NewPdfEngine.php, która implementuje Drupal\entity_print\Plugin\PrintEngineInterface ze wszystkimi wymaganymi metodami. Gdy to zrobisz, twoja wtyczka będzie dostępna na liście silników do wyboru na stronie konfiguracji.

Alternatywne rozwiązania

Jest kilka innych opcji tworzenia pliku PDF z encji w Drupalu, z którymi warto się zapoznać.

PrintFriendly & PDF jest wtyczką do Drupala 7, 8 i 9. Poniżej znajdziesz listę jej funkcji:

Jest w pełni konfigurowalna.
Z opcją On-Page-Lightbox, plik PDF otwiera się w Lightboxie.
Pozwala wydrukować lub pobrać plik PDF.
Możesz edytować stronę przed wydrukowaniem lub uzyskaniem pliku PDF, na przykład usuwając obrazy i paragrafy, których nie potrzebujesz.

Printer and PDF versions for Drupal 8+ to moduł, który działa także w Drupalu 9. Umożliwia generowanie dostosowanych do druku wersji dowolnego noda, takich jak:

wersja strony internetowej (pod /node/[node_id]/printable/print),
wersja PDF (pod /node/[node_id]/printable/pdf).

Obsługiwane biblioteki:

mPDF,
TCPDF,
wkhtmltopdf,
dompdf.

Podsumowanie

Moduł Entity Print oferuje wiele metod eksportowania encji do plików PDF za pomocą różnych silników PDF. Jest to bardzo elastyczny i konfigurowalny moduł, który pomoże ci w dynamicznym generowaniu twoich artykułów, faktur lub innych treści związanych z twoją stroną na Drupalu. Moduł został w pełni przetestowany i jest gotowy do użycia na produkcji dla Drupala 7, 8 i 9.