PDF Generator documentation

Welcome to the documentation for PDF Generator, your complete solution for creating dynamic PDFs in Joomla! 4 and beyond. Whether you're a website owner or administrator, this extension simplifies the process of turning your content into professional-quality PDF files.

Key Features

• Seamless Integration: PDF Generator smoothly integrates with your Joomla website, streamlining PDF generation.
• Content Compatibility: Enjoy native support for Joomla's com_content and FLEXIcontent through dedicated plugins. This ensures straightforward PDF creation from articles and custom content types.
• Future-Proof: Our commitment to enhancing your experience means we're continually developing new plugins, expanding support to popular Joomla extensions like HikaShop and others (let us know your needs).
• Easy Template Creation : At the core of PDF Generator is the concept of template-based PDF generation. Customize templates for specific content types, such as Joomla categories or FLEXIcontent types. These templates are designed for user-friendliness and flexibility.
• Visual Editing Made Simple : Use the intuitive GrapesJS visual editor to design templates effortlessly. No technical expertise required. Craft visually appealing templates that align with your website's branding seamlessly.
• Generate PDFs On Your Terms : PDF Generator puts you in control of PDF file generation. Whether it's individual files/documents or entire catalogs/books, you decide when to create them. This flexibility allows you to experiment with templates and make modifications while always having PDFs ready for download.
• Creating Files : Once your template is ready, generating PDF files is straightforward. A file or PDF file associates your template with compatible articles/items. The robust Dompdf library ensures high-quality PDFs, preserving visual integrity and quality.
• Creating Catalogs/Books : Take PDF generation to the next level by assembling your created files into catalogs/books. These compilations are also generated using Dompdf, enabling you to create comprehensive documents that bring together multiple content pieces into a cohesive whole.

Operating Principle

Two types of PDFs can be created:

1. Free-form PDFs, such as a cover page.
2. PDFs generated from content data (e.g., com_content article, FLEXIcontent item).

In both cases, creation involves the use of a template that defines the PDF layout. In the first case, the template directly integrates the content, while in the second case, the content is dynamically called using shortcodes (replaced during document generation) and must be specifically associated with a data and content type.

The templates can be of three types:

• "Content," for any type of PDF.
• "Header," which can be used alongside several other ("content" and "footer") templates.
• "Footer," which can be used alongside several other ("content" and "header") templates.

The template is not linked to content: several PDFs can be generated from different templates for specific layouts from the same content. If there are multiple PDFs for a content, one of the documents can be set as the default document.

Making PDFs available for download on your site is done via a module. A download button will only display if a corresponding PDF exists and has been generated beforehand.

In this documentation, we will guide you through every aspect of PDF Generator, from installation and configuration to advanced tips and tricks. Our goal is to make your experience with PDF generation in Joomla seamless, productive, and capable of producing professional-quality documents.

Before you begin using PDF Generator, please ensure that your Joomla environment meets the following prerequisites:

• PHP Minimum Version 8.0: PDF Generator requires PHP version 8.0 or higher for optimal performance and security. Make sure your hosting environment supports PHP 8.0 or higher.
• Joomla Version 4.0 or Higher: Ensure that your Joomla installation is version 4.0 or higher to fully utilize the capabilities of the PDF Generator extension.
  

To start using PDF Generator on your Joomla website, follow these straightforward steps:

1. Register or Log In and Purchase a License

You can get your license by clicking here, then follow these steps:

• If you don't already have an account, you can register a new account during the license purchase process.
• If you already have an account, simply log in using your existing credentials, and proceed with the purchase of your PDF Generator license.

2. Download PDF Generator

After your subscription payment has been validated, you will receive a download URL by mail.

You can also access your download files by following these steps:

1. Log in to your account.
2. Hover over Your Account in the site's main menu.
3. Locate Your Files in the dropdown menu.
4. In the "Your Files" section, find the PDF Generator extension package.
5. Click on the download link to save it to your computer.

Installing the Extension

After successfully downloading PDF Generator, proceed with the installation by following the steps outlined below:

• Log in to your administration panel.
• In the admin panel, click on System in the side menu and find Install, then click on Extensions.
• Select Upload Package File.
• Click the Browse for File button or drag and drop the PDF Generator extension's ZIP file into the designated area.
• Joomla will initiate the installation process once the file has been chosen or dropped.

Activating Additionnal Plugins

When you install a new copy of the PDF Generator extension, all default plugins will be enabled automatically. However, you might need to activate additional plugins based on your specific requirements. For example, if you want to use the PDF Generator with the FLEXIcontent support plugin, you'll need to activate it. To do so, please follow these steps:

1. Log in to your administration panel.
2. Navigate to the System tab from the side menu, locate Manage and click on Plugins.
3. Search the plugin you wish to activate, lookup "PDF" to see a list of all the plugins available for the PDF Generator.
4. Click on the  icon to enable the plugin, or click on the plugin's name and enable the plugin by setting Status to "Enabled".

Please remember that the "PDF Generator Installer Plugin" must be enabled in order to benefit from automatic updates as long as your license is active!

Congratulations! You've now successfully installed and configured PDF Generator on your Joomla website. If you encounter any issues during the download or installation process or require assistance with license activation, please don't hesitate to contact our support team for prompt assistance.

Configuring PDF Generator is a straightforward process. This section outlines the key configuration options available for your convenience.

Accessing the Configuration

To access the configuration settings for PDF Generator, follow these steps:

1. Log in to your website's administrator panel.
2. In the admin panel, navigate to the System menu, and select Global Configuration.
3. Find and click on PDF Generator in the Components section.
   

You are now in the PDF Generator component, where you can configure the extension to meet your requirements.

Options Tab

1. Download ID

The Download ID is a unique identifier associated with your domain. To create a Download ID, follow these steps:

• Log in to your account on this website.
• Hover over Your Account in the site's main menu.
• Locate Your Download IDs in the dropdown menu.
• From the "Your Download IDs" page, generate a Download ID for your current domain. You can create multiple Download IDs, each corresponding to a different domain. The domain will be defined automatically once the ID is used.

• In the PDF Generator Options tab, enter the Download ID you just generated. This ensures that you can benefit from automatic updates while your license is active.

2. Recurrent Messages

PDF Generator provides the option to hide recurrent messages, such as reminders to regenerate your PDF files or catalogs after making modifications. Choose whether to show or hide these messages based on your preference.

Permissions Tab

In the Permissions tab, you'll find standard Joomla ACL (Access Control List) options that allow you to define access and permissions for different user roles:

• Configure ACL & Options: Grants permission to configure PDF Generator ACL settings and options.
• Configure Options Only: Grants permission to configure PDF Generator's options.
• Access Administration Interface: Controls access to the PDF Generator administrative interface.
• Create: Enables users to create new templates, files, and catalogs.
• Delete: Allows users to delete templates, files, and catalogs.
• Edit: Permits editing of existing templates, files, and catalogs.
• Edit State: Controls the ability to change the status (published/unpublished) of templates, files, and catalogs.
• Edit Own: Defines the ability to edit one's own templates, files, and catalogs.

Configure these permissions to align with your website's user roles and access requirements.

Saving Configuration

Remember to click the Save button to apply your configuration changes once you have finished.

By configuring PDF Generator to suit your specific needs, you can ensure seamless PDF generation and content management on your Joomla website.

Keeping PDF Generator up to date ensures that you have access to the latest features and enhancements. Here's how you can easily update the extension:

Automatic Updates

1. Log in to your administration panel.
   
2. Navigate to the System menu and locate Update.
   
3. Click on Extensions.
   

• A list of available updates will be displayed. Check if the PDF Generator extension is listed. If not, click the Check for Updates button to refresh the list. If an update is available the extension should be listed. If you encounter any problems please refer to the Troubleshooting guide.
• Click the Update button to install the latest version.

Manual Download

If you prefer to manually download and install updates, you can do so through our website:

1. Log in to your account on our website.
2. Hover over Your Account on the site's main menu, and select Your Files from the dropdown.
3. Locate the updated PDF Generator extension package and click the download link to save it to your computer.
4. Follow the installation instructions provided earlier in this documentation to install the updated version of PDF Generator on your website.

By following these steps, you can effortlessly keep PDF Generator up to date and benefit from the latest improvements.

Templates

Creating Templates

1. Start a New Template

1. Log in to your website's admin panel.
2. In the admin panel, navigate to the Components menu and select PDF Generator.
3. Click on Templates in the dropdown menu to access the template management section.
4. Click on New to begin creating a new template.

2. Template Information

When creating a template, you'll need to provide the following details:

• Title: (required) Give your template a descriptive title to easily identify it.
• Type: (required) Select the type of template you are creating. The default type is "Content," but you can also create "Header" and "Footer" templates. This feature allows users to categorize templates and conveniently reuse headers and footers when creating files.
• Data Type: (optional) Choose the data type based on the support plugin you are using:
  • If you are using the Joomla support plugin, select "Joomla!" as the data type.
  • If you are using the FLEXIcontent support plugin, choose "FLEXIcontent" as the data type.
• Content Type: (optional) Choose the content type that corresponds to the specific article/item you want to create a PDF for. The available content types are dynamically retrieved based on the selected data type:
  • For Joomla support plugin users, this refers to Joomla categories (e.g., "Courses," "Events," "Products").
  • For FLEXIcontent support plugin users, this refers to FLEXIcontent types (e.g., "Training Course," "Invoice").

3. Template Creation

• You will be taken directly to the GrapesJS Visual Editor, which provides an intuitive drag-and-drop interface for building your template. (see below for an indepth look)

4. Save Your Template

• Once you've designed your template, click "Save" to save your changes.

Your template is now ready to be used to generate PDFs.

Editor View and Options

When using the GrapesJS Visual Editor for template creation, you'll enjoy a user-friendly interface that simplifies the design process. Here's an overview of the editor's view and available options:

Designing with Ease:

The GrapesJS Visual Editor empowers you to effortlessly create templates with the following features:

• Drag-and-Drop Elements: Easily add text, images, headings, and more to your template by dragging and dropping elements onto the canvas.
• Text Editing: Double-click on text elements to make direct content edits, allowing for customization as needed.
• Formatting Tools: Access built-in formatting tools to style content, change text colors, and apply various formatting options.
• [[Shortcodes]]: Incorporate dynamic content into your template using shortcodes with the syntax [[fieldname]], which will be replaced with actual content when generating the PDF.

Content Fields (Shortcodes)

Adjacent to the editor view, you'll find the "Content Fields" element, where shortcodes ([[fieldname]]) are easily accessible. This card includes a search bar and drag and drop feature for quick shortcode insertion.

Exploring the GrapesJS Visual Editor

The GrapesJS Visual Editor offers a powerful and intuitive design environment. Here's an overview of the editor's layout and key functionality:

PDF Orientation Selection (Top Right)

• Choose between portrait and landscape PDF orientations, using the buttons in the top right corner. These orientations are optimized to match the A4 paper format as closely as possible.

Actions Panel (Top Left)

Positioned above the canvas*, the Actions Panel provides quick access to essential functions:

• Outline: Toggle outlines around components for enhanced visibility (enabled by default).
• Fullscreen: Expand the editor to fullscreen mode for immersive design.
  
• Undo and Redo: Efficiently reverse or redo recent actions for precise template design.
• Rulers: The 'Rulers' action button, when clicked, adds horizontal and vertical rulers to the canvas*, enabling an absolute positioning mode. In this mode, rulers provide precise measurements for element placement, allowing for meticulous design adjustments. The absolute positioning mode enhances your control over element placement, ensuring precise alignment.
  
• Code Editor: Access HTML and CSS editing screens in a modal for advanced modifications.

Side Panel (Adjacent to Canvas*)

Within the Side Panel, you'll discover a range of advanced creative tools. These tools vary depending on the option selected in the Options Panel. These options will allow you to:

• Styles: Customize the appearance of the selected element.
• Options: Define class names or traits for the selected element.
• Layers: Manage different layers within your template.
• Add: Insert predefined blocks via drag-and-drop onto the canvas*, including text, images, responsive containers, columns, and more...

* Canvas: In the context of the GrapesJS Visual Editor, the "canvas" refers to the main design area where you create and arrange template elements. It serves as the visual workspace for building your templates.

The GrapesJS Visual Editor combines these elements to provide a versatile and user-friendly platform for creating templates tailored to your specific needs.

Templates List View

The Templates List View in PDF Generator follows the standard Joomla layout, providing an organized interface to manage your templates effectively. This view offers a range of common actions to streamline your template management tasks. Here's an overview of the key features:

Toolbar Actions:

• Check-In: Allows you to check in templates, making them available for editing.
• Publish: Enables you to publish selected templates, making them accessible for File creation.
• Unpublish: Allows you to unpublish templates, making them temporarily unavailable for File creation.
• Archive: Archives templates, helping you organize and manage your template library.
• Trash: Moves templates to the trash, preparing them for deletion.

Filtering and Searching:

• Search Bar: Use the search bar to quickly find specific templates based on their titles or other relevant criteria.
• Filtering by State: Filter templates by their publication state (published, unpublished, archived, trashed) for efficient sorting.
• Filtering by Template Type: Easily categorize templates based on their type (content, header and footer), making it simpler to locate specific templates.
• Filtering by Data Type: Start by selecting a data type to further refine your template search.
• Filtering by Content Type: Once you've selected a data type, filter templates by content type for more precise filtering.

Deleting Templates:

To delete a template, follow these steps:

1. Move the template to the trash by selecting it and clicking the Trash toolbar action.
2. Next, filter templates by selecting the Trashed state.
3. Select the trashed template you wish to delete.
4. Before deleting, ensure that the template is not in use. If the template is in use, you will be prompted to delete the associated files first.
5. If the template is not in use, you can safely click the Empty Trash button to permanently remove the template.

This process ensures proper template deletion while maintaining an organized template library.

Files

Creating Files

The PDF Generator extension offers flexibility in creating files/documents, whether you need a single file or multiple files. Follow these steps to begin creating your desired files:

1. Start a New File

1. Begin by logging in to your website's admin panel.
2. In the admin panel, navigate to the Components menu and select PDF Generator.
3. Click on Files to access the file management section.
4. Select New from the dropdown menu, where you can choose between "New" for single-file creation or "New (multiple)" for the multiple file creation process.

2. File Details

When creating a file, you'll be required to provide specific details:

• Title: Assign a descriptive title to your file for easy identification. If you leave the title blank, the title will be set automatically, defaulting to either the name of the associated article (if applicable) or the name of the chosen template.
• Set as Default File: When creating a file, you have the option to set it as the default file. This feature comes into play when you want to display a download button in the frontend of your website, typically achieved using a module. If you use the "autoload file" option in the module, the default file will be automatically retrieved and displayed when multiple files are associated with the content being viewed. By default if no other file was found for the associated content (if applicable) the file will be marked as default file.
• Template: (required) Choose the template that will be used for generating the PDF content.
• Header: (optional) Select a header template to include at the beginning of your PDF file.
• Footer: (optional) Choose a footer template to append at the end of your PDF file.
• Associated Article: (If applicable) Select the associated article for your file. Articles are dynamically retrieved based on the selected template. All articles with the same data type (Joomla!, FLEXIcontent) and content type (category for Joomla or type for FLEXIcontent) will be available for selection.

3. Configuration Options

In addition to the file details provided in the "General" tab when creating or editing a file, the PDF Generator extension offers further customization options in the "Configuration" tab. These settings allow you to fine-tune the appearance and layout of your PDF files. Here's an overview of the configuration settings:

• Margins: Choose between two margin options:
  • Default: Utilizes the default (standard A4) page margins for your PDF file .
  • None: Removes all margins, allowing your content to extend to the edges of the page.
• Orientation: Select the page orientation for your PDF file:
  • Portrait: The standard vertical orientation.
  • Landscape: A horizontal orientation that may be suitable for certain content layouts.
• Pagination: Decide whether you want to include pagination in your PDF file.
• Header Height: Specify the height of the header section in your PDF file. This option allows you to control the space reserved for header content.
• Footer Height: Set the height of the footer section in your PDF file. Similar to the header height, this option provides control over the footer space.

4. Save Your File

• Once you've finished creating your file, click Save to save your changes.
• You can also generate your file imediatly, find the "Save & Close" dropdown, and select Save & Generate.

Creating Multiple Files

If you need to create multiple files, the file titles will be managed as follows:

• If a title is set, titles will be incremented for each file created.
• If articles are selected, each file will be named after its corresponding article. In cases of duplicate names, files will be automatically incremented.

Creating multiple files is especially useful when you need to generate files for articles of the same content type, streamlining the process for greater practicality and efficiency.

Files List View

The Files List View in PDF Generator offers a well-organized interface to efficiently manage your files and documents. This view provides a range of options and actions, including standard toolbar actions and specific PDF actions, to simplify your file management tasks. Here's an overview of the key features:

Standard Toolbar Actions:

• Check-In: This action allows you to check in files, making them available for editing.
• Publish: Enables you to publish selected files, making them available to download (if your file has been generated and the download button is available) and for addition to your Catalogs.
• Unpublish: Allows you to unpublish files, making them temporarily unavailable for download and for Catalog addition.
• Archive: Archives files, helping you organize and manage your file library effectively.
• Trash: Moves files to the trash, preparing them for deletion.

PDF Actions:

The PDF Actions button in the toolbar provides additional functionality for working with generated PDF files. Here are the available actions:

• Generate PDFs: Easily generate multiple PDF files for selected documents with a single click.
• Remove Generated PDFs: If you need to remove generated PDF files, this action streamlines the process for you. This action is disabled if the PDF file has not been generated yet.

Filtering and Searching:

• Search Bar: Use the search bar to quickly find specific files based on their titles or other relevant criteria.
• Filtering by State: Filter files by their publication state (published, unpublished, archived, trashed) for efficient sorting.
• Filtering by Template: Categorize files based on their associated templates, making it simpler to locate specific files.

Line-Specific Actions:

Each file entry in the list includes an "Actions" tab, offering quick access to various functions:

• Preview: Clicking this action opens a new tab, displaying a preview of the PDF file. The preview includes any shortcodes replaced with the article content you selected (if applicable).
• Generate: Generate a PDF file based on the selected document.
• Download: Download the generated PDF file for offline use. This action is disabled if the PDF file has not been generated yet.
• Debug: Clicking this action opens a modal displaying the HTML generated, which will be served to Dompdf to create the PDF file. This can help you troubleshoot any issues with the file generation process.

• Add to Catalog: Clicking this action opens a modal with a list of your catalogs. You can add your file to an existing catalog or create a new one. If the catalog did not contain the file yet, it will be selected by default, and a prompt will remind you that you must save the catalog for this to take effect.

• Remove generated PDF: Remove the generated PDF file. This option is only available if the PDF file has been generated.

Template Editing Access:

Easily access the templates that compose each file, including content, header, and footer templates, for further customization and adjustments.

Organized File Deletion:

To delete a file, follow these organized steps:

1. Move the file to the trash by selecting it and clicking the Trash toolbar action.
2. Next, filter files by selecting the Trashed state.
3. Select the trashed file you wish to delete.
4. Before deleting, ensure that the file is not in use. If it is in use by a catalog, you will be prompted to remove the file from the catalog first.
5. If the file is not in use, you can safely click the Empty Trash button to permanently remove the file.

This process ensures proper file deletion while maintaining an organized file library.

Catalogs/Books

Creating Catalogs/Books

The PDF Generator extension allows you to organize your files into catalogs or books for better management and presentation. Follow these steps to create catalogs or books:

1. Start a New Catalog/Book

1. Begin by logging in to your website's admin panel.
2. In the admin panel, navigate to the Components menu and select PDF Generator.
3. Click on Catalogs to access the catalog management section.
4. Click on New to create a new catalog or book.

2. Catalog Details

When creating a catalog or book, you'll need to specify specific details:

• Title: (required) Assign a descriptive title to your catalog or book for easy identification.
• Override Catalog Styles: (optional) Choose to override catalog styles to customize the appearance of your catalog or book.
• Files: (required, at least one) Select the files you want to include in the catalog or book.

File Selection and Arrangement:

When selecting files, you will encounter a dual listbox interface that allows you to manage your files efficiently:

• Search Bar: You can use the search function to filter both the available and selected options.
• Available Options: Displays a list of available files sorted alphabetically. You can select multiple files using either the Shift + click or Ctrl + click combination to add them simultaneously to the selected documents list, with the help of the drag and drop system.
• Selected Options: Lists the files you've chosen to include in your catalog or book. You can easily re-arrange the order of the files by utilizing the drag and drop system in the selected options list.

3. Configuration Options

In addition to the catalog details provided in the "General" tab when creating or editing a catalog or book, the PDF Generator extension offers further customization options in the "Configuration" tab. These settings allow you to fine-tune the appearance and layout of your catalogs or books. Here's an overview of the configuration settings:

• Margin: Choose between two margin options:
  • Default: Utilizes the default (standard A4) page margins for your catalog or book.
  • None: Removes all margins, allowing your content to extend to the edges of the page.
• Orientation: Select the page orientation for your catalog or book:
  • Portrait: The standard vertical orientation.
  • Landscape: A horizontal orientation that may be suitable for certain content layouts.
• Pagination: Decide whether you want to include pagination in your catalog or book.

4. Save Your Catalog/Book

Once you've finished creating your catalog or book, click Save to save your changes. You can also generate your catalog or book immediately, find the "Save & Close" dropdown, and select Save & Generate.

Catalogs List View

The Catalogs/Books List View in PDF Generator provides an organized interface to efficiently manage your catalogs or books. This view offers a range of options and actions to simplify your catalog and book management tasks. Here's an overview of the key features:

Standard Toolbar Actions:

• Check-In: This action allows you to check in catalogs or books, making them available for editing.
• Publish: Enables you to publish selected catalogs or books, making them accessible for download (if your catalog has been generated and the download button is available) .
• Unpublish: Allows you to unpublish catalogs or books, making them temporarily unavailable for download.
• Archive: Archives catalogs or books, helping you organize and manage your catalog and book library effectively.
• Trash: Moves catalogs or books to the trash, preparing them for deletion.

PDF Actions:

The PDF Actions button in the toolbar provides additional functionality for working with generated PDF files. Here are the available actions:

• Generate PDFs: Easily generate PDF files for selected catalogs or books with a single click.
• Remove Generated PDFs: If you need to remove generated PDF files for catalogs or books, this action streamlines the process for you. This action is disabled if the PDF file has not been generated yet.

Filtering and Searching:

• Search Bar: Use the search bar to quickly find specific catalogs or books based on their titles or other relevant criteria.
• Filtering by State: Filter catalogs or books by their publication state (published, unpublished, archived, trashed) for efficient sorting.

Line-Specific Actions:

Each catalog or book entry in the list includes an "Actions" tab, offering quick access to various functions:

• Preview: Clicking this action opens a new tab, displaying a preview of the catalog or book.
• Generate: Generate PDF files for the selected catalog or book.
• Download: Download the generated PDF files for offline use. This action is disabled if the PDF files have not been generated yet.
• Debug: Clicking this action opens a modal displaying the HTML generated, which will be served to Dompdf to create the PDF files. This can help you troubleshoot any issues with the generation process.
• Remove generated PDF: Remove the generated PDF file. This option is only available if the PDF file has been generated.

Deleting Catalogs:

To delete a catalog, follow these steps:

1. Move the catalog to the trash by selecting it and clicking the Trash toolbar action.
2. Next, filter catalogs by selecting the Trashed state.
3. Select the trashed catalog you wish to delete.
4. Click the Empty Trash button to permanently remove the catalog.

This process ensures proper catalog deletion while maintaining an organized catalog library.

Displaying Download Buttons in the Frontend

To allow users to download files and catalogs from your Joomla website's frontend, you can use two modules: the Download File Module and the Download Catalog Module. These modules provide an easy way to showcase downloadable content to your site visitors.

Download File Module

The Download File Module is used to display individual files as download buttons on your website. Here's how to set it up:

1. Access Module Management:

• Log in to your website's admin panel.
• In the admin panel, navigate to the Content menu and select Site Modules.
  

2. Create a New Download File Module:

• Click on the New button to create a new module.
• From the list of available modules, select PDF Generator Module - Download File.

3. Module Settings:

• Title: (required) Provide a descriptive title for your module in the "Title" field. This title is for internal reference and helps you identify the module easily.
• Autoload File: This option determines whether the module will automatically attempt to retrieve the PDF file associated with the content being viewed. If enabled, the module will try to find and display the appropriate PDF file based on the content being viewed. The "Set as default file" option in the file/document creation process plays a crucial role here. When multiple files are associated with the same content, the one marked as the default file will be displayed for download.
• File: (Autoload disabled) When the "Autoload File" option is disabled, you can manually select the specific file you want to make available for download. Choose from the list of files previously created using the PDF Generator extension.
• Text: (optional) Customize the text to display inside the download button. By default, this field is empty, but you can enter text that suits your website's context or user preferences.
• Show download icon: Decide whether to display a download icon alongside the download button. Enabling this option adds a visual cue to the button, indicating that it's used for downloading content.
• Css class: (optional) If you have specific styling requirements for the download button, you can apply custom CSS classes to the button element. This allows you to tailor the button's appearance to match your website's design.

4. Customization:

• Customize the module's display by adjusting settings such as the module position, menu assignment, and module layout.
• You can also configure additional options related to the module's appearance and behavior.

5. Save and Publish:

• Click the Save & Close button to save your module settings.
• Make sure the module is published by checking the Status option in the module settings.

6. Assign the Module to a Menu Item:

To display the download button on a specific page of your website, you can assign the module to a menu item.

• Navigate to the Menus menu and select "Your Menu."
• Edit the menu item for the page where you want to display the download button.
• In the Module Assignment tab, assign the Download File Module you created to this menu item.

Now, when users visit the page associated with the menu item, they will see a download button that allows them to download the file you specified in the module settings.

Download Catalog Module

The Download Catalog Module is used to display catalogs or books as download buttons on your website. Here's how to set it up:

1. Access Module Management:

• Log in to your website's admin panel.
• In the admin panel, navigate to the Content menu and select Site Modules.

2. Create a New Download Catalog Module:

• Click on the New button to create a new module.
• From the list of available modules, select PDF Generator Module - Download Catalog.

3. Module Settings:

• Title: (required) Provide a descriptive title for your module in the "Title" field. This title is for internal reference and helps you identify the module easily.
• Views: Specify where you want the catalog download button to appear, either on item views, category views, or both.
• Catalog: Select the catalog/book you want to make available for download. Choose from the list of catalogs previously created using the PDF Generator extension.
• Text: (optional) Customize the text to display inside the download button. By default, this field is empty, but you can enter text that suits your website's context or user preferences.
• Show download icon: Decide whether to display a download icon alongside the download button. Enabling this option adds a visual cue to the button, indicating that it's used for downloading content.
• Css class: (optional) If you have specific styling requirements for the download button, you can apply custom CSS classes to the button element. This allows you to tailor the button's appearance to match your website's design.

4. Customization:

• Customize the module's display by adjusting settings such as the module position, menu assignment, and module layout.
• You can also configure additional options related to the module's appearance and behavior.

5. Save and Publish:

• Click the Save & Close button to save your module settings.
• Make sure the module is published by checking the Status option in the module settings.

6. Assign the Module to a Menu Item:

To display the download button on a specific page of your website, you can assign the module to a menu item.

• Navigate to the Menus menu and select "Your Menu."
• Edit the menu item for the page where you want to display the download button.
• In the Module Assignment tab, assign the Download Catalog Module you created to this menu item.

Now, when users visit the page associated with the menu item, they will see a download button that allows them to download the catalog or book you specified in the module settings.

Content Actions Plugin

The Content Actions Plugin seamlessly integrates into the PDF Generator, offering a streamlined approach to manage templates, files, and catalogs directly from the content article/item edit view. It introduces a new PDF Generator button within the article/item toolbar. Clicking this button opens a modal dialog with three primary options, adapting dynamically to enhance user experience:

Manage Templates:

This option is always available, empowering users to oversee and edit templates related to the specific content type of the article/item. When creating templates through this option, the data type and content type are pre-defined based on the article/item's content type. Additionally, the associated content fields are automatically loaded and can be inserted as shortcodes within the template. In cases where no compatible template is found, users have the option to create a new one.

Manage Files:

Users can efficiently manage and select files/documents linked to the article/item directly from this option. The available templates are pre-defined based on the article/item's content type, ensuring compatibility. However, it's important to note that this option will be disabled if no compatible template is found for the article/item's content type. When creating files through this option, the selected template will already be associated with the current article/item being edited. This streamlined process minimizes errors and enhances efficiency, as users can quickly set up files/documents for PDF generation, provided that a compatible template exists for the content type.

Manage Catalogs:

When users need to organize content into catalogs or books for better presentation and management, this option becomes available. Users can efficiently select and configure catalogs or books related to the article/item. A new switch is enabled by default when creating catalogs through this option, filtering available options to display only files related to the content (article/item being edited). This ensures that catalogs are directly associated with the article/item and contain relevant content. However, it's important to note that the "Manage Catalogs" option will be disabled if no compatible files/documents are found for the article/item. This takes both the content type and article association into account, ensuring that catalogs are created and configured in contexts where they can be used effectively.

By pre-defining crucial elements in the template, file, and catalog creation processes, the Content Actions Plugin enhances efficiency, minimizes errors, and ensures that users can work seamlessly with PDF generation resources while maintaining context and relevance.

Adding Custom Fonts

In PDF generation, custom fonts can be invaluable for achieving a distinctive and branded look for your documents. The PDF Generator extension allows users to incorporate custom fonts into their templates. A custom font typically consists of the following components:

• Font Family: (required) A unique name for your custom font, which you'll reference in your template styling.
• Alternative Font: (optional) Alternative font families to use if the primary custom font is not available. These alternatives ensure graceful fallback in case the custom font can't be loaded. You can define multiple alternative fonts by separating them with commas.
• Font Files: (required, at least one) A set of four font files, each corresponding to a different font style:
  • Regular
  • Bold
  • Italic
  • Bold Italic

Here's how to add custom fonts to PDF Generator:

1. Upload Font Files:

• Log in to your website's admin panel.
• In the admin panel, navigate to the Components menu and select PDF Generator.
• Click on Fonts to access the custom font management section.
• Upload the four TTF font files for your custom font by clicking the New button. You can also choose to upload only one file, but note that only the font types uploaded (regular, bold, italic, or bold italic) will be available for use.

2. Provide Font Details:

• On the same edit screen for your custom font, you can define the Font Family Name and Alternative Fonts, separated by commas if multiple alternatives are needed.
• Ensure that you enter consistent names and associations to facilitate font styling in your templates.

3. Save Your Custom Fonts:

• Click Save to save your custom fonts. They are now available for use in your template styling.

4. Using Custom Fonts in Templates:

• When creating or editing templates, you can apply your custom fonts using the GrapesJS visual editor. Simply select the Font Family you provided in the Typography section from the Styles tab, or include it in your CSS via the code editor.

By following these steps, you can seamlessly integrate custom fonts into your PDF templates, enhancing the visual appeal and brand identity of your generated PDF documents.

Display Options

When adding shortcodes (content fields) to your template, you can apply various display options to customize the output. These options allow you to control the appearance of specific field types. Here's a breakdown of the available display options:

Image Fields:

• Size: Define the size of an image field using [[imageField#size:200]]. If you specify only one value, it's considered the width. To set both width and height, separate the values with "x" like this: [[imageField#size:200x200]].

Image Gallery Fields:

• Size: Specify the size for each image in the gallery. Use [[imageGalleryField#size:200]] for the width or [[imageGalleryField#size:200x200]] for both width and height.
• Additional Image Gallery Options: Customize the image gallery display further:
  • Cols: Specify the number of columns with #cols:value.
  • Gap: Define spacing between images in pixels using #gap:value. You can set the gap individually for the X and Y axes with #gap_x:value and #gap_y:value.
  • Vertical Alignment: Control vertical alignment using #v_align:value.

You can chain various display options, for example: [[imageGalleryField#size:200#cols:3#gap_x:10#gap_y:5#v_align:middle]].

List Rendering:

• List Type: Customize the list type by using [[fieldName#list_type:ol]] for an ordered list or [[fieldName#list_type:string]] for a comma-separated string. By default, lists are rendered as unordered lists.
• Custom Separator: Define a custom separator using #separator: my separator. For example, [[fieldName#list_type:string#separator: / ]] separates items with slashes.
• Line Break Separator: Setting the separator to "br" inserts a line break between items.

By utilizing these display options, you can tailor the presentation of your content fields to meet your specific layout and formatting requirements.

Advanced Customization (Developers):

For advanced users and developers, the PDF Generator extension offers even greater customization possibilities. You can override the layouts of list types and image galleries by accessing and modifying the respective PHP files. This level of control empowers you to create highly tailored PDF document layouts to meet your specific requirements.

By delving into the underlying PHP files, you can exert fine-grained control over the presentation of your content fields, giving you unparalleled flexibility in PDF document generation.

Template Override

Work in progress.

While PDF Generator for Joomla is designed to provide a seamless PDF generation experience, you may encounter certain issues or challenges. This section addresses some common problems and offers solutions to help you overcome them.

Differences Between GrapesJS Visual Editor and Dompdf Output:

• Issue: You may encounter situations where what is displayed within the GrapesJS Visual Editor during template design differs from what is generated by the Dompdf library in the final PDF output.
• Solution: To manage discrepancies between the GrapesJS editor and Dompdf output:
  • Simplified Template Design: Consider simplifying your template design within the GrapesJS Visual Editor. Sometimes, overly complex layouts or styling can lead to inconsistencies in the final PDF output.
  • Manual Tweaks: If specific elements or styling properties are not rendering correctly in the PDF, you may need to manually adjust the HTML and CSS within your template. Carefully review the code to identify and correct any inconsistencies.
  • Testing and Iteration: Regularly test your templates with real content to identify any discrepancies early in the design process. This allows you to make adjustments and fine-tune your templates for accurate PDF generation.
  • Stay Informed: Keep an eye on updates for the PDF Generator extension. Updates may include improvements to PDF rendering and compatibility, helping to reduce discrepancies over time.
  • Community Support: If you encounter specific rendering differences that are challenging to resolve, take a look at the PDF Generator support page, or consider reaching out to the Joomla community forums, or experienced Joomla developers for guidance and assistance.

While striving for the best consistency possible between the GrapesJS editor and the final PDF output is our goal, it's important to recognize that some variations may occur due to differences in rendering engines and the limitations of the Dompdf library. Regular testing, careful template design, and community support can help you manage and minimize these differences effectively.

Limited CSS Support in Dompdf:

• Issue: Dompdf primarily supports CSS 2.1 and some CSS 3 properties. As a result, advanced layout techniques like Flexbox and CSS Grid may not work as expected, and certain CSS properties may not be fully supported.
• Solution: To address CSS compatibility issues:
  • Avoid Advanced CSS Techniques: When designing templates, avoid using advanced CSS layout techniques such as Flexbox and CSS Grid. Stick to CSS 2.1 and basic CSS 3 properties for consistent PDF rendering.
  • Test and Iterate: Regularly test your templates with Dompdf to identify any specific CSS properties or features that may not render correctly. Make adjustments as needed.

To view the complete list of CSS compatibility with Dompdf, please click here.

Blank Pages or Incorrect PDF Displays:

• Issue: Dompdf, the library used for PDF generation, can have difficulty splitting large tables over multiple pages. This may result in blank pages being inserted or the PDF displaying incorrectly.
• Solution: To mitigate this issue, consider the following workarounds:
  • Split Large Tables: If you have large tables in your content, try splitting them into smaller tables. This can make it easier for Dompdf to handle pagination without introducing blank pages.
  • Adjust Template Layout: Review your template layout to see if there are any elements causing layout problems in the PDF. Sometimes, altering the template structure can improve PDF generation.

Shortcodes (Item Fields) Compatibility and Ongoing Improvements:

• Issue: Shortcodes representing item fields, especially those from FLEXIcontent, can face challenges due to the extensive variety of fields available and the potential for custom user-created field plugins. In some cases, users may encounter differences between their expectations and the actual output when using these fields. This discrepancy arises from the need to determine appropriate outputs for fields that haven't undergone exhaustive testing or standardization.
• Solution and Ongoing Efforts:
  • Output Decisions: To address this diversity, the PDF Generator extension must make output decisions when encountering various fields. These decisions aim to ensure that the generated PDF remains coherent and functional.
  • Alignment with Expectations: Users may find that the output for certain fields doesn't align with their expectations, especially for complex or custom fields. This situation occurs because defining a one-size-fits-all output for every field type is impossible.
  • Ongoing Improvement: The development team is committed to improving field compatibility and output consistency. Regular updates may enhance field rendering and alignment with user expectations.
  • User Feedback: User feedback is invaluable for pinpointing field-related issues and guiding improvements. If you encounter challenges with specific fields or have suggestions for better compatibility, consider reaching out to the development team or community channels to share your insights.
  • Documentation: As part of the ongoing efforts, documentation updates may provide clearer guidance on working with various fields, including custom and complex types.

Our development team is dedicated to enhancing compatibility and seeking user input to refine field outputs. Continued testing and user involvement are crucial to addressing field-related challenges effectively.

Template Rendering Issues:

• Issue: Templates may not render as expected in the PDF, leading to inconsistencies or unexpected results.
• Solution: To troubleshoot template rendering issues:
  • Ensure that your templates are correctly designed using the GrapesJS Visual Editor. Verify that all elements are appropriately placed and formatted within the template.
  • Double-check your template's HTML and CSS to identify any potential issues that might affect PDF rendering.
  • Test the template with different article/items to ensure compatibility.

PDF Generation Errors:

• Issue: You may encounter errors during the PDF generation process.
• Solution: When dealing with PDF generation errors:
  • Review the template and file configurations to ensure they are correctly set up.
  • Check for any missing or incorrect shortcodes in your templates that could cause issues during PDF generation.
  • Examine the template's HTML and CSS for any syntax errors that may affect rendering.

File Association Problems:

• Issue: Files may not associate correctly with articles or content items.
• Solution: To address association problems:
  • Verify that the content type and data type settings in your templates match those in your articles or content items.
  • Ensure that files are linked to the correct articles or content items.
  • If associations are still problematic, consider recreating the file from scratch.

PDF Display in Frontend:

• Issue: The PDF download buttons may not display correctly in your website's frontend.
• Solution: To resolve frontend display issues:
  • Confirm that the associated PDF files and catalogs are published and generated. Without this, the download buttons will not appear.
  • Check the module settings for the Download File Module and Download Catalog Module to ensure they are correctly configured.

These troubleshooting steps should help you address common issues that may arise when using PDF Generator. If you encounter more specific or technical problems, you may need to consult our support, Joomla community forums, or a Joomla developer for further assistance.