Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kennethormandy/craft-api2pdf
https://github.com/kennethormandy/craft-api2pdf
craft-plugin craftcms-plugin pdf pdf-generation
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/kennethormandy/craft-api2pdf
- Owner: kennethormandy
- License: mit
- Created: 2019-12-13T18:23:40.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-01-12T20:29:05.000Z (almost 2 years ago)
- Last Synced: 2024-09-17T03:16:33.478Z (3 months ago)
- Topics: craft-plugin, craftcms-plugin, pdf, pdf-generation
- Language: PHP
- Homepage: https://plugins.craftcms.com/api2pdf
- Size: 75.2 KB
- Stars: 1
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Api2Pdf plugin for Craft CMS
Generate PDFs easily, using [Api2Pdf.com](https://www.api2pdf.com)
## Requirements
This plugin requires Craft CMS 3.1.x or later, or Craft 4.0.0 or later.
## Installation
The Craft 4 version of the plugin is [currently tagged as a beta release](https://github.com/kennethormandy/craft-api2pdf/pull/5). You can install it with:
```sh
composer require kennethormandy/craft-api2pdf:^1.0.0-beta.1
```
Otherwise, require the plugin using Composer like normal:
```sh
composer require kennethormandy/craft-api2pdf
```
Then, in the Craft CMS Control Panel, go to Settings → Plugins, and click the “Install” button for Craft Api2Pdf. Or run:
```sh
./craft install/plugin api2pdf
```
## Settings
The only setting required to run the plugin is an API key from Api2Pdf, which can (and probably should) be set to an [environment variable](https://docs.craftcms.com/v3/config/environments.html):
## Actions
- [`api2pdf/pdf/generate-from-url`](#action-generate-from-url)
- [`api2pdf/pdf/generate-from-html`](#action-generate-from-html)
- [`api2pdf/pdf/merge`](#action-merge)
## Twig
- [`craft.api2pdf.generateFromUrl`](#twig-generatefromurl-function)
- [`craft.api2pdf.generateFromHtml`](#twig-generatefromhtml-function)
- [`craft.api2pdf.merge`](#twig-merge-function)
## Options
Option
Type
Description
filename
String
redirect
Boolean
Redirect directly to the PDF URL
- `filename`
- `redirect`
All [advanced options for Headless Chrome](https://www.api2pdf.com/documentation/advanced-options-headless-chrome/) to pass along to Api2Pdf are also supported.
## Examples
### Action `generate-from-url`
Get the JSON response from Api2Pdf:
```html
{{ csrfInput() }}
```
Redirect directly to the PDF url:
```html
{{ csrfInput() }}
```
### Action `generate-from-html`
Redirect directly to the PDF made using an HTML string:
```html
{{ csrfInput() }}
```
Offer an editable filename:
```html
{{ csrfInput() }}
```
### Action `merge`
Merge two hosted PDFs (generated by this plugin or otherwise), into one:
These URLs passed to this function need to be hosted PDFs. Whether or not they were previously generated via this plugin previously, or whether they are on your server doesn’t matter, as long as they are accessible at the URL.
```html
{% set urls = [
'https://example.com/one.pdf',
'https://example.com/two.pdf'
] %}
{% for url in urls %}
{% endfor %}
{{ csrfInput() }}
```
### Twig `generateFromUrl` function
```twig
{% set result = craft.api2pdf.generateFromUrl('https://example.com') %}
{% if result and result.success %}
{{ result.pdf }}
{% endif %}
```
### Twig `generateFromHtml` function
```twig
{% set result = craft.api2pdf.generateFromHtml('
Hello
') %}
{% if result and result.success %}
{{ result.pdf }}
{% endif %}
```
Slightly more detailed example:
```twig
{% set options = {
redirect: true,
filename: "test.pdf"
} %}
{% set result = craft.api2pdf.generateFromHtml('
Hello
', options) %}
{% if result and result.success %}
{# Display the URL #}
{{ result.pdf }}
{# The other pieces of metadata available #}
- {{ result.mbIn|round }}mb
- {{ result.mbOut|round }}mb
- US${{ result.cost|round }}
- {{ result.responseId }}
{% else %}
{{ result.error }}
{% endif %}
```
### Twig `merge` function
```twig
{% set urls = [
'https://example.com/one.pdf',
'https://example.com/two.pdf'
] %}
{% set result = craft.api2pdf.merge(urls) %}
{% if result and result.success %}
{{ result.pdf }}
{% else %}
{{ result.error }}
{% endif %}
```
## Notes
- This plugin is build for v1 of the Api2Pdf API, but support for the [v2 endpoint](https://www.api2pdf.com/api2pdf-launches-v2-in-beta/) may be added when it’s out of beta, the Api2Pdf client libraries are also updated
- This plugin only supports Headless Chrome for PDF generation. If you are interested in adding support for another endpoint, I’d be open to discussing a Pull Request (but note the v2 API also only supports Headless Chrome).
## License
[The MIT License (MIT)](./LICENSE.md)
Copyright © 2019–2020 [Kenneth Ormandy Inc.](https://kennethormandy.com)