Difference between revisions of "Freeside:4:Documentation:Developer/FS/msg template"

Latest revision as of 07:25, 18 November 2015

NAME

FS::msg_template - Object methods for msg_template records

SYNOPSIS

 use FS::msg_template;

 $record = new FS::msg_template \%hash;
 $record = new FS::msg_template { 'column' => 'value' };

 $error = $record->insert;

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;

NOTE

This uses a table-per-subclass ORM strategy, which is a somewhat cleaner version of what we do elsewhere with _option tables. We could easily extract that functionality into a base class, or even into FS::Record itself.

DESCRIPTION

An FS::msg_template object represents a customer message template. FS::msg_template inherits from FS::Record. The following fields are currently supported:

msgnum - primary key; msgname - Name of the template. This will appear in the user interface; if it needs to be localized for some users, add it to the message catalog.; msgclass - The FS::msg_template subclass that this should belong to. Defaults to 'email'.; agentnum - Agent associated with this template. Can be NULL for a global template.; mime_type - MIME type. Defaults to text/html.; from_addr - Source email address.; bcc_addr - Bcc all mail to this address.; disabled - disabled (NULL for not-disabled and selectable, 'D' for a draft of a one-time message, 'C' for a completed one-time message, 'Y' for a normal template disabled by user action).

METHODS

new HASHREF

Creates a new template. To add the template to the database, see "insert".

Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the hash method.

insert [ CONTENT ]

Adds this record to the database. If there is an error, returns the error, otherwise returns false.

delete

Delete this record from the database.

replace [ OLD_RECORD ]

Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.

check

Checks all fields to make sure this is a valid template. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.

prepare OPTION => VALUE

Fills in the template and returns an FS::cust_msg object, containing the message to be sent. This method must be provided by the subclass.

Options are passed as a list of name/value pairs:

cust_main

Customer object (required).

object

Additional context object (currently, can be a cust_main, cust_pkg, cust_bill, cust_pay, cust_pay_pending, or svc_(acct, phone, broadband, domain) ). If the object is a svc_*, its cust_pkg will be fetched and used for substitution.

As a special case, this may be an arrayref of two objects. Both objects will be available for substitution, with their field names prefixed with 'new_' and 'old_' respectively. This is used in the rt_ticket export when exporting "replace" events.

from_config

Configuration option to use as the source address, based on the customer's agentnum. If unspecified (or the named option is empty), 'invoice_from' will be used.

The from_addr field in the template takes precedence over this.

to

Destination address. The default is to use the customer's invoicing_list addresses. Multiple addresses may be comma-separated.

substitutions

A hash reference of additional substitutions

prepare_substitutions OPTION => VALUE ...

Takes the same arguments as "prepare", and returns a hashref of the substitution variables.

send OPTION => VALUE ...

Creates a message with "prepare" (taking all the same options) and sends it.

render OPTION => VALUE ...

Fills in the template and renders it to a PDF document. Returns the name of the PDF file.

Options are as for 'prepare', but 'from' and 'to' are meaningless.

print OPTIONS

Render a PDF and send it to the printer. OPTIONS are as for 'render'.

content LOCALE

Stub, returns nothing.

agent

Returns the FS::agent object for this template.

BUGS

SEE ALSO

FS::Record, schema.html from the base documentation.