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

Revision as of 13:40, 27 June 2014 (view source) Jeremyd (talk | contribs) (Edit via perl MediaWiki framework (1.13)) Newer edit →

(No difference)

---

Revision as of 13:40, 27 June 2014

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.

Non optional options include format - latex, html, template

Optional options include

template - a value used as a suffix for a configuration template. Please don't use this.

time - a 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.

cid -

unsquelch_cdr - overrides any per customer cdr squelching when true

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

locale - override customer's locale

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.

_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.

_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 ])

The only OPTIONS accepted is 'section', which may point to a hashref with a key named 'condensed', which may have a true value. If it does, this method tries 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.

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 35:

'=item' outside of any '=over'