Developer notes

Overview · Installation · Configuration · Usage · FAQ

Data

Table	Contents
?:kv_gwm_wraps	wrap_id, company_id (Ultimate storefront, 0 = all), price, tax_ids, status, position, availability (A all, C categories, P products), category_ids, product_ids, updated_at
?:kv_gwm_wrap_descriptions	wrap_id, lang_code, name, description
?:kv_gwm_orders	one row per gift order: order_id, message, sender, recipient, send_to_other, wrap_total (net), wrap_tax, display_total, lines (JSON: scope package/item, company_id, cart_id, product, wrap_id, name, price, amount, subtotal, tax)

Wrap pictures are core image pairs with the object type kv_gwm_wrap. On Multi-Vendor the parent order and every vendor sub-order have their own row.

How the fee is calculated

The wrap fee is an order surcharge, modelled on the core payment surcharge and the core gift certificates:

1. The checkout form posts kv_gwm[...] with every checkout.update_steps, checkout.customer_info and checkout.place_order request (the fields carry data-ca-lite-checkout-field); controllers/frontend/checkout.pre.php validates them and stores them in $cart['kv_gwm'].
2. The calculate_cart hook (priority 150, before gift certificates are redeemed) resolves the wraps (active, offered for the package or product), calculates the taxes of each line with fn_calculate_tax_rates(), merges them into $cart['taxes'][<tax_id>]['applies']['KVGW_<line>'] and adds the net fee plus the added taxes to $cart['total']. The result is $cart['kv_gwm_calc'] (lines, total, tax_added, tax_total, display_total).
3. Core then calculates the payment surcharge from that total. On Multi-Vendor core recalculates every sub-order cart per vendor group, so each sub-order gets the lines of its own vendor.
4. The place_order hook writes ?:kv_gwm_orders for the order (and for each sub-order).

Order editing: the form_cart hook loads the gift data back into the cart with the ordered wrap prices locked.

Hooks used

calculate_cart, place_order, get_order_info, form_cart, delete_order, template_document_order_context_init, mailer_create_message_before, delete_product_post, delete_category_post, delete_company. All exist with the same arguments in 4.17.2 and 4.21.2.

Template hooks: checkout:final_section_customer_notes, checkout:checkout_totals, checkout:summary, orders:info, orders:order_total, orders:details_tools, products:promo_text (storefront); orders:totals, orders:totals_content, orders:details_tools, order_management:totals (admin and vendor panel); orders:totals, orders:invoice (classic e-mail templates).

Order data and REST API

fn_get_order_info() returns the gift data as kv_gwm, so GET /api/orders/<order_id> contains it:

"kv_gwm": {
  "is_gift": "Y",
  "message": "Happy birthday, Liam!",
  "sender": "Emma",
  "recipient": "Liam",
  "send_to_other": "Y",
  "wrap_total": 9,
  "wrap_tax": 0.82,
  "display_total": 9,
  "lines": [{"scope": "package", "company_id": 1, "wrap_id": 3, "name": "Premium gift box", "price": 9, "amount": 1, "subtotal": 9, "tax": 0.82}]
}

The order total includes the wrap fee. Full refunds through the payment gateway refund the order total, so they include the wrap; returns that refund products only (RMA) do not, like shipping.

Documents and e-mails

• template_document_order_context_init adds the rows kv_gwm_<n> (wraps) and kv_gwm_msg (message) to products and the wrap amount to display_subtotal of the document data only.
• Document variable gift for custom invoice and e-mail templates: {{ gift.is_gift }}, {{ gift.message }} (HTML, line breaks as <br>), {{ gift.sender }}, {{ gift.recipient }}, {{ gift.send_to_other }}, {{ gift.wraps }}, {{ gift.total }} (formatted), {{ gift.raw_total }}.
• Shipment e-mail (shipment_products): kv_gwm is available to the template; with Hide prices on, the order’s price fields are emptied.

Licence gate

Config::isActive() (setting + License\Client::isActive()) gates the checkout box, the storing of posted gift data, the fee of new carts and the product note. Existing orders (display, receipts, invoices, order editing with the stored wrap) are never gated.

CSS classes

.kv-gwm (checkout box), __card, __switch, __group, __options, __option, __option--selected, __thumb, __name, __desc, __price, __items, __field, __counter, __note, __total; .kv-gwm-total-line (totals), .kv-gwm-order (customer order page), .kv-gwm-note (product page), .kv-gwm-admin-order (admin order panel).

Classes (Tygh\Addons\KvGiftWrapMessages)

Config (settings, licence gate), Wraps (catalogue, availability), Calculator (input, fee, taxes), Orders (gift data of orders, document rows, receipt data), Panel (checkout view data), Documents (document variable), Mail (shipment e-mail data), Cleanup, License\Client, Upgrade\Synchronizer.

File map

app/addons/kv_gift_wrap_messages/
  addon.xml  init.php  func.php
  controllers/backend/kv_gift_wrap_messages.php       wraps manage/update/delete/status, gift_receipt
  controllers/backend/orders.pre.php                  message corrections from the order page
  controllers/backend/kv_gift_wrap_messages_license.php
  controllers/frontend/checkout.pre.php               stores the posted gift options
  controllers/frontend/checkout.post.php              checkout box data
  controllers/frontend/products.post.php              product page note
  controllers/frontend/kv_gift_wrap_messages.php      customer gift receipt
  schemas/{menu,permissions,block_manager,documents}/*.post.php
  Tygh/Addons/KvGiftWrapMessages/*.php
design/backend/templates/addons/kv_gift_wrap_messages/
  views/kv_gift_wrap_messages/{manage,update,gift_receipt}.tpl
  hooks/orders/{totals.pre,totals_content.post,details_tools.post}.tpl  hooks/order_management/totals.post.tpl
design/backend/mail/templates/addons/kv_gift_wrap_messages/hooks/orders/{totals,invoice}.post.tpl
design/backend/css/addons/kv_gift_wrap_messages/{styles,license}.less
var/themes_repository/responsive/templates/addons/kv_gift_wrap_messages/
  components/panel.tpl  views/kv_gift_wrap_messages/gift_receipt.tpl
  hooks/checkout/{final_section_customer_notes,checkout_totals,summary}.post.tpl
  hooks/orders/{info.post,order_total.pre,details_tools.post}.tpl  hooks/products/promo_text.post.tpl
var/themes_repository/responsive/mail/templates/addons/kv_gift_wrap_messages/hooks/orders/{totals,invoice}.post.tpl
var/themes_repository/responsive/css/addons/kv_gift_wrap_messages/styles.less
js/addons/kv_gift_wrap_messages/func.js
var/langs/en/addons/kv_gift_wrap_messages.po

Storefront templates and styles ship for the Responsive theme and reach Bright, Nova and other child themes by inheritance.