How to create invoices easily with document-templates package

Share on facebook
Share on twitter
Share on linkedin

Introduction

There are some common features almost every web application has: registration, login, email sending, pdf generation, admin interface etc. We created our document-templates Laravel package to allow the admins to easily edit their email (and any other) templates using a wysiwyg editor. This package is a generic templating system, which can be used to create any output format like: html, markdown, txt, etc, but the most common usage is to use html template. The package comes with build in pdf rendering engine and it can be used seamlessly with Laravel mailables. The package uses Twig as a template engine.

Why Twig instead of Blade?

This is a logical question, why would we use different template engines? We already have a good build in template engine in Laravel. The basic idea was to allow the users/admins to put some logic into the templates like: ifs, for loops etc. It could be easily solved also with Blade as well, but for security reasons I wanted to allow the developers have control on what functions/logic can be used in the editable part of the template. Twig has a built in configurable sandboxing feature. The sandbox is applied on every part of the templates which can be edited by the users/admins.

How it works?

We create a basic layout of the document, and define which parts of it can be editable by the user. To achieve this we use the block feature of Twig. In the next step we create a document class which uses a trait from the package, and defines the datasources for the document. Every document class represents a document type in your application. For example you should create different classes for invoice, confirmation email, registration email, etc. Render the document on the proper place in your application (for example generate the invoice when the payment finished).

How can I use it?

The architecture of the package consists of 3 main parts:

  1. The core features include the twig engine, datasources and the layout
  2. The rendering module allows the document rendering as html, pdf etc
  3. Admin part comes with routes, controller, vue component, and Ckeditor to quickly build the administration for the documents

You can decide if you want to simply use the core features and use the advantages of twig, and build the other parts yourself. You can also utilize the pdf rendering capabilities, or use the whole package with all the belts and whistles.

The conceptual diagram of the package can be found below:

Let’s build something!

In the next paragraphs we will build an invoice generation system from scratch using this package.

Installation

Install the package with composer:

Publish the migrations, views, vue components and config:

Run the migration

 

Create the base layout

Create the template file: resources/templates/InvoiceTemplate.html.twig with the following content:

In the above template we’ve defined 2 blocks: customer_details and order_items. These blocks will be editable in the admin area with Ckeditor.

Create the document class

Let’s create our document class in app/DocumentTemplates/InvoiceTemplate.php:

In this step we create the document class, and define the datasources for the document. For the sake of simplicity we use an array as the order data, and the User model for the customer data. To be able to use the User as a datasource for the invoice, it needs to implement  the TemplateDataSourceInterface, so we will use the ModelProvidesTemplateData trait to achieve this:

Create controller

We create a controller for administration and to test the document editing/rendering:

Add the package routes to the routes file:

Create seeders

Now it is time to fill the database with some test data. Create seeder for editable templates database/seeds/EditableTemplatesTableSeeder.php:

database/seeds/UsersTableSeeder.php:

Add these seeders to the DatabaseSeeder:

Run the seeders:

If you use Laravel 6 you might need to create frontend scaffolding, please check the Laravel documentation here:

Compile the assets:

Create the app layout – optional

If your application don’t have already, create the app layout: resources/views/layouts/app.blade.php:

Let’s try it

If everything went well when we navigate to the /document-templates/ url, we should see something like this:

The edit form should look like this:

and the generated invoice with with the placeholders filled should look like this:

Closing thoughts

The package has been tested with Laravel version >=5.7. For more information on how to use the package and for more code examples, please check the source code of the demo application here and the package documentation.

Subscribe to our newsletter

Be first to read new helpful post

Share this post with your friends

Share on linkedin
Share on xing
Share on twitter
Share on facebook

Communian – GO LIVE

In one of our previous blog posts we have announced Communian – an event platform for local communities, that will allow you to find interesting

Communian – COMING SOON

Update: We have launched communian.com on 19th November and we would like to invite you to check it out by registering. Find local communities of your

Leave a Reply

avatar
  Subscribe  
Notify of