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

From Freeside
Jump to: navigation, search
(Edit via perl MediaWiki framework (1.13))
 
m (Edit via perl MediaWiki framework (1.13))
 
(One intermediate revision by the same user not shown)
Line 30: Line 30:
 
:See print_ps and print_pdf for methods that return PostScript and PDF output.
 
:See print_ps and print_pdf for methods that return PostScript and PDF output.
  
:Non optional options include format - latex, html, template
+
:Required options
 +
:; format
 +
::The '''format''' option is required and should be set to html, latex (print and PDF) or template (plaintext).
  
:Optional options include
+
:Additional options
 
+
:; notice_name
:template - a value used as a suffix for a configuration template. Please don't use this.
+
::Overrides "Invoice" as the name of the sent document.
 
+
:; today
: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 [[perlfunc#time|"time" in perlfunc]]. Also see [[Freeside:3:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:3:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
+
::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 [[perlfunc#time|"time" in perlfunc]]. Also see [[Freeside:3:Documentation:Developer/Time/Local|Time::Local]] and [[Freeside:3:Documentation:Developer/Date/Parse|Date::Parse]] for conversion functions.
 
+
:; logo_file
:cid -
+
::Logo file (path to temporary EPS file on the local filesystem)
 
+
:; cid
:unsquelch_cdr - overrides any per customer cdr squelching when true
+
::CID for inline (emailed) images (logo)
 
+
:; locale
:notice_name - overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
+
::Override customer's locale
 
+
:; unsquelch_cdr
:locale - override customer's locale
+
::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 ] ]
 
; print_ps HASHREF | [ TIME [ , TEMPLATE ] ]
 
:Returns an postscript invoice, as a scalar.
 
:Returns an postscript invoice, as a scalar.
Line 73: Line 91:
  
 
:''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.
 
:''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
+
; 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.
 
: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
 
; _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.
 
: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
 +
:; subject
 +
::email subject, optional
 +
:; notice_name
 +
::notice name instead of "Invoice", optional
 +
 +
:Returns an argument list to be passed to [[Freeside:3:Documentation:Developer/FS/Misc/send email|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
 
; _items_sections OPTIONS
 
:Generate section information for all items appearing on this invoice. This will only be called for multi-section invoices.
 
:Generate section information for all items appearing on this invoice. This will only be called for multi-section invoices.
Line 110: Line 154:
 
:$self->_items_cust_bill_pkg([ $self->cust_bill_pkg ])
 
:$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).
+
: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
 
; _items_cust_bill_pkg CUST_BILL_PKGS OPTIONS
 
:Takes an arrayref of [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]] objects, and returns a list of hashrefs describing the line items they generate on the invoice.
 
:Takes an arrayref of [[Freeside:3:Documentation:Developer/FS/cust bill pkg|FS::cust_bill_pkg]] objects, and returns a list of hashrefs describing the line items they generate on the invoice.
Line 125: Line 173:
  
 
:multisection: a flag indicating that this is a multisection invoice, which does something complicated.
 
: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:
 
:Returns a list of hashrefs, each of which may contain:
Line 135: Line 185:
 
Hey! '''The above document had some coding errors, which are explained below:'''
 
Hey! '''The above document had some coding errors, which are explained below:'''
  
; Around line 35:
+
; Around line 36:
 
:'=item' outside of any '=over'
 
:'=item' outside of any '=over'

Latest revision as of 08:26, 2 March 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
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'