Leave other plugins' features to hooks

Refund emails and PDFs take the shop name and mail settings from
:qbo_mail_settings instead of reading redmine_qbo_reminders' settings; the
customer page's ticked boxes use generic data-ticked-field/data-ticked-params
instead of knowing redmine_qbo_calendar's Add appointment link; and Create
issues carries the params plugins name in :qbo_billing_issue_carry_params
instead of appointment_id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rickyandClaude Opus 5.5 committed 2026-11-21 07:37:57 -05:00
1 parent 0552e2f1a3
commit ae0ffc7c1c
10 files changed
+69 -39

No files matched your search

+4 -2
View File
@@ -162,7 +162,7 @@ Refunds for canceled orders and returned parts, following SOP-OPS-014, so they d
1. makes the restocking fee invoice, its line showing the math ("Restocking fee: 30% × $307.99 parts on E1068 = $92.40"), and pays it from the customer's credit, oldest first (unless QuickBooks already applied the credit to it on its own); 1. makes the restocking fee invoice, its line showing the math ("Restocking fee: 30% × $307.99 parts on E1068 = $92.40"), and pays it from the customer's credit, oldest first (unless QuickBooks already applied the credit to it on its own);
2. records the rest of the credit as a refund with the category **Accounts Receivable**, from the bank account in the settings, described "Refund for deposit on E1068": a **Check** for a check, an **Expense** for a card refund; 2. records the rest of the credit as a refund with the category **Accounts Receivable**, from the bank account in the settings, described "Refund for deposit on E1068": a **Check** for a check, an **Expense** for a card refund;
3. applies the customer's remaining credit to that check or expense, so the deposit, the fee invoice and the refund reconcile, and reads back the customer's balance (it should be $0.00). 3. applies the customer's remaining credit to that check or expense, so the deposit, the fee invoice and the refund reconcile, and reads back the customer's balance (it should be $0.00).
* As ticked on the page, it also marks the estimate **Rejected**, sets the order's work orders to the canceled status with the reason as a note, and emails the customer a summary (through redmine_qbo_reminders' mail settings when that plugin is set up, otherwise Redmine's). * As ticked on the page, it also marks the estimate **Rejected**, sets the order's work orders to the canceled status with the reason as a note, and emails the customer a summary (with the shop name and mail settings another plugin gives through `:qbo_mail_settings`, e.g. redmine_qbo_reminders', otherwise Redmine's).
* Each refund has its own page, listed on the customer page: what was refunded and how, with the fee invoice (opened in Redmine), a **PDF** of the refund (QuickBooks has no PDF of a check or an expense), the fee invoice's PDF, and **Email the customer** to send the summary again. If a QuickBooks step fails, the refund stops there and its page says which step and what was already done, to finish in QuickBooks. * Each refund has its own page, listed on the customer page: what was refunded and how, with the fee invoice (opened in Redmine), a **PDF** of the refund (QuickBooks has no PDF of a check or an expense), the fee invoice's PDF, and **Email the customer** to send the summary again. If a QuickBooks step fails, the refund stops there and its page says which step and what was already done, to finish in QuickBooks.
* It refunds all of the customer's remaining credit held as unapplied payments. Credit held as credit memos isn't refunded here. * It refunds all of the customer's remaining credit held as unapplied payments. Credit held as credit memos isn't refunded here.
@@ -277,7 +277,9 @@ Hook|:qbo_billing_issues_created, { estimate:, issues:, params: } | Called after
Hook|:qbo_billing_field_defaults, { customer:, issues: } | Return `{ field_id => value }` for a document's work orders: used when an invoice is made from an estimate, for the fields it leaves blank. New estimates and invoices start blank (redmine_qbo_vehicles: the work orders' VIN and highest mileage) Hook|:qbo_billing_field_defaults, { customer:, issues: } | Return `{ field_id => value }` for a document's work orders: used when an invoice is made from an estimate, for the fields it leaves blank. New estimates and invoices start blank (redmine_qbo_vehicles: the work orders' VIN and highest mileage)
Hook|:qbo_billing_field_options, { customer: } | Return `{ field_id => [{ value:, label: }, ...] }` to suggest in the editor's custom field boxes for a customer (redmine_qbo_vehicles: the customer's vehicles for the VIN box) Hook|:qbo_billing_field_options, { customer: } | Return `{ field_id => [{ value:, label: }, ...] }` to suggest in the editor's custom field boxes for a customer (redmine_qbo_vehicles: the customer's vehicles for the VIN box)
View|:view_qbo_estimate_form_bottom, { form:, document: } | Add your plugin's script to the estimate/invoice editor. It can use `window.qboEditor` (`field(id)`, `fieldNamed(/name/)`, `setFieldOptions(id, options)`) and listen for `qbo:customer-changed` and `qbo:imported` on the form (redmine_qbo_vehicles fills the VIN and mileage) View|:view_qbo_estimate_form_bottom, { form:, document: } | Add your plugin's script to the estimate/invoice editor. It can use `window.qboEditor` (`field(id)`, `fieldNamed(/name/)`, `setFieldOptions(id, options)`) and listen for `qbo:customer-changed` and `qbo:imported` on the form (redmine_qbo_vehicles fills the VIN and mileage)
View|checkboxes with `data-new-issue-param="issue[field]"` and `data-appointment-param="field"` on the customer page | Ticking one adds `issue[field]=value` to the New issue link and `field=value` to redmine_qbo_calendar's Add appointment link (`#appointment_link`), one per field (redmine_qbo's estimates: `estimate_id`, redmine_qbo_vehicles' vehicles: `vehicle_id`) View|checkboxes with `data-ticked-field="field"`, links with `data-ticked-params` on the customer page | Ticking a box adds its value to every link with `data-ticked-params`, named by that format: `issue[%s]` for the New issue link, `%s` for a plain param (e.g. redmine_qbo_calendar's Add appointment link). One box per field (redmine_qbo's estimates: `estimate_id`, redmine_qbo_vehicles' vehicles: `vehicle_id`)
Hook|:qbo_billing_issue_carry_params | Return names of request params the Create issues from estimate page keeps through its form (redmine_qbo_calendar: `appointment_id`)
Hook|:qbo_mail_settings | Return any of `shop_name`, `from`, `reply_to` and `delivery` (options for ActionMailer's `mail()`, e.g. an SMTP server) for customer emails such as refund summaries (redmine_qbo_reminders: its shop name and email settings). Blank ones fall back to Redmine's settings
View Hook|:view_qbo_estimate_contextual, { estimate_id:, customer_id:, custom_fields:, doc_number: } | Adds links to an estimate page's action area (e.g. redmine_qbo_calendar's Add appointment); `custom_fields` is `{ field_id => value }` View Hook|:view_qbo_estimate_contextual, { estimate_id:, customer_id:, custom_fields:, doc_number: } | Adds links to an estimate page's action area (e.g. redmine_qbo_calendar's Add appointment); `custom_fields` is `{ field_id => value }`
View Hook|:view_qbo_invoice_contextual, { invoice_id:, customer_id:, doc_number: } | Adds links to an invoice page's action area (e.g. redmine_qbo_labels' Print label) View Hook|:view_qbo_invoice_contextual, { invoice_id:, customer_id:, doc_number: } | Adds links to an invoice page's action area (e.g. redmine_qbo_labels' Print label)
+5 -5
View File
@@ -21,16 +21,16 @@ class QboRefundMailer < ActionMailer::Base
def refund_summary(refund, email) def refund_summary(refund, email)
@refund = refund @refund = refund
@customer = refund.customer @customer = refund.customer
reminders = defined?(RedmineQboReminders::Settings) ? RedmineQboReminders::Settings.current : nil settings = RedmineQboBilling.mail_settings
@shop_name = reminders&.[]('shop_name').to_s.presence || Setting.app_title @shop_name = settings[:shop_name].presence || Setting.app_title
delivery = reminders ? reminders.delivery_options : {} delivery = settings[:delivery] || {}
if delivery.empty? && !ActionMailer::Base.perform_deliveries if delivery.empty? && !ActionMailer::Base.perform_deliveries
raise DeliveryOff, I18n.t(:text_refund_email_off) raise DeliveryOff, I18n.t(:text_refund_email_off)
end end
options = { to: email, from: reminders&.from.presence || Setting.mail_from.to_s, options = { to: email, from: settings[:from].presence || Setting.mail_from.to_s,
subject: I18n.t(:text_refund_email_subject, shop: @shop_name, amount: RedmineQboBilling::RefundWriter.money(refund.refund_amount)) } subject: I18n.t(:text_refund_email_subject, shop: @shop_name, amount: RedmineQboBilling::RefundWriter.money(refund.refund_amount)) }
options[:reply_to] = reminders.reply_to if reminders&.reply_to options[:reply_to] = settings[:reply_to] if settings[:reply_to]
message = mail(options.merge(delivery)) do |format| message = mail(options.merge(delivery)) do |format|
format.text format.text
end end
@@ -1,40 +1,33 @@
<%# <%#
Adds what's ticked on the customer page to its links: "New issue" (#dynamic-new-issue-link in the contextual area) Adds what's ticked on the customer page to its links. A checkbox takes part with data-ticked-field="field"
and redmine_qbo_calendar's "Add appointment" (#appointment_link). A checkbox takes part with (one is ticked per field), e.g. this plugin's estimates (estimate_id) and other plugins' lists. A link takes
data-new-issue-param="issue[field]" (New issue) and data-appointment-param="field" (Add appointment); one is part with data-ticked-params, how each field is named in its URL: "issue[%s]" for New issue
ticked per field: this plugin's estimates (estimate_id), and other plugins' lists (e.g. redmine_qbo_vehicles' (#dynamic-new-issue-link), "%s" for a plain param. Other plugins' links on the page work the same way.
vehicle_id).
%> %>
<script> <script>
(function () { (function () {
var LINKS = [['dynamic-new-issue-link', 'data-new-issue-param'], ['appointment_link', 'data-appointment-param']]; var BOX = 'input[data-ticked-field]';
var ANY = 'input[data-new-issue-param], input[data-appointment-param]';
function boxes(attr, param) { function boxes(field) {
return Array.prototype.filter.call(document.querySelectorAll('input[' + attr + ']'), function (cb) { return Array.prototype.filter.call(document.querySelectorAll(BOX), function (cb) {
return !param || cb.getAttribute(attr) === param; return !field || cb.getAttribute('data-ticked-field') === field;
}); });
} }
// Boxes for the same field (the same estimate list, the same vehicle list) function fields() {
function sameField(box) { return boxes().map(function (cb) { return cb.getAttribute('data-ticked-field'); })
for (var i = 0; i < LINKS.length; i++) { .filter(function (field, i, all) { return all.indexOf(field) === i; });
var attr = LINKS[i][1], param = box.getAttribute(attr);
if (param) return boxes(attr, param);
}
return [box];
} }
function updateLinks() { function updateLinks() {
LINKS.forEach(function (pair) { Array.prototype.forEach.call(document.querySelectorAll('a[data-ticked-params]'), function (link) {
var link = document.getElementById(pair[0]);
if (!link) return;
// Cache the pristine base URL on first run // Cache the pristine base URL on first run
if (!link.dataset.baseUrl) link.dataset.baseUrl = link.getAttribute('href'); if (!link.dataset.baseUrl) link.dataset.baseUrl = link.getAttribute('href');
var url = new URL(link.dataset.baseUrl, window.location.origin); var url = new URL(link.dataset.baseUrl, window.location.origin);
boxes(pair[1]).forEach(function (cb) { var format = link.getAttribute('data-ticked-params');
var param = cb.getAttribute(pair[1]); fields().forEach(function (field) {
var ticked = boxes(pair[1], param).filter(function (b) { return b.checked; })[0]; var param = format.replace('%s', field);
var ticked = boxes(field).filter(function (b) { return b.checked; })[0];
if (ticked) { if (ticked) {
url.searchParams.set(param, ticked.value); url.searchParams.set(param, ticked.value);
} else { } else {
@@ -48,9 +41,9 @@
// One box per field: ticking one unticks the others for the same field // One box per field: ticking one unticks the others for the same field
document.addEventListener('change', function (event) { document.addEventListener('change', function (event) {
var box = event.target; var box = event.target;
if (!box.matches || !box.matches(ANY)) return; if (!box.matches || !box.matches(BOX)) return;
if (box.checked) { if (box.checked) {
sameField(box).forEach(function (cb) { if (cb !== box) cb.checked = false; }); boxes(box.getAttribute('data-ticked-field')).forEach(function (cb) { if (cb !== box) cb.checked = false; });
} }
updateLinks(); updateLinks();
}); });
+1 -1
View File
@@ -6,7 +6,7 @@
<div class="contextual qbo-under-title"> <div class="contextual qbo-under-title">
<%# New issue for this customer; picks up what's ticked on this page (an estimate, other plugins' items) %> <%# New issue for this customer; picks up what's ticked on this page (an estimate, other plugins' items) %>
<%= link_to sprite_icon('add', l(:label_new_issue)), new_issue_path(issue: { customer_id: @customer.id }), <%= link_to sprite_icon('add', l(:label_new_issue)), new_issue_path(issue: { customer_id: @customer.id }),
id: 'dynamic-new-issue-link', class: 'icon icon-add', target: :_blank %> id: 'dynamic-new-issue-link', class: 'icon icon-add', target: :_blank, data: { ticked_params: 'issue[%s]' } %>
<%# Plugins add their customer actions here (e.g. redmine_qbo_calendar's Add appointment) %> <%# Plugins add their customer actions here (e.g. redmine_qbo_calendar's Add appointment) %>
<%= call_hook :view_customers_show_contextual, { customer: @customer } %> <%= call_hook :view_customers_show_contextual, { customer: @customer } %>
<%# Estimates, invoices and payments are handled here, each shown to users with its permission; Open in <%# Estimates, invoices and payments are handled here, each shown to users with its permission; Open in
+2 -2
View File
@@ -5,8 +5,8 @@
<% estimates.sort.reverse.each do |estimate| %> <% estimates.sort.reverse.each do |estimate| %>
<%# One cell each (qbo_estimates/_status_styles lines them up in columns, so the icons line up) %> <%# One cell each (qbo_estimates/_status_styles lines them up in columns, so the icons line up) %>
<div class="row"> <div class="row">
<%# Ticking an estimate adds it to the customer page's New issue and Add appointment links (customers/_new_issue_link_script) %> <%# Ticking an estimate adds it to the customer page's links (customers/_new_issue_link_script) %>
<span class="qbo-list-check"><%= check_box_tag "estimate_ids[]", estimate.id, false, data: { new_issue_param: 'issue[estimate_id]', appointment_param: 'estimate_id' }, class: "estimate-checkbox" if local_assigns[:new_issue_checkboxes] %></span> <span class="qbo-list-check"><%= check_box_tag "estimate_ids[]", estimate.id, false, data: { ticked_field: 'estimate_id' }, class: "estimate-checkbox" if local_assigns[:new_issue_checkboxes] %></span>
<b class="qbo-list-number"><%= link_to "##{estimate.doc_number}", estimate_path(estimate), target: :_blank %></b> <b class="qbo-list-number"><%= link_to "##{estimate.doc_number}", estimate_path(estimate), target: :_blank %></b>
<span class="qbo-list-date"><%= estimate.txn_date %></span> <span class="qbo-list-date"><%= estimate.txn_date %></span>
<%# QuickBooks status, cached by the estimate sync (kept current by the webhook) %> <%# QuickBooks status, cached by the estimate sync (kept current by the webhook) %>
@@ -1,6 +1,6 @@
<% html_title l(:button_create_estimate_issues) %> <% html_title l(:button_create_estimate_issues) %>
<%# Extra params to carry through (e.g. appointment_id from redmine_qbo_calendar) %> <%# Params other plugins carry through the page (:qbo_billing_issue_carry_params, e.g. redmine_qbo_calendar's appointment) %>
<% carry = request.query_parameters.merge(request.request_parameters).slice('appointment_id') %> <% carry = request.query_parameters.merge(request.request_parameters).slice(*Redmine::Hook.call_hook(:qbo_billing_issue_carry_params, {}).flatten.compact.map(&:to_s)) %>
<div class="contextual"> <div class="contextual">
<%= link_to sprite_icon('angle-left', @return_label), @return_path, class: 'icon icon-angle-left' %> <%= link_to sprite_icon('angle-left', @return_label), @return_path, class: 'icon icon-angle-left' %>
+12
View File
@@ -30,6 +30,18 @@ module RedmineQboBilling
# Suggestions for the editor's custom field boxes for a customer, from plugins answering # Suggestions for the editor's custom field boxes for a customer, from plugins answering
# :qbo_billing_field_options, { customer: } => { field_id => [{ value:, label: }, ...] } # :qbo_billing_field_options, { customer: } => { field_id => [{ value:, label: }, ...] }
# (e.g. redmine_qbo_vehicles: the customer's vehicles for its VIN field). Returns { "2" => [...] }. # (e.g. redmine_qbo_vehicles: the customer's vehicles for its VIN field). Returns { "2" => [...] }.
# The shop's name and how customer emails (refund summaries) are sent, from other plugins (e.g.
# redmine_qbo_reminders: its shop name and SMTP server) through :qbo_mail_settings. Each returns any of
# shop_name:, from:, reply_to:, delivery: (options for ActionMailer's mail(), e.g. an SMTP server); blank
# ones fall back to Redmine's own settings.
def self.mail_settings
Redmine::Hook.call_hook(:qbo_mail_settings, {}).select { |result| result.is_a?(Hash) }
.reduce({}) { |merged, result| merged.merge(result.symbolize_keys.compact_blank) }
rescue StandardError => e
Rails.logger.warn "[RedmineQboBilling] Could not read mail settings from plugins: #{e.message}"
{}
end
def self.field_options(customer) def self.field_options(customer)
return {} unless customer return {} unless customer
+1 -2
View File
@@ -132,8 +132,7 @@ module RedmineQboBilling
end end
def shop_name def shop_name
reminders = defined?(RedmineQboReminders::Settings) ? RedmineQboReminders::Settings.current : nil RedmineQboBilling.mail_settings[:shop_name].presence || Setting.app_title
reminders&.[]('shop_name').to_s.presence || Setting.app_title
rescue StandardError rescue StandardError
Setting.app_title Setting.app_title
end end
@@ -62,6 +62,13 @@ class CustomersControllerTest < Redmine::IntegrationTest
assert_redirected_to '/customers/9101' assert_redirected_to '/customers/9101'
end end
def test_new_issue_picks_up_ticked_boxes
grant(:view_customers, :add_issues)
get '/customers/9101'
assert_select 'a#dynamic-new-issue-link[data-ticked-params=?]', 'issue[%s]'
assert_includes response.body, "a[data-ticked-params]"
end
def test_show_lists_open_and_closed_issues def test_show_lists_open_and_closed_issues
grant(:view_customers) grant(:view_customers)
get '/customers/9101' get '/customers/9101'
+17
View File
@@ -103,6 +103,23 @@ class QboHelpersTest < ActiveSupport::TestCase
end end
end end
def test_refund_email_with_another_plugins_mail_settings
RedmineQboBilling.stubs(:mail_settings).returns(shop_name: 'Example Garage', from: 'Example Garage <shop@example.com>',
reply_to: 'office@example.com')
mail = QboRefundMailer.refund_summary(refund, 'jane@example.com')
assert_equal ['shop@example.com'], mail.from
assert_equal ['office@example.com'], mail.reply_to
assert_match 'Example Garage', mail.subject
end
def test_mail_settings_from_plugins
Redmine::Hook.stubs(:call_hook).with(:qbo_mail_settings, {})
.returns([{ shop_name: '', from: 'a@example.com' }, nil, { 'shop_name' => 'Example Garage' }])
assert_equal({ from: 'a@example.com', shop_name: 'Example Garage' }, RedmineQboBilling.mail_settings)
Redmine::Hook.stubs(:call_hook).with(:qbo_mail_settings, {}).raises(StandardError, 'boom')
assert_equal({}, RedmineQboBilling.mail_settings)
end
def test_refund_email_when_delivery_is_off def test_refund_email_when_delivery_is_off
ActionMailer::Base.stubs(:perform_deliveries).returns(false) ActionMailer::Base.stubs(:perform_deliveries).returns(false)
assert_raises(QboRefundMailer::DeliveryOff) { QboRefundMailer.refund_summary(refund, 'jane@example.com').message } assert_raises(QboRefundMailer::DeliveryOff) { QboRefundMailer.refund_summary(refund, 'jane@example.com').message }