Print label in the sidebar, filled in from the page

A Labels section in the sidebar of every page: Print label fills the
label in from the page's customer (their name), estimate, invoice,
appointment (its customer and estimate) or work order, or opens a blank
label anywhere else. When there's a customer, the PO number field offers
their latest estimates, invoices and open work orders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rickyandClaude Opus 5.5 committed 2026-11-16 11:51:53 -05:00
1 parent 3e29f14f76
commit 98a9bcc1bf
11 files changed
+239 -18

No files matched your search

+3 -2
View File
@@ -9,8 +9,8 @@ Prints part labels on a Brother QL label printer from Redmine: the customer's la
└──────────────────────┘
```
* **Where**: **Print label** in the top-right actions of an issue, an estimate or an invoice ([redmine_qbo](https://github.com/rickbarrette/redmine_qbo)).
* **What**: the customer's last name (their family name in QuickBooks; a business's whole name) and the PO number: **E** + estimate number, **I** + invoice number, **W** + work order (issue) number. Both can be changed before printing, with a preview of the label as it will print, and up to 10 copies.
* **Where**: **Print label** in the top-right actions of an issue, an estimate or an invoice ([redmine_qbo](https://github.com/rickbarrette/redmine_qbo)), and in the sidebar's **Labels** section on every page. The sidebar's fills the label in from the page: a customer (their name), an estimate, an invoice, an appointment ([redmine_qbo_calendar](https://github.com/rickbarrette/redmine_qbo_calendar): its customer and estimate) or a work order; anywhere else it's a blank label to type.
* **What**: the customer's last name (their family name in QuickBooks; a business's whole name) and the PO number: **E** + estimate number, **I** + invoice number, **W** + work order (issue) number. When there's a customer, the PO number field offers their latest estimates, invoices and open work orders to pick from. Both lines can be changed before printing, with a preview of the label as it will print, and up to 10 copies.
* **Size**: labels run along a 62mm (2.4in) continuous roll (e.g. DK-2205) and are only as long as their text needs, up to 4in (both lengths can be changed). Each line gets the biggest letters that fit; a long name gets smaller letters, and the PO number stays big.
* **From anywhere**: Redmine never talks to the printer. A small **print agent** on the printer's network ([redmine_qbo_label_agent](https://github.com/rickbarrette/redmine_qbo_label_agent)) asks Redmine for labels every 2 seconds and prints them, so labels print from a phone or from home, without knowing the printer's address. The agent finds the printer on its network by itself.
@@ -66,6 +66,7 @@ Hook|Context|Use
---|---|---
`:view_qbo_estimate_contextual`, `:view_qbo_invoice_contextual` (redmine_qbo)|estimate/invoice id|**Print label** on estimates and invoices
`:view_issues_show_details_bottom`|issue|**Print label** on issues (moved into the issue's actions by script, as Redmine has no hook there)
`:view_layouts_base_sidebar`|controller|The sidebar's **Labels** section, filled in from the page's customer, estimate, invoice, appointment or work order
## Tests
+3 -2
View File
@@ -8,7 +8,8 @@
#
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
# The Print label dialog: opened from an issue, estimate or invoice (new), sends the label to a printer's
# The Print label dialog: opened from an issue, estimate, invoice, customer or appointment, or blank from the
# sidebar (new), sends the label to a printer's
# queue (create), and follows it until it's printed (show, polled by the dialog). The dialog asks for show's
# JSON with an Accept header, not a .json URL: Redmine treats .json as the REST API, without the session.
class LabelJobsController < ApplicationController
@@ -27,7 +28,7 @@ class LabelJobsController < ApplicationController
@copies = params[:copies].to_i.clamp(1, LabelJob::MAX_COPIES)
printer = @printers.find { |p| p.id == params[:printer_id].to_i } || @printers.first
@job = LabelJob.new(label_printer: printer, user: User.current, lines: @lines, copies: @copies,
source_type: @source.type, source_id: @source.id.to_s)
source_type: @source.type, source_id: @source.id&.to_s)
@job.save if printer
respond_to { |format| format.js }
end
+8
View File
@@ -0,0 +1,8 @@
<%# The sidebar's Labels section (every page): Print label for what the page shows, or a blank label %>
<h3><%= l(:label_qbo_labels_sidebar) %></h3>
<p class="qbo-label-sidebar">
<%= link_to sprite_icon('qbo-label-print', l(:button_qbo_labels_print), plugin: 'redmine_qbo_labels'),
new_label_job_path({ source_type: source_type, source_id: source_id }.compact),
remote: true, class: 'icon icon-qbo-label-print' %>
<% if title %><br><span class="qbo-label-muted"><%= l(:text_qbo_labels_sidebar_for, title: title) %></span><% end %>
</p>
+11 -1
View File
@@ -21,6 +21,7 @@
<div class="qbo-label-preview-wrap">
<canvas class="qbo-label-preview" width="1" height="1" aria-label="<%= l(:label_qbo_labels_preview) %>"></canvas>
<div class="qbo-label-size"></div>
<% if @source.title %><div class="qbo-label-for"><%= @source.title %></div><% end %>
</div>
<div class="tabular">
@@ -31,8 +32,17 @@
</p>
<p>
<label for="qbo_label_line_1"><%= l(:field_qbo_labels_po_number) %></label>
<% suggestions = @source.po_suggestions %>
<%= text_field_tag 'lines[]', @lines[1], id: 'qbo_label_line_1', class: 'qbo-label-line',
maxlength: LabelJob::MAX_LINE_LENGTH, autocomplete: 'off' %>
maxlength: LabelJob::MAX_LINE_LENGTH, autocomplete: 'off',
list: ('qbo_label_po_numbers' if suggestions.any?),
placeholder: ('E1234, I1234, W1234' if @lines[1].blank?) %>
<% if suggestions.any? %>
<datalist id="qbo_label_po_numbers">
<% suggestions.each do |number, description| %><option value="<%= number %>"><%= description %></option><% end %>
</datalist>
<em class="info"><%= l(:text_qbo_labels_po_suggestions) %></em>
<% end %>
</p>
<p>
<label for="qbo_label_copies"><%= l(:field_qbo_labels_copies) %></label>
+8
View File
@@ -86,6 +86,14 @@
to { transform: rotate(360deg); }
}
#qbo-label-dialog .qbo-label-for {
margin-top: .2em;
font-weight: bold;
}
/* The sidebar's Labels section */
#sidebar .qbo-label-sidebar .qbo-label-muted { color: #888; font-size: .9em; }
/* Administration » Label printers */
table.label-printers .status-online { color: #1a7f37; font-weight: bold; }
table.label-printers .status-offline { color: #c22; }
+5
View File
@@ -28,6 +28,9 @@ en:
label_qbo_labels_source_issue: "Work order"
label_qbo_labels_source_estimate: "Estimate"
label_qbo_labels_source_invoice: "Invoice"
label_qbo_labels_source_customer: "Customer"
label_qbo_labels_source_appointment: "Appointment"
label_qbo_labels_sidebar: "Labels"
label_qbo_labels_status_queued: "Waiting for the printer"
label_qbo_labels_status_printing: "Printing"
label_qbo_labels_status_printed: "Printed"
@@ -54,6 +57,8 @@ en:
button_qbo_labels_new_token: "New token"
text_qbo_labels_printing: "Printing…"
text_qbo_labels_sidebar_for: "for %{title}"
text_qbo_labels_po_suggestions: "Pick from the customer's estimates, invoices and open work orders, or type one"
text_qbo_labels_waiting: "Sent, waiting for the printer…"
text_qbo_labels_offline: "The printer's agent is offline. The label will print if it comes back within a few minutes…"
text_qbo_labels_lost_contact: "Lost contact with Redmine. Check the printer before printing again."
@@ -10,8 +10,16 @@
module RedmineQboLabels
module Hooks
# "Print label" in the top-right actions of issues, estimates and invoices
# "Print label" in the top-right actions of issues, estimates and invoices, and in the sidebar of every page
class ViewHookListener < Redmine::Hook::ViewListener
# Pages the sidebar's Print label fills the label from: [controller, action] => how to find the record
SIDEBAR_SOURCES = {
%w[issues show] => ['issue', ->(c) { c.instance_variable_get(:@issue) }],
%w[qbo_estimates edit] => ['estimate', ->(c) { c.instance_variable_get(:@form) }],
%w[qbo_invoices edit] => ['invoice', ->(c) { c.instance_variable_get(:@form) }],
%w[customers show] => ['customer', ->(c) { c.instance_variable_get(:@customer) }],
%w[customer_appointments show] => ['appointment', ->(c) { c.instance_variable_get(:@appointment) }]
}.freeze
# The print dialog's script and styles
def view_layouts_base_html_head(context = {})
@@ -39,8 +47,37 @@ module RedmineQboLabels
context[:hook_caller].render(partial: 'label_hooks/issue_print_link', locals: { issue: issue })
end
# The sidebar's Labels section: Print label for what the page shows (a customer, estimate, invoice,
# appointment or work order), or a blank label anywhere else
def view_layouts_base_sidebar(context = {})
return '' unless RedmineQboLabels.printing_available?
source_type, record = sidebar_source(context[:controller])
context[:hook_caller].render(partial: 'label_hooks/sidebar',
locals: { source_type: source_type, source_id: record&.id,
title: sidebar_title(source_type, record) })
end
private
def sidebar_source(controller)
return [nil, nil] unless controller
type, finder = SIDEBAR_SOURCES[[controller.controller_name, controller.action_name]]
record = finder&.call(controller)
record&.id.present? ? [type, record] : [nil, nil]
end
# What the page shows, from what the page already loaded (no QuickBooks lookups on every page)
def sidebar_title(source_type, record)
case source_type
when 'issue' then "#{l(:label_qbo_labels_source_issue)} ##{record.id}"
when 'estimate', 'invoice' then "#{l("label_qbo_labels_source_#{source_type}")} ##{record.doc_number}"
when 'customer' then record.name
when 'appointment' then record.try(:subject).presence || "#{l(:label_qbo_labels_source_appointment)} ##{record.id}"
end
end
def print_link(context, source_type, source_id)
return '' if source_id.blank? || !RedmineQboLabels.printing_available?
+82 -12
View File
@@ -9,51 +9,87 @@
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
module RedmineQboLabels
# What goes on a part label for an issue, estimate or invoice: the customer's last name and the PO number
# parts are ordered with (Sales SOP): E + estimate number, I + invoice number, W + work order (issue) number
# What goes on a part label: the customer's last name and the PO number parts are ordered with (Sales SOP):
# E + estimate number, I + invoice number, W + work order (issue) number.
#
# From an issue, estimate or invoice, both lines are filled in; from a customer, their name (with their
# estimates, invoices and open work orders offered as PO numbers); from an appointment (redmine_qbo_calendar),
# its customer and its estimate. A blank label (no type) is for anything else.
class LabelSource
TYPES = %w[issue estimate invoice].freeze
TYPES = %w[issue estimate invoice customer appointment].freeze
PREFIXES = { 'issue' => 'W', 'estimate' => 'E', 'invoice' => 'I' }.freeze
NAME_SUFFIXES = /\A(jr|sr|ii|iii|iv|v|esq)\.?\z/i
# PO numbers offered in the print dialog, of each kind
SUGGESTIONS = 8
attr_reader :type, :record
# The issue, estimate or invoice the current user may see, or nil
# The record of that type the current user may see (as a LabelSource), or nil. No type: a blank label.
def self.find(type, id)
type = type.to_s
return blank if type.empty?
return nil unless TYPES.include?(type)
record = case type
when 'issue' then Issue.visible.find_by(id: id)
when 'estimate' then Estimate.find_by(id: id) if billing_visible?(:write_estimates)
when 'invoice' then Invoice.find_by(id: id) if billing_visible?(:write_invoices)
when 'customer' then Customer.find_by(id: id) if customers_visible?
when 'appointment' then find_appointment(id)
end
record && new(type, record)
end
def self.blank
new(nil, nil)
end
def self.find_appointment(id)
return nil unless defined?(CustomerAppointment) &&
User.current.allowed_to?(:view_customer_appointments, nil, global: true)
CustomerAppointment.find_by(id: id)
end
private_class_method :find_appointment
# Estimates and invoices are seen by those who view customers or write them (redmine_qbo's permissions)
def self.billing_visible?(write_permission, user = User.current)
[:view_customers, write_permission].any? { |permission| user.allowed_to?(permission, nil, global: true) }
end
private_class_method :billing_visible?
def self.customers_visible?(user = User.current)
user.allowed_to?(:view_customers, nil, global: true)
end
private_class_method :customers_visible?
def initialize(type, record)
@type = type
@record = record
end
def blank?
record.nil?
end
def id
record.id
record&.id
end
def customer
return nil if blank?
return record if type == 'customer'
record.respond_to?(:customer) ? record.customer : nil
end
# E1234, I1234 or W1234
# E1234, I1234 or W1234 (an appointment's is its estimate's); blank for a customer or a blank label
def po_number
number = type == 'issue' ? record.id : record.doc_number
"#{PREFIXES[type]}#{number}"
case type
when 'issue' then "W#{record.id}"
when 'estimate', 'invoice' then "#{PREFIXES[type]}#{record.doc_number}"
when 'appointment' then record.estimate ? "E#{record.estimate.doc_number}" : ''
else ''
end
end
def last_name
@@ -65,10 +101,38 @@ module RedmineQboLabels
[last_name, po_number]
end
# Shown in the job list: "Estimate #1234"
# The customer's estimates, invoices and open work orders the user may see, newest first, as
# [[po_number, description]], offered for the PO number in the print dialog
def po_suggestions
customer = self.customer
return [] unless customer
suggestions = []
if self.class.billing_visible?(:write_estimates)
customer.estimates.where.not(doc_number: [nil, '']).order(txn_date: :desc).limit(SUGGESTIONS).each do |estimate|
suggestions << ["E#{estimate.doc_number}", describe(:label_qbo_labels_source_estimate, estimate.txn_date)]
end
end
if self.class.billing_visible?(:write_invoices)
customer.invoices.where.not(doc_number: [nil, '']).order(txn_date: :desc).limit(SUGGESTIONS).each do |invoice|
suggestions << ["I#{invoice.doc_number}", describe(:label_qbo_labels_source_invoice, invoice.txn_date)]
end
end
Issue.visible.open.where(customer_id: customer.id).order(id: :desc).limit(SUGGESTIONS).each do |issue|
suggestions << ["W#{issue.id}", issue.subject.to_s.truncate(50)]
end
suggestions.uniq(&:first)
end
# What it's for, e.g. "Estimate #1234", "Customer Jane Smith"; nil for a blank label
def title
number = type == 'issue' ? record.id : record.doc_number
"#{I18n.t("label_qbo_labels_source_#{type}")} ##{number}"
case type
when nil then nil
when 'issue' then "#{I18n.t(:label_qbo_labels_source_issue)} ##{record.id}"
when 'estimate', 'invoice' then "#{I18n.t("label_qbo_labels_source_#{type}")} ##{record.doc_number}"
when 'customer' then "#{I18n.t(:label_qbo_labels_source_customer)} #{record.name}"
when 'appointment' then "#{I18n.t(:label_qbo_labels_source_appointment)} ##{record.id}"
end
end
# The customer's last name: their family name in QuickBooks, or for a business their full name, or else
@@ -94,5 +158,11 @@ module RedmineQboLabels
nil
end
private_class_method :qbo_details
private
def describe(label, date)
[I18n.t(label), date.respond_to?(:strftime) ? I18n.l(date.to_date) : date].compact_blank.join(' ')
end
end
end
+26
View File
@@ -83,10 +83,36 @@ class LabelJobsTest < Redmine::IntegrationTest
assert_select 'template#qbo-label-issue-link a.icon-qbo-label-print[data-remote=true]'
end
def test_sidebar_prints_for_the_work_order_on_its_page
log_user('jsmith', 'jsmith')
get '/issues/1'
assert_select '#sidebar .qbo-label-sidebar a.icon-qbo-label-print[href=?]', '/label_jobs/new?source_id=1&source_type=issue'
assert_select '#sidebar .qbo-label-sidebar', text: /Work order #1/
end
def test_sidebar_prints_a_blank_label_elsewhere
log_user('jsmith', 'jsmith')
get '/projects'
assert_select '#sidebar .qbo-label-sidebar a.icon-qbo-label-print[href=?]', '/label_jobs/new'
end
def test_blank_label_dialog_and_print
log_user('jsmith', 'jsmith')
get '/label_jobs/new', xhr: true
assert_response :success
assert_no_match(/qbo_label_po_numbers/, response.body)
post '/label_jobs', params: { source_type: '', source_id: '', lines: ['Parts', 'Bin 4'] }, xhr: true
job = LabelJob.last
assert_equal ['PARTS', 'BIN 4'], job.lines
assert_nil job.source_type
end
def test_no_link_without_an_active_printer
@printer.update!(active: false)
log_user('jsmith', 'jsmith')
get '/issues/1'
assert_select 'template#qbo-label-issue-link', 0
assert_select '.qbo-label-sidebar', 0
end
end
+12
View File
@@ -31,6 +31,18 @@ module QboLabelsTestHelper
LabelJob.create!({ label_printer: printer, user: user, lines: lines, status: status }.merge(attributes))
end
# A customer, without sending it to QuickBooks
def create_customer(id: 9001, name: 'Jane Smith')
customer = Customer.new(id: id, name: name)
customer.skip_qbo_push = true
customer.save!
customer
end
def create_estimate(customer, id: '8001', doc_number: '1234', txn_date: Date.new(2026, 11, 2))
Estimate.create!(id: id, doc_number: doc_number, txn_date: txn_date, customer: customer)
end
def with_label_settings(values)
saved = Setting.plugin_redmine_qbo_labels
Setting.plugin_redmine_qbo_labels = RedmineQboLabels::Settings::DEFAULTS.merge(values)
+43
View File
@@ -62,6 +62,49 @@ class LabelSourceTest < ActiveSupport::TestCase
User.current = nil
end
def test_a_blank_label
source = RedmineQboLabels::LabelSource.find('', nil)
assert source.blank?
assert_equal ['', ''], source.lines
assert_nil source.title
assert_empty source.po_suggestions
end
def test_a_customer_fills_in_the_name_and_suggests_po_numbers
customer = create_customer
create_estimate(customer, id: '8001', doc_number: '1234', txn_date: Date.new(2026, 11, 2))
create_estimate(customer, id: '8002', doc_number: '1240', txn_date: Date.new(2026, 11, 9))
Issue.find(1).update_column(:customer_id, customer.id)
User.current = User.find(1) # admin
source = RedmineQboLabels::LabelSource.find('customer', customer.id)
assert_equal ['Smith', ''], source.lines
numbers = source.po_suggestions.map(&:first)
assert_equal %w[E1240 E1234 W1], numbers
ensure
User.current = nil
end
def test_estimates_from_the_record
customer = create_customer
estimate = create_estimate(customer)
User.current = User.find(1)
source = RedmineQboLabels::LabelSource.find('estimate', estimate.id)
assert_equal %w[Smith E1234], source.lines
assert_equal 'Estimate #1234', source.title
assert_includes source.po_suggestions.map(&:first), 'E1234'
ensure
User.current = nil
end
def test_customers_need_view_customers
customer = create_customer
User.current = User.find(7)
assert_nil RedmineQboLabels::LabelSource.find('customer', customer.id)
ensure
User.current = nil
end
def test_estimates_and_invoices_need_redmine_qbos_permissions
User.current = User.find(7) # no global permissions
assert_nil RedmineQboLabels::LabelSource.find('estimate', 1)