Move invoice templates to module based .tpl.php files

Many thanks. I've had making this patch on the backburner for some time now... this is great. : ) There are a few settings forms, though, in the order settings and notification settings, where you can specify an .itpl.php from the templates directory for e-mailed vs. on-site invoices. I think for D5, I should maybe just search both the templates and the theme templates directories for these... but maybe change it in D6.

I don't suppose you also know what it would take for D6? My thought was we should get rid of the templates directory altogether, use a module based .tpl.php, and let Drupal override that in the theme. Sound about right?

Yes, for D6 I'd switch if possible to a tpl.php to take advantage of the theme system, though probably in that case you'd need to populate all the token things as variables, rather than having them as you do now.

So, I was reviewing this issue and the patch, and I decided that at this time it's not necessary in its current form. The solution for Ubercart 1.x is to simply copy/modify the core invoice templates based on this documentation page (although looking it up now I realize it's quite hidden :( ). I don't think the patch would appropriately handle the way the settings forms work that let you select an invoice template at various places in the source.

So... moving onto Drupal 6 development, I'm moving this to patch needs work and "reconsigning" this issue to be one that moves invoice template more toward the theme layer. I think it would be good for the modules to ship w/ module based .tpl.php files and let user's override them at the theme layer. However, people should also maintain the ability to have multiple invoice templates. Some people send one invoice as a standard invoice but then a different one altogether if the order contained a certain product (like a file download or gift certificate). The solution here must allow for or rule out the use of module based .tpl.php files for the default customer/admin invoices and allow for the use of multiple invoices found in the theme layer.

I'd love to see this happen too, and would be happy to contribute code to make it so.

rszrama, it sounds like your proposed implementation will require a significant rework of the templating code, while patches like the one above could be integrated into current 1.x series without too much grief.

Do you think there's room for us to pursue both approaches, if further code along the lines of pwolanin's was contributed, and the contributions were careful to move towards (rather than in the way of) your intended result?

A couple of related posts (one by me) on the UC forums:

* http://www.ubercart.org/forum/ideas_and_suggestions/8711/themeing_layer_...
* http://www.ubercart.org/forum/support/6334/creating_custom_invoice_template

And a related issue here, allowing for symlink workarounds so we don't need to keep files for several customers in a single shared templates directory:

* http://drupal.org/node/387888 (link fixed)

I have been thinking of a few ideas for this:

1) you could use the theme template suggestions approach, so there is a default template provided by uc_order:
uc-invoice.tpl.php

Any theme can overrider that base template or provide other specific templates.
uc-invoice.tpl.php
uc-invoice-[nodetype|nid|other-identifier].tpl.php

If there is only one product there could be something like:
uc-invoice-single-[nid].tpl.php

For multiple products, the only way this would work with the current theming system is if the nid where required to be in some specific order, so the nid would have to be in say ascending order.
uc-invoice-multiple-[nid1-nid2-nid3].tpl.php

You could also do other things like have an invoice for an order that includes a product.
uc-invoice-includes-[nid].tpl.php

2) A simpler solution to the above problem of different invoice content based on the products purchased is to have a field associated with each product so you can add a message that gets included in an invoice

3) Another way would be to put the invoices into the database or files directory (it actually makes a lot of sense to have them there as an invoice is usually tied to a site not a theme or a module), you can then setup the ability to create rules to decide what invoices to send on what orders.

This is just some ideas....

rszrama
However, people should also maintain the ability to have multiple invoice templates. Some people send one invoice as a standard invoice but then a different one altogether if the order contained a certain product (like a file download or gift certificate)

This is exactly what I'm trying to achieve in Drupal 5.16 + Ubercart 5.17. I'm basically looking to send a standard invoice template for all products, except one (a free/trial product), for which I want to send a different invoice template.
Does the patch at the top of the page allow this? Any suggested reading/help on how to achieve?

Any help is greatly appreciated,

Thanks,

Mark

No, if you have a look at that patch, all it does is check a different (per-theme) directory for the theme template. Which is still a huge improvement over having to keep all your per-site templates in a (multisite, shared) single module directory.

But your use case is a really good one, and it's exciting to imagine that being available.

The attached patch implements a hook_uc_invoice_template_list hook. This allows modules to provide template files freely to uc_order.
It also implements pwolanin's patch allowing themes to override the templates provided by the modules.

Suggestions are welcomed.

Cheers !

PS: One little question: in uc_order_template_options function I didn't really understand why we have the $custom parameter: it is not used anywhere in the code.

md2 regarding #9: you should now be able to do that with CA, the patch at #11 and by implementing a hook_uc_invoice_template_list in your custom module to provide other templates.

If this patch gets accepted we need to provide a hook_update_N to update the uc_cust_order_invoice_template variable.

Bleah... New patch attached. In the previous one I omitted to replace $file with $template_file...

Edit: both patches are against the latest UC 2.x snapshot dev (2009-Jun-16)

Ultimately I'm thinking that it would be really really useful it we would allow our clients to change their templates from the UI admin interface. It would make sense to have a {uc_invoice_templates} table where we would store the templates.
This way we could use filters like pathologic, Internal path filter, etc on the text area where the templates are submitted. It really sucks to have to edit your tpl files whenever you change an url on the website or you want to add/substract some content from the template.
Also, building your invoice template into a WYSIWYG editor it is a lot better than builfing it into an IDE in my opinion.

Of course there are some problems doing this, for example how would we do the products listing in a user friendly manner ? Tokens for product title, description, etc ?

Any thoughts about this ?

I unintentionally created duplicate issue #520478: Allow themes to override order invoice templates.. If I read the patch from #14 correctly, in order to provide a new template you must create a module. With the patch from the other issue, one may simply add an additional itpl.php file in the theme's directory. Is the custom module really necessary, and what does it buy you?

As for the theme version of an existing template overriding the core one, our patches are nearly identical, so I have no issues with that part.

(BTW, my patch was written to address an urgent need for a new site going live, so that's probably why I missed this issue...)

Subscribing.

Will test when I get a chance.

For a module I've created I have a form_alter for the list of templates which submits the whole path of the templates (it looks in the uc_order template dir, my_module template dir and a theme dir that is specified in the settings).

Then I've patched uc_order_load_invoice to take the whole path.

But I agree that a hook is easier and the theme layer is available for some reasons

Subscribing.

I feel like these patches are trying to do things that the theme system already does, like figuring out where the overrides are and loading the template files. Of course, that's what the code was doing in the first place, but I think to really knock this issue out, we've got to fully embrace the way Drupal expects template files to work.

Enter theme_uc_order(). This takes the place of uc_order_load_invoice() and it even takes the exact same arguments: the order, the "op" or "view", and the specific template. I think there needs to be a hook to provide the list of available templates, but I ended up calling it hook_uc_invoice_templates(). If it wasn't for the fact that the user needs to choose which template to use in the emails and such, I wouldn't have bothered. But as it is, there isn't any other place for that data to live.

The biggest win for doing it this way, though, is that we get a preprocess hook! hook_preprocess_uc_order() lets you add anything as a variable to the invoice template. The default template_preprocess_uc_order() already adds all of the order tokens, though, so I don't know what else might be needed. However, you if don't like the way the tokens are generated, then you have the opportunity to completely change them. Drupal's theme system provides supreme flexibility.

It should be noted that the patch adds a basically empty uc_order.tpl.php. Technically, it's not needed, but I put it there as a reminder that it must exist in the theme folder if you want to override the other templates. Since the $template variable must be given to theme_uc_order(), or it defaults to "customer", that file shouldn't ever be loaded. However, if it's not there, Drupal won't load any of the theme's other invoice templates.

Hey Lyle,
I don't have time to try out this patch right now, but I fully support the concept. The theme layer is the right place for this. Reading through the patch, everything looks good to me. Just clean up the commented //function uc_order_load_invoice... line.

Now I'll just have to redo the templates on our production site... again.. :)

I'm not convinced the theme layer is actually the right place for this, although its better then in ubercart where it can't be overridden.

The problem is you can have different themes for admin/site/users and there are also contrib modules to allow to have multiple themes running at the same time for different purposes. So unless there is a way for ubercart to specify what theme it should be using when generating the invoices its possible it could end up looking in the wrong place.

I think the ideal solution would be a UI in ubercart for creating invoices which are saved to the database or filesystem.

@univate - Good points. However, Drupal's theme system allows both modules and themes to provide theme hints, so presumably by implementing hook_uc_invoice_template_list() Ubercart could scan a custom dir per-site (eg sites/example.org/uc_invoice_templates) as well as theme and module directories (incl. core Ubercart for the default templates).

If Ubercart gets hints from the current theme when selecting an invoice template, then the available templates might be affected by the use of an administration theme.

I would suggest that the default implementation of hook_uc_invoice_template_list() as implemented in UC (optionally) check the site default theme and the folder sites/[sitename]/uc_order_templates. That way we have simple defaults which suit the common use cases, and people can implement their own hook_uc_invoice_template_list() if they want to go further or have special cases.

Btw, I believe there already is a UI for storing invoices in the DB, by choosing "custom" and adding it to the invoice template field. For me, that's not an appealing option, because Ubercart's site templates are stored in the DB, while Drupal's templates are stored in the filesystem. (Sure, we could copy template code from the filesystem to the DB on each update, but this would not be good practice IMO.)

Subscribing

Subscribing

Subscribing. I was getting ready to submit a patch a lot like #1, so I'm glad there's movement on this.

subscribing.

subscribing