Modifying FusionInvoice- A Primer and Best Practices

Some Background

FusionInvoice was developed using the Laravel framework for PHP, and as such follows the MVC design pattern. If you have worked with Laravel, making modifications should be fairly straight forward. If not, the next two sections will cover a few topics that will help.

MVC- Model, View, Controller

• A model represents your data model, generally a single row in a table. It is the source of the data that will be displayed and worked with, but has no visual components.
• A view is the visual component, how the model information is displayed to the user. It is the layout of the user interface.
• A controller is the logic that is the go-between for the model and the view. It is responsible preparing data for a view, updating data from the model to the actual database, validating data, etc.

Blades

Laravel uses a templating engine called Blades. A template in this case is simply a PHP file that allows you to use logic and control structures, like conditional statements and looping, to generate HTML output. Since blades are solely focused on UI/output, they are only used in views (never models or controllers).

• App - This is the heart of the application and as such, the majority of changes you might want to make will start with a dive into this folder.
• Assets - Support libraries and graphics. Not much to be concerned with here.
• Bootstrap - Mostly managed by Laravel. Not much to be concerned with here
• Config - The folder that contains your configuration settings. The two files of note here are database.php and app.php.
• Custom - This is ideally where we will put all of our customizations.
• Database - This is managed by the application and you will rarely need to make any changes here. Of note is the migrations subdirectory. When we release updates, the migrations files are responsible for updating your database structures.
• Resources - Support libraries. Not much to be concerned with here. If you need to make changes to your specific language translations, the subfolder, Resources/Lang holds language translations which you can edit.

*FI is written with the English language, but provides translations for Spanish, French, French-Canadian, Swedish, Dutch, Italian, German and Turkish. If you do not see your language listed, reach out and we can discuss adding it

• Storage - This is managed by the application. It is where temp files get written, etc. Of special importance is the subdirectory called storage/logs. This is where your log file is written. If you are running into an error, the log file is the first place to look for clues.
• Vendor - Support libraries for various components used throughout FI. You shouldn’t need to modify anything in this folder.

Save Yourself Some Time and Effort

Stop! Before you jump right in and modify your database and/or change your core logic files, take a few minutes to look over the helpful tools and shortcuts that what we have provided to make your life easier.

Custom Views

Whenever possible, try to avoid modifying core logic files. Why? Because whenever we release an update, core files will be overwritten and you will need to re-make your original changes. The ./Custom/ folder is your friend. It provides a way for you to plug in your own views that will override the default ones.

For instance, say that you wanted to change the display order of a number of fields in the client display and edit views. To save yourself from the update overwrite headache mentioned above, you would navigate to the ./custom/overrides/ folder and create a new folder called “clients”. You would then copy the original _form.blade.php and view.blade.php files from ./app/modules/Clients/Views/Clients/ folder into your new ./custom/overrides/Clients/ folder. Any files in this folder by the same name as the core files will be used at runtime in place of the original files, and these custom/overrides files will not be overwritten by updates.

View Naming Conventions

Generally there are three types of blade views in FI.

• Index or sometimes “Table” - This represents a list of records from which you can select a specific record.
• View - This is the read-only display of the record, not editable.
• Form or often “_Form” - This is the view in edit mode.

Custom Invoice, Quote or Email Templates

Within the ./Custom/ folder, you will also notice folders for templates - email, invoice, and quotes. If you need to make a customization to the layout of any of these documents, make it here. It will avoid the potential for update overwrites and allows you to select from the original or custom versions when creating the documents.

Adding New Fields

FI has a very powerful Custom Fields system that you can use to quickly add custom fields to nearly any module, all without a single line of custom code.

You can add as many custom fields as you like to any of the following base tables: Clients, Company Profiles, Expenses, Invoices, Quotes, Recurring Invoices, Payments or Users. From the System menu - just select Custom Fields. You can choose from any of the following field types: Text, dropdown, text area, checkbox, radio, date, integer, URL, Email, Phone, Tag Selection, DateTime, Currency, Decimal, and Image.

Any custom fields that you add will automatically be displayed below the core fields in your module view.

Referencing Custom Fields in Invoice, Quote or Email Templates

You can also reference any of these new fields in your templates using the custom field label name, like this:

        {{ $invoice->customField('Expected Delivery') }}

You can even reference a related custom field from the invoice to the related client entry like this:

{{ $invoice->client->customField('Favorite Color') }}

Need Deeper Integration In Your Views?

Do you want a custom field to be displayed amongst your core fields? You can do that, with just a little bit of additional code. For this example, we will use the Client module. We will integrate a custom field we created earlier, called “Customer Rating”, which is a dropdown field type. We will make it available on the display, edit, and index views. You can find the source blade files for these views in the ./app/Modules/Clients/Views/clients/ folder.

Remember, we do not want to modify core files, so we will copy these three files and place the copies in the view overrides folder for Clients, ./custom/overrides/clients/ . The files we will copy in this instance are: view.blade.php, _form.blade.php and index.blade.php. After making the copies, we are ready to modify our override files.

Adding a custom field to the Client DISPLAY view.

After finding the location where you would like the custom field to be placed, somewhere in the <section class="content"> area, you would add an entry referencing your custom field something like this:

                     <tr>
                         <td class="col-md-2 view-field-label">
                              Customer Rating
                         </td>
                         <td class="col-md-10">
                              {!! $client->customField('Customer Rating') !!}
                         </td>
                    </tr>
 

*Note that you must enter the custom field label name exactly as you created it, including the correct capitalization.

In this example we will use the Laravel blade syntax to conditionally color the background of the custom field if the customer “Customer Rating” value is “A1”.

@if ($client->customField('Customer Rating') == "A1")
<tr style="background-color: red;">
@else
<tr>
@endif
<td class="col-md-4">{!! $client->customField('Customer Rating') !!}</td>
</tr>

Adding a custom field to the Client EDIT view.

The syntax when referencing a custom field in an edit view is a little different, but also uses the custom field label as the point of reference. Example below:

    <div class="col-md-4">
    <div class="form-group">
 @include('custom_fields._custom_fields_unbound', ['object' => isset($client) ? $client : [],'label' => 'Customer Rating'])
 </div>
 </div>

Adding a custom field to the Client INDEX (list) view.

In this example we will add our custom field for “Customer Rating” to the customer list (index.blade) file. We will also make it sortable by clicking on the column header.

In the index.blade.php <thread> section.

 <th> {!! Sortable::link('Customer Rating', 'Customer Rating') !!} </th> 

In the index.blade.php <tbody> section.

 <td> class="hidden-xs">{{ $invoice->customField('Customer Rating') }} </td> 

*Fields having multiple value options (like tags) are not sortable and are not suitable for displaying in list displays.