198 lines
10 KiB
PHP
198 lines
10 KiB
PHP
<?php
|
|
/*
|
|
* Example for the optional company email-template hook.
|
|
* Copy to company/<company-id>/reporting/email_template.php.
|
|
* Requires the pdf_report.inc email-template hook patch; this is not a
|
|
* standard feature of unpatched FrontAccounting 2.4.20.
|
|
*
|
|
* The file must return a callable. It is loaded separately for each contact.
|
|
* Return array() to keep the standard email. Optional return keys:
|
|
* body - introductory text, ending with two newlines
|
|
* sender - signature details (without a closing greeting)
|
|
* FrontAccounting adds payment links, "Kindest regards", and the signature.
|
|
* Recipients, subject and attachments are handled by FrontAccounting.
|
|
* Do not echo, send mail, or modify database records here.
|
|
*
|
|
* CALLBACK FIELD REFERENCE -- FrontAccounting 2.4.20 + this port's hook
|
|
* ==================================================================
|
|
* Use $contact['email'], $formData['reference'], etc.; array keys are NOT
|
|
* separate variables. Names are case-sensitive (including DebtorName and
|
|
* StockItemName). Use ?? or isset(): fields can be absent, null or empty.
|
|
* Database numbers/flags can be strings. Dates normally use YYYY-MM-DD;
|
|
* format them for display rather than assuming they are localized.
|
|
*
|
|
* These are the standard source fields, not a guarantee that every report
|
|
* supplies every key. Custom reports, company headers and extensions can
|
|
* add/replace fields. In particular, $company is an extensible preference
|
|
* map, so no fixed list can describe every installation.
|
|
*
|
|
* $contact -- the current email recipient (one callback per contact)
|
|
* ----------------------------------------------------------------
|
|
* Standard crm_persons fields:
|
|
* id Contact/person record ID (not an invoice/customer ID).
|
|
* ref Contact reference/short name.
|
|
* name First contact name field.
|
|
* name2 Second contact name field; may be empty.
|
|
* address Contact postal address.
|
|
* phone Primary contact phone number.
|
|
* phone2 Alternative contact phone number.
|
|
* fax Contact fax number.
|
|
* email Recipient email address; changing this argument does not
|
|
* change the address used by the renderer to send the mail.
|
|
* lang Contact language code.
|
|
* notes Internal contact notes; do not include by default.
|
|
* inactive Contact inactivity flag.
|
|
* Depending on which standard contact query the report uses, also:
|
|
* type Relationship class, e.g. customer, cust_branch, supplier.
|
|
* action Contact purpose, e.g. invoice, order, delivery, general.
|
|
* ext_type Combined type.action (branch contact queries).
|
|
* contact_id Relationship record ID (get_crm_persons queries).
|
|
* description, system
|
|
* Contact-category description and system-category flag
|
|
* (get_crm_persons joins crm_categories with crm_persons).
|
|
* Numeric SQL-result indexes may also exist; use named keys instead.
|
|
*
|
|
* $formData -- document/header data, NOT the complete transaction row
|
|
* -----------------------------------------------------------------
|
|
* Prepared by SetCommonData and the standard doctext.inc header:
|
|
* doctype Document type; sales invoice = 10. This is distinct
|
|
* from the source transaction's type field below.
|
|
* document_name Localized label, e.g. "Invoice No.".
|
|
* document_number Display number/reference selected by report settings.
|
|
* document_date Document date selected by the header.
|
|
* document_amount Initially ov_amount + ov_freight + ov_gst. Do not
|
|
* assume a universally valid payable balance: headers
|
|
* can overwrite it (stock sales-order header does so).
|
|
* recipient_name Name selected for the document's primary address.
|
|
* rep_lang Report language, taken from the first supplied contact;
|
|
* may differ from this recipient's $contact['lang'].
|
|
* domicile Company domicile, added for invoices/statements.
|
|
*
|
|
* All source-row keys copied by SetCommonData, only when present/non-null:
|
|
* Identifiers/references:
|
|
* order_no, reference, id, trans_no, type, order_, wo_ref, debtor_ref,
|
|
* requisition_no
|
|
* Dates:
|
|
* ord_date, date_, tran_date, delivery_date, due_date, required_by
|
|
* Party/location/item data:
|
|
* name, location_name, delivery_address, supp_name, address,
|
|
* DebtorName, supp_account_no, tax_id, contact, StockItemName
|
|
* Amounts/settings:
|
|
* ov_freight, ov_gst, ov_amount, prepaid, payment_terms, curr_code,
|
|
* units_issued
|
|
* payment_terms is an ID, not the payment-terms description.
|
|
* prepaid may be converted to "partial" or "final" by the invoice header.
|
|
*
|
|
* Additional keys copied from the other SetCommonData arguments:
|
|
* Customer branch: br_address, br_name, salesman, disable_branch
|
|
* Sales order: deliver_to, delivery_address, customer_ref
|
|
* Bank account: bank_name, bank_account_number, payment_service
|
|
* salesman is an ID, not the salesperson's name. A bank account or
|
|
* payment service is only present when the report supplies that data.
|
|
* Later arguments can overwrite an earlier key such as delivery_address.
|
|
*
|
|
* $company -- current company's get_company_prefs() / sys_prefs values
|
|
* -----------------------------------------------------------------
|
|
* Common fields for customer-facing text:
|
|
* coy_name Company name.
|
|
* postal_address Company postal address (may contain line breaks).
|
|
* phone, fax, email
|
|
* Company contact details.
|
|
* coy_no Company registration number.
|
|
* gst_no Company tax/VAT registration number.
|
|
* domicile Registered domicile text.
|
|
* coy_logo Logo filename, not an image attachment or URL.
|
|
* curr_default Company base currency code; use formData.curr_code for
|
|
* the document currency when available.
|
|
* legal_text Configured legal/footer text.
|
|
* bcc_email Internal BCC setting; not customer-facing text.
|
|
*
|
|
* Other preference keys seeded by the stock 2.4.20 en_US-new.sql database
|
|
* (settings/account codes, not automatically formatted descriptions):
|
|
* tax_prd, tax_last, use_dimension, f_year, shortname_name_in_list,
|
|
* no_item_list, no_customer_list, no_supplier_list, base_sales, time_zone,
|
|
* add_pct, round_to, login_tout, past_due_days, profit_loss_year_act,
|
|
* retained_earnings_act, bank_charge_act, exchange_diff_act, tax_algorithm,
|
|
* default_credit_limit, accumulate_shipping, freight_act, debtors_act,
|
|
* default_sales_act, default_sales_discount_act, default_prompt_payment_act,
|
|
* default_delivery_required, default_receival_required, default_quote_valid_days,
|
|
* default_dim_required, pyt_discount_act, creditors_act, po_over_receive,
|
|
* po_over_charge, allow_negative_stock, default_inventory_act, default_cogs_act,
|
|
* default_adj_act, default_inv_sales_act, default_wip_act,
|
|
* default_workorder_required, version_id, auto_curr_reval, grn_clearing_act,
|
|
* deferred_income_act, gl_closing_date, alternative_tax_include_on_docs,
|
|
* no_zero_lines_amount, show_po_item_codes, accounts_alpha, loc_notification,
|
|
* print_invoice_no, allow_negative_prices, print_item_images_on_quote,
|
|
* suppress_tax_rates, company_logo_report, barcodes_on_stock,
|
|
* print_dialog_direct, ref_no_auto_increase, default_loss_on_asset_disposal_act,
|
|
* depreciation_period, use_manufacturing, dim_on_recurrent_invoice,
|
|
* long_description_invoice, max_days_in_docs, use_fixed_assets,
|
|
* company_logo_on_views
|
|
* An upgraded database can have additional preferences, and custom charts
|
|
* of accounts can seed different values. Use ?? for optional preferences.
|
|
*
|
|
* $user -- string: display name of the logged-in user generating the report.
|
|
* It is not a user object, username, email address or database connection.
|
|
*
|
|
* Not supplied as callback arguments:
|
|
* PDF bytes/path, invoice line items, attachments, email subject, mail
|
|
* object, full customer record, passwords or database connection details.
|
|
* $this is unavailable in this static callback. The renderer's local
|
|
* variables do not become callback variables automatically.
|
|
*
|
|
* Variables created by this example below (not additional FA input fields):
|
|
* $name, $reference, $greeting, $document, $body, $address, $addressLines,
|
|
* $signature. The nested array_filter callback uses its own $line argument.
|
|
*
|
|
* To inspect a custom installation, examine array_keys($contact),
|
|
* array_keys($formData) and array_keys($company) in a private test harness.
|
|
* Do not echo/debug-dump them into a customer email or a public web page.
|
|
*
|
|
* Source references in the stock 2.4.20 archive:
|
|
* reporting/includes/pdf_report.inc: constructor, SetCommonData, End
|
|
* reporting/includes/doctext.inc
|
|
* sales/includes/db/branches_db.inc: get_branch_contacts
|
|
* includes/db/crm_contacts_db.inc: get_crm_persons
|
|
* admin/db/company_db.inc: get_company_prefs
|
|
* sql/en_US-new.sql: crm_persons, crm_categories, sys_prefs
|
|
*/
|
|
return static function ($contact, $formData, $company, $user) {
|
|
// FrontAccounting transaction type 10 is a sales invoice.
|
|
// Leave other document types unchanged.
|
|
if (($formData['doctype'] ?? null) != 10) {
|
|
return array();
|
|
}
|
|
|
|
$name = trim(($contact['name'] ?? '') . ' ' . ($contact['name2'] ?? ''));
|
|
|
|
$reference = (string) ($formData['reference'] ?? $formData['document_number'] ?? '');
|
|
|
|
$greeting = $name !== '' ? 'Hello ' . $name . ',' : 'Hello,';
|
|
|
|
$document = $reference !== '' ? 'invoice ' . $reference : 'your invoice';
|
|
|
|
// Replace these paragraphs with your preferred wording.
|
|
$body = $greeting . "\n\n";
|
|
$body .= "Thank you for your business.\n\n";
|
|
$body .= 'Please find attached ' . $document . " in PDF format.\n\n";
|
|
$body .= "If you have any questions, please reply to this email.\n\n";
|
|
|
|
// Use this installation's own settings, with one address line per line.
|
|
// No organization names, addresses or contact details are embedded here.
|
|
$address = str_replace(array("\r\n", "\r"), "\n", $company['postal_address'] ?? '');
|
|
|
|
$addressLines = array_filter(array_map('trim', explode("\n", $address)),
|
|
static function ($line) { return $line !== ''; });
|
|
|
|
$signature = array_merge(
|
|
array($user, $company['coy_name'] ?? ''),
|
|
array_values($addressLines),
|
|
array($company['email'] ?? '', $company['phone'] ?? '')
|
|
);
|
|
|
|
$signature = array_filter(array_map('trim', $signature),
|
|
static function ($line) { return $line !== ''; });
|
|
|
|
return array('body' => $body, 'sender' => implode("\n", $signature));
|
|
};
|