Difference between revisions of "Freeside:3:Documentation:Developer/FS/Template Mixin"

Revision as of 05:42, 10 February 2015

conf [ MODE ]

Returns a configuration handle (FS::Conf) set to the customer's locale.

If the "mode" pseudo-field is set on the object, the configuration handle will be an FS::invoice_conf for that invoice mode (and the customer's locale).

print_text OPTIONS

Returns an text invoice, as a list of lines.

Options can be passed as a hash.

time, if specified, is used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

template, if specified, is the name of a suffix for alternate invoices.

notice_name, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)

print_latex HASHREF

Internal method - returns a filename of a filled-in LaTeX template for this invoice (Note: add ".tex" to get the actual filename), and a filename of an associated logo (with the .eps extension included).

See print_ps and print_pdf for methods that return PostScript and PDF output.

Options can be passed as a hash.

time, if specified, is used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

template, if specified, is the name of a suffix for alternate invoices. This is strongly deprecated; see FS::invoice_conf for the right way to customize invoice templates for different purposes.

notice_name, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)

print_generic OPTION => VALUE ...

Internal method - returns a filled-in template for this invoice as a scalar.

See print_ps and print_pdf for methods that return PostScript and PDF output.

Required options

format

The format option is required and should be set to html, latex (print and PDF) or template (plaintext).

Additional options

notice_name

Overrides "Invoice" as the name of the sent document.

today

Used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

logo_file

Logo file (path to temporary EPS file on the local filesystem)

cid

CID for inline (emailed) images (logo)

locale

Override customer's locale

unsquelch_cdr

Overrides any per customer cdr squelching when true

no_number

Supress the (invoice, quotation, statement, etc.) number

no_date

Supress the date

no_coupon

Supress the payment coupon

barcode_file

Barcode file (path to temporary EPS file on the local filesystem)

barcode_img

Flag indicating the barcode image should be a link (normal HTML dipaly)

barcode_cid

Barcode CID for inline (emailed) images

preref_callback

Coderef run for each line item, code should return HTML to be displayed before that line item (quotations only)

template

Dprecated. Used as a suffix for a configuration template. Please don't use this, it deprecated in favor of more flexible alternatives.

print_ps HASHREF | [ TIME [ , TEMPLATE ] ]

Returns an postscript invoice, as a scalar.

Options can be passed as a hashref (recommended) or as a list of time, template and then any key/value pairs for any other options.

time an optional value used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

notice_name, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)

print_pdf HASHREF | [ TIME [ , TEMPLATE ] ]

Returns an PDF invoice, as a scalar.

Options can be passed as a hashref (recommended) or as a list of time, template and then any key/value pairs for any other options.

time an optional value used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

template, if specified, is the name of a suffix for alternate invoices.

notice_name, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)

print_html HASHREF | [ TIME [ , TEMPLATE [ , CID ] ] ]

Returns an HTML invoice, as a scalar.

time an optional value used to control the printing of overdue messages. The default is now. It isn't the date of the invoice; that's the `_date' field. It is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.

template, if specified, is the name of a suffix for alternate invoices.

notice_name, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)

cid is a MIME Content-ID used to create a "cid:" URL for the logo image, used when emailing the invoice as part of a multipart/related MIME email.

terms; due_date; due_date2str; balance_due_msg; balance_due_date; _date_pretty

Returns a string with the date, for example: "3/20/2008", localized for the customer. Use _date_pretty_unlocalized for non-end-customer display use.

_date_pretty_unlocalized

Returns a string with the date, for example: "3/20/2008", in the format configured for the back-office. Use _date_pretty for end-customer display use.

email HASHREF

Emails this template.

Options are passed as a hashref. Available options:

from

If specified, overrides the default From: address.

notice_name

If specified, overrides the name of the sent document ("Invoice" or "Quotation")

template

(Deprecated) If specified, is the name of a suffix for alternate template files.

Options accepted by generate_email can also be used.

generate_email OPTION => VALUE ...

Options:

from

sender address, required

template

alternate template name, optional

print_text

text attachment arrayref, optional

subject

email subject, optional

notice_name

notice name instead of "Invoice", optional

Returns an argument list to be passed to FS::Misc::send_email.

mimebuild_pdf

Returns a list suitable for passing to MIME::Entity->build(), representing this invoice as PDF attachment.

_items_sections OPTIONS

Generate section information for all items appearing on this invoice. This will only be called for multi-section invoices.

For each line item (FS::cust_bill_pkg record), this will fetch all related display records (FS::cust_bill_pkg_display) and organize them into two groups ("early" and "late" according to whether they come before or after the total), then into sections. A subtotal is calculated for each section.

Section descriptions are returned in sort weight order. Each consists of a hash containing:

description: the package category name, escaped subtotal: the total charges in that section tax_section: a flag indicating that the section contains only tax charges summarized: same as tax_section, for some reason sort_weight: the package category's sort weight

If 'condense' is set on the display record, it also contains everything returned from _condense_section(), i.e. _condensed_foo_generator coderefs to generate parts of the invoice. This is not advised.

The method returns two arrayrefs, one of "early" sections and one of "late" sections.

OPTIONS may include:

by_location: a flag to divide the invoice into sections by location. Each section hash will have a 'location' element containing a hashref of the location fields (see FS::cust_location). The section description will be the location label, but the template can use any of the location fields to create a suitable label.

by_category: a flag to divide the invoice into sections using display records (see FS::cust_bill_pkg_display). This is the "traditional" behavior. Each section hash will have a 'category' element containing the section name from the display record (which probably equals the category name of the package, but may not in some cases).

summary: a flag indicating that this is a summary-format invoice. Turning this on has the following effects: - Ignores display items with the 'summary' flag. - Places all sections in the "early" group even if they have post_total. - Creates sections for all non-disabled package categories, even if they have no charges on this invoice, as well as a section with no name.

escape: an escape function to use for section titles.

extra_sections: an arrayref of additional sections to return after the sorted list. If there are any of these, section subtotals exclude usage charges.

format: 'latex', 'html', or 'template' (i.e. text). Not used, but passed through to _condense_section().

total_line_generator FORMAT

Returns a coderef used for generation of invoice total line items for this usage_class. FORMAT is either html or latex

_items_pkg [ OPTIONS ]

Return line item hashes for each package item on this invoice. Nearly equivalent to

$self->_items_cust_bill_pkg([ $self->cust_bill_pkg ])

OPTIONS are passed through to _items_cust_bill_pkg, and should include 'format' and 'escape_function' at minimum.

To produce items for a specific invoice section, OPTIONS should include 'section', a hashref containing 'category' and/or 'locationnum' keys.

'section' may also contain a key named 'condensed'. If this is present and has a true value, _items_pkg will try to merge identical items into items with 'quantity' equal to the number of items (not the sum of their separate quantities, for some reason).

_items_cust_bill_pkg CUST_BILL_PKGS OPTIONS

Takes an arrayref of FS::cust_bill_pkg objects, and returns a list of hashrefs describing the line items they generate on the invoice.

OPTIONS may include:

format: the invoice format.

escape_function: the function used to escape strings.

DEPRECATED? (expensive, mostly unused?) format_function: the function used to format CDRs.

section: a hashref containing 'category' and/or 'locationnum'; if this is present, only returns line items that belong to that category and/or location (whichever is defined).

multisection: a flag indicating that this is a multisection invoice, which does something complicated.

preref_callback: coderef run for each line item, code should return HTML to be displayed before that line item (quotations only)

Returns a list of hashrefs, each of which may contain:

pkgnum, description, amount, unit_amount, quantity, pkgpart, _is_setup, and ext_description, which is an arrayref of detail lines to show below the package line.

_items_discounts_avail

Returns an array of line item hashrefs representing available term discounts for this invoice. This makes the same assumptions that apply to term discounts in general: that the package is billed monthly, at a flat rate, with no usage charges. A prorated first month will be handled, as will a setup fee if the discount is allowed to apply to setup fees.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 36:

'=item' outside of any '=over'