Adding descriptive text to your invoices (viewinvoices.tpl)

[sohouk]

Adding descriptive text to your invoices (viewinvoices.tpl)

 

Following on from earlier discussions, I had a quick go at seeing if it was possible to ‘enhance’ the information provided on the client invoices. This is what I learnt and tested:

 

Backup viewinvoices.tpl first!

 

In the viewinvoices.tpl, the invoice items come from the tblinvoicesitems table in WHMCS.

 

The text for each item in the invoice comes from the ‘Description’ field of that table.

How it gets there I’m not too clear, but for my purposes its not relvant.

 

The only other key field is the ‘type’ field which holds a single description of the type of item in the invoice.

 

So, for example, I have ‘Hosting’ and ‘Domain’ as two items in the type field of my table.

Easy example:

If you just want to add some text depending on the type of invoice item, then its easy.

All you need to do is compare the invoice item type with the string you want and branch from there.

 

So, for a type ‘domain’, during the invoice populating loop (around line 93 where it says {foreach key=num item=invoiceitem from=$invoiceitems} )you would put:

{if $invoiceitem.type eq "Domain"} "Domain service transaction” {/if}

 

This simply means that if the current item being output to the invoice is of type ‘Domain’ then it prints the message, otherwise it does nothing.

 

The problem is that with one domain that is OK. But for a whole page of them it’s a bit repetitive on the invoice.

What I do in the case of many domain transactions is to test if at least one of the items is of the type ‘domain’, and if so print a message at the end of the invoice list. See later.

 

For hosting and other services its a different matter (for me).

Rather than just the simple product message (which is usually very short), I want a more descriptive text for invoice items related to services we offer.

 

The way to do this is either use the simple way above, changing the test for the type from ‘Domain’ to ‘Hosting’ or whatever service it is you have, or, do it a more complex way by testing the description string and providing a specific message depending on the result.

 

The difficulty is that Smarty does not have a direct string comparison function to test the ‘description’ text. But, we are in luck, because most PHP functions can be used in Smarty.

 

One of our hosting plans is called ‘Parking Plus’ and using the php stristr function, I can test if that name is contained in the ‘description’ text.

If it is, then I simply add some text to that invoice item using a smarty variable I created (see later). In my case the variable for Parking Plus is $pp_msg

 

Here is the full statement

 

{if stristr($invoiceitem.description,"ParkingPlus")} {$pp_msg}</br> {/if}

 

Which means: If the invoice description contains the phrase ‘ParkingPlus’ then output the string $pp_msg and a line feed, otherwise do nothing

 

Assigning a variable:

You can assign Smarty text variables on the fly without having to put them in the language files. Keeping them in the language files makes it all neater and easier to maintain, but on this occasion I use local variables in the template because I can assign them dynamically.

 

Here is how you do it. Somewhere in your template, before you want the variable put theSmarty assign statement

 

{assign var="pp_msg" value="All the text I want assigned to the variable”}

 

Now you can use $pp_msg where you want in the template (after the assignment of course).

 

 

Multiple domains:

As I mentioned, if you have many domains on an invoice, simply repeating what type of service it is gets ugly and repetitive.

I test for any domain items and put a single message at the end of the list.

All I have to do is to check all the invoice items and if any one is of a type ‘Domain’ then output my message.

If there are no domains (just other services) the don’t bother with a message (or use an alternative)

 

{if $invoiceitem.type eq "Domain"} {assign var="tmp_msg" value="This invoice contains domain registration transactions”} {else} {assign var="tmp_msg" value="”} {/if}

 

This says:

If the type is equal to ‘Domain’ then assign a smarty variable called ‘tmp_msg’ with your text, otherwise, assign the smarty variable to nothing (or an alternate message)

 

Then, output the variable $tmp_msg somewhere outside of the loop that populates the invoice table.

I put mine at around line 112 which was at the end of the items table, but before the transactions table.

 

 

I’m certain there are easier ways to accomplish the same results, but for me this works with invoices.

[meeven]

Fantastic, thank you.

 

This is the kind and level of documentation for customization that needs to be on wiki.whmcs.com but WHMCS never manages to do. Thanks again. You have probably saved people like me hours and hours of work.

[xeqution]

This should be added as a feature requests! absolute must!

[HostGuts]

This would be an excellent make over for invoices system.

Right now ringing the bells of our coder

Thanks Sohouk.

[eternitynz]

Im trying to add a few lines of descriptive text for each product I offer, for example:

 

1. Small Business Website Package $2,999

- custom artwork and logo design

- content management system

- newsletter module

- etc etc etc

 

Is it possible to achieve this using your method above?

[sohouk]

As long as you can identify an element of the order that is distinct from your other items then you can.

The invoice information provides two useful items you can test: ‘type’ or ‘description’

 

The ‘type’ field is simply the product type field as set up in the products setup, and the ‘description’ field is again the short description.

 

Knowing this we can test for values in the description field and set up the variable text as we need.

 

Using your example: ‘Small Business Website Package $2,999’

 

First assign you text to a variable:

 

{assign var="sb_msg" value="
Small Business Website Package $2,999 </ br>
- custom artwork and logo design </ br>
- content management system</ br>
- newsletter module</ br>”}

 

Assuming that the phrase ‘Small Business Website’ is unique to this product you can simply test if that string occurs in the invoice items, and if it does, use your text.

 

{if stristr($invoiceitem.description,"Small Business Website Package")} {$sb_msg}</br> {/if}

 

This produces:

 

Small Business Website Package $2,999

- custom artwork and logo design

- content management system

- newsletter module

 

However, if there are a lot of items common to the products then why not assign the individual features to separate variables and use them once when you want them.

 

Put the individual features in variables near the top of the template.

 

{assign var="ca" value=" - custom artwork and logo design </ br>”}
{assign var="cm" value=" - content management system</ br>”}
{assign var="nl" value=" - newsletter module</ br>”}

 

 

Now, simply add the ones you want together as you need them.

 

Because we put the </ br> tag into the variables, we don’t have to do it again which makes it easier to maintain.

 

Here is the output, but using three variables method instead on one phrase like this:

 

 

{if stristr($invoiceitem.description,"Small Business Website Package")} {$ca} {cm} {nl} {/if}

 

Small Business Website Package $2,999

- custom artwork and logo design

- content management system

- newsletter module

 

Trevor

[moep_za]

Thanks for this, very useful.