Create Booking Form - Technical Documentation

1. Page Overview

Property	Value
URL	/operations/create-booking
Route Handler	portals/operations/routes.py → create_booking() (line ~4116)
Template	templates/portals/operations/create_booking.html (~7,134 lines)
Blueprint	operations_portal
Base Template	portals/operations/base.html
Block	{% block dashboard_content %}
Auth	@login_required (Flask-Login)
Title	”Create Booking - iDrv5-MyFR8”

---

2. Form Structure & Layout

The form uses a 2-column layout:

• Left Column - Customer info, job type, special instructions, booking summary
• Right Column - Tabbed booking details (load, pickup, delivery), pricing, submission

2.1 Left Column Sections

Customer & Load Information Card

Tab navigation (#customerLoadTabs):

Tab	Content ID	Fields
Customer	#customer-info-content	Customer select, Invoice To radio, Third Party selector
Load	#load-details-content	Customer Reference Number, Document upload, Hourly rate fields (conditional)

Job Type Card

• Job Type - Button group: LTL, FTL, Empty Run, Towhaul
• Activity Type - Radio buttons: Pickup, Pickup and Delivery, Delivery Only, Local Start
• Service Level - Button group (dynamically loaded from API)

Special Instructions Card

• Additional Requirements textarea

Booking Summary Card (read-only)

Displays: Type, Service Type, Charge By, Items Count, Total Weight, Total Volume

2.2 Right Column Sections

Booking Details Card (#bookingTabs)

Draggable, reorderable tab navigation:

Tab	ID	Description
Load Details	#packaging-tab	Default active. Vehicle selection, unified load type entry, item tables
Pickup	#pickup-tab	Company info, address (Google Autocomplete), schedule, handling options
Delivery	#delivery-tab	Same structure as Pickup with receiver_* prefixes
Local Start	#local-start-tab	Conditional. Shown only for local_start activity type

Add Stop Dropdown: Allows adding extra Pickup or Delivery tabs.

Pricing Details Card (Section 5)

• Charge By method + units
• Base Price, Flat Rate (auto-computed), Fuel Levy %, Tailgate Fee
• Estimated Total (calculated)
• Surcharges section (dynamically populated addons)
• Price Breakdown (shown when tax addons active)
• Action buttons: Auto Calculate, Rate Computation Modal, Clear Pricing

Form Submission

• Save Booking (primary button)
• Cancel link

---

3. Complete Field Inventory

3.1 Customer Section

Field	HTML ID	Type	Required	Default	Notes
Customer	customer_select	Select dropdown	Yes	— Select Customer —	Populated from /api/customers
Add Customer	add_customer	Button	No	N/A	Opens new customer form
Invoice To	invoice_to_customer / invoice_to_third_party	Radio	No	customer	Options: customer, third_party
Third Party Customer	third_party_customer	Select dropdown	Conditional	Empty	Shown when invoice_to = third_party

3.2 Load Information Section

Field	HTML ID	Type	Required	Default	Notes
Reference Number	N/A	Text	No	Empty	Max 500 chars
Documents	operations-file-input	File (multiple)	No	N/A	PDF, JPG, PNG, DOC, DOCX. Max 10MB each. Drag & drop
Vehicle Type	vehicle_type	Select	Conditional	Empty	Shown for hourly hire
Hours Required	hours_required	Number	Conditional	1	For hourly hire bookings

3.3 Job Type Section

Field	HTML ID	Type	Required	Default	Notes
Job Type	job_type	Hidden + Button group	Yes	ftl	LTL, FTL, Empty Run, Towhaul
Activity Type	activity_*	Radio	Yes	pickup_and_delivery	Controls tab visibility
Service Level	selected_service_level	Hidden + Button group	No	Empty	From /api/service-levels

3.4 Load Details - Packaging Tab

Vehicle Selection

Field	HTML ID	Type	Required	Default	Notes
Vehicle Config	booking-vehicle-config	Select	Conditional	— No vehicle selected —	Required for FTL/Towhaul/Empty Run

Unified Load Type Selection

Field	HTML ID	Type	Required	Default	Notes
Load Type	unified-load-type	Select	Conditional	— Select —	Controls field visibility
Selected Load Type	selected_load_type	Hidden	No	Empty	freight, pallet, container, special

Freight Load Type (General Freight)

First row fields:

Field	HTML ID	Type	Required	Default	Notes
Quantity	first-row-qty	Number	No	1	min=1
Length	first-row-length	Decimal	No	Empty	CM, step=0.01
Width	first-row-width	Decimal	No	Empty	CM, step=0.01
Height	first-row-height	Decimal	No	Empty	CM, step=0.01
Weight	first-row-weight	Decimal	No	Empty	KG, step=0.01

Additional rows added dynamically via “Add Item” button (.freight-item-row class). Each row has: type select, qty, length, width, height, weight, delete button.

Pallet Load Type

Field	HTML ID	Type	Required	Default	Notes
Quantity	pallet-qty	Number	No	1	min=1
Length	pallet-length-cm	Decimal	No	120	CM, step=0.1
Width	pallet-width-cm	Decimal	No	120	CM, step=0.1
Height	pallet-height-cm	Decimal	No	275	CM, step=0.1
Total Weight	pallet-total-weight	Decimal	No	Empty	KG, step=0.01
Pallet Brand	palletTypeRadio	Radio	No	standard	standard, chep, loscam

Hire Account Details (shown when CHEP or LOSCAM selected):

Field	HTML ID	Type	Required	Default	Notes
Transaction Type	hire-transaction-type	Select	No	transfer	transfer, exchange, one-way
Docket Number	hire-docket-number	Text	No	Empty	CHEP/LOSCAM docket ref
Sender Account	hire-sender-account	Text	No	Empty	Sender account number
Receiver Account	hire-receiver-account	Text	No	Empty	Receiver account number

Towhaul / Special Load Type

Field	HTML ID	Type	Required	Default	Notes
Data Source	towhaul-manual / towhaul-registry	Radio	No	manual	Manual Entry or From Client Registry
Saved Asset	towhaul-saved-asset	Select	Conditional	Empty	Shown when registry selected
Category	towhaul-category	Select	Yes	— Select —	ROAD_TRAILER, HEAVY_MACHINERY, VEHICLE, RECREATIONAL
Subcategory	towhaul-subcategory	Text	No	Empty	e.g. Excavator, Skel Trailer
Nickname	towhaul-nickname	Text	No	Empty	e.g. Yellow Cat 320
Make/Model	towhaul-makemodel	Text	Yes	Empty	e.g. Caterpillar 320D
VIN	towhaul-vin	Text	No	Empty	VIN or Serial Number
Rego	towhaul-rego	Text	No	Empty	Registration plate
Coupling	towhaul-coupling	Select	Yes	— Select —	KINGPIN, PINTLE_HOOK, BALL_50MM, DRAWBAR, NONE
Braking	towhaul-braking	Select	Yes	— Select —	AIR_LINES, ELECTRIC, HYDRAULIC, NONE
Length	towhaul-length	Number	No	0	MM
Width	towhaul-width	Number	No	0	MM
Height	towhaul-height	Number	No	0	MM
Weight	towhaul-weight	Number	Yes	0	KG

Display Summaries:

• #total-cubic-weight - Total Cubic Weight
• #chargeable-weight - Chargeable Weight
• #total-pallets - Total Pallets
• #total-floor-spaces - Total Floor Spaces
• #total-pallet-weight - Total Pallet Weight

3.5 Pickup / Delivery Tabs (Dynamic, Repeatable)

Fields use array naming: pickup[N][field_name] and delivery[N][field_name].

Company & Contact

Field	Name Pattern	Type	Required	Notes
Company Name	pickup[N][company_name]	Text	Yes	Sender/Receiver company
Contact Person	pickup[N][contact_person]	Text	No	Contact name
Address	pickup[N][address]	Text + Google Autocomplete	Yes	Google Places autocomplete
Locality	pickup[N][locality]	Hidden	No	Suburb (from autocomplete)
Postal Code	pickup[N][postal_code]	Hidden	No	Postcode (from autocomplete)
State	pickup[N][state]	Hidden	No	State (from autocomplete)
Zone ID	pickup[N][zone_id]	Hidden	No	Zone ID (from zone lookup)
Email	pickup[N][email]	Email	No	Contact email
Phone	pickup[N][phone]	Tel	No	Contact phone
Opening Time	pickup[N][opening_time]	Time	No	HH:MM
Closing Time	pickup[N][closing_time]	Time	No	HH:MM

Schedule & Requirements

Field	Name Pattern	Type	Required	Notes
Date	pickup[N][date]	Date	Yes	YYYY-MM-DD
Time From	pickup[N][time_from]	Time	No	HH:MM
Time To	pickup[N][time_to]	Time	No	HH:MM

Handling Options (Button toggles with hidden inputs)

Field	Name Pattern	Type	Default	Addon Binding
Residential	pickup[N][residential]	Hidden	Empty	pickup_residential
Tailgate	pickup[N][tailgate]	Hidden	Empty	pickup_tailgate
Manual Handling	pickup[N][manual_handling]	Hidden	Empty	pickup_manual_handling
Time Slot	pickup[N][time_slot]	Hidden	Empty	pickup_time_slot

Special Instructions

Field	Name Pattern	Type	Required	Notes
Instructions	pickup[N][special_instructions]	Textarea	No	Max 500 chars

Delivery tabs follow the same structure with delivery[N][...] naming.

3.6 Local Start Tab (Conditional)

Shown only when activity_type = local_start. Prefix: local_start_*.

Field	HTML ID	Type	Required	Notes
Company Name	local_start_company_name	Text	No	Site/company name
Street Number	local_start_street_number	Text	No
Street	local_start_street	Text	No
Suburb	local_start_suburb	Text	No
State	local_start_state	Text	No
Postcode	local_start_postcode	Text	No
Zone ID	local_start_zone_id	Hidden	No
Opening Time	local_start_opening_time	Time	No
Closing Time	local_start_closing_time	Time	No
Contact Name	local_start_contact_name	Text	No
Contact Number	local_start_contact_number	Text	No
Contact Email	local_start_contact_email	Email	No
Notes	local_start_notes	Textarea	No

3.7 Pricing Section

Field	HTML ID	Type	Required	Default	Notes
Charge By Method	charge_by_method	Select	Yes	Loading…	From rate calculation methods API
Charge By Units	charge_by_units	Number	No	0	min=0, step=0.01
Base Price	base_price	Currency	Yes	0.00
Flat Rate	flat-rate-input	Currency (read-only)	No	0.00	Auto-computed from rate engine
Fuel Levy	fuel-levy-input	Percentage	No	20	Fuel surcharge %
Tailgate Fee	service-fee-input	Currency	No	0
Total Cost	total-cost	Display (span)	No	0.00	Calculated

Hidden fields for rate calculation: sender_address, receiver_address, pickup_locality, delivery_locality, pickup_postal_code, delivery_postal_code, pickup_administrative_area_level_1, delivery_administrative_area_level_1, pickup_zone_id, delivery_zone_id, selected_service_level, chargeable-weight.

---

4. JavaScript Architecture

4.1 Global Variables & Caches

window._addonCache = {}           // Keyed by ui_binding
window._addonCacheAll = []        // All applicable addons
window._activeAddonItems = {}     // Keyed by addon_id -> line item data
window._computedEngineTotal = null // Last computed rate from API

4.2 Key Functions

Addon Management

Function	Purpose
toggleHandlingOption(button)	Toggle handling option buttons (residential, tailgate, etc.). Toggles active state, sets hidden input, calls addAddonByBinding() or removeAddonByBinding(), updates total cost
addAddonByBinding(binding)	Add addon by UI binding string. Looks up in cache, creates line item, renders it
removeAddonByBinding(binding)	Remove addon by UI binding. Deletes from _activeAddonItems, removes DOM element
renderAddonLineItem(item)	Render addon as styled line item in surcharges list. Shows trigger mode badge, label, amount, taxable status
removeManualAddon(addonId)	Remove a manually added addon

Load Type & Item Management

Function	Purpose
handleLoadTypeChange(value)	Handle main load type dropdown change. Hides all conditional fields, shows fields for selected type, updates selected_load_type hidden input
addFreightRow()	Add additional freight item row with all input fields
clearLoadTypeForm()	Clear all load type fields and reset selection
handleBrandChange(value)	Handle pallet brand selection (Standard/CHEP/LOSCAM). Shows/hides hire account details
toggleHireDetails(event)	Toggle hire account details section

Rate Calculation

Function	Purpose
calculateRatesFromAPI(showModalLog)	Primary rate calculation. Validates fields, collects data, POSTs to /api/rate-entries/compute-rate, falls back to /api/rate-entries/check-entry. When showModalLog=true shows detailed modal; when false auto-fills silently
applyComputedRate()	Apply lastComputedRate to form. Sets base_price and flat_rate fields, stores in _computedEngineTotal, calls updateTotalCost()
updateTotalCost()	Calculate and display total. Processes fuel levy, tailgate, all active addons (fixed/percentage), handles per-unit addons, applies taxes, updates #total-cost display
clearPricing()	Reset all pricing fields to defaults

Zone & Address Resolution

Function	Purpose
fillInAddress(place, type)	Populate address fields from Google Places result. Extracts components, populates form, calls zone resolution API
fillInLocalStartAddress(place)	Populate local start address from Google Places. Also extracts business name

Data Collection

Function	Purpose
collectPackageData()	Collect all items/packages. Checks load type, collects freight/pallet/container data, falls back to legacy tables. Returns array of package objects
collectAddressData(type)	Collect address fields into structured object. Parameter: ‘pickup’ or ‘delivery’

Form Submission

Function	Purpose
submitBooking()	Collect all form data, build JSON payload, POST to /api/connotes/, handle success/error responses

Utility

Function	Purpose
_getBookingQuantityForUnit(unitType)	Calculate total quantity for a unit type. Handles: pallet/item (sum qty), kg (sum weight), km (distance), cubic_meter (total CBM)
logToRatesModal(html, scrollToBottom)	Append HTML to rates computation log modal

---

5. API Endpoints Used

5.1 Rate Calculation

POST /api/rate-entries/compute-rate

Primary rate calculation endpoint.

Request:

{
  "rate_card_id": 123,
  "customer_id": 456,
  "origin_zone_id": 1,
  "destination_zone_id": 2,
  "service_level_id": 3,
  "items": [
    {
      "packaging_type": "Carton",
      "quantity": 2,
      "length_cm": 60,
      "width_cm": 40,
      "height_cm": 30,
      "weight_kg": 25
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "base_rate": 150.00,
    "flat_rate": 150.00,
    "final_total": 195.00,
    "rate_calculation_method": "Per Pallet",
    "minimum_charge": 50.00
  }
}

POST /api/rate-entries/check-entry

Fallback endpoint when compute-rate returns no results. Similar request/response structure.

POST /api/rate-entries/check-zone

Resolves address to zone ID.

Request:

{
  "suburb": "Parramatta",
  "postcode": "2150",
  "state": "NSW"
}

Response:

{
  "found": true,
  "zone_id": 42
}

5.2 Reference Data (loaded on page init)

Endpoint	Method	Used For
/api/service-levels	GET	Service type button group
/api/rate-entries/rate-calculation-methods	GET	Charge By dropdown
/api/transport-equipment/configurations	GET	Vehicle type dropdown
/api/pallet-types	GET	Pallet dimensions & pricing
/api/container-types	GET	Container selection
/api/packaging-types	GET	Freight type selection
/api/customers	GET	Customer dropdown (loaded server-side)

5.3 Addon/Surcharge Loading

GET /api/addons/for-context?form_target=Booking&customer_id=X&rate_card_id=Y

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Residential Surcharge",
      "alias": "residential",
      "addon_type": "Surcharge",
      "value_type": "Fixed amount",
      "default_value": 25.00,
      "customer_override_value": null,
      "ui_binding": "pickup_residential",
      "trigger_mode": "automatic",
      "calculation_order": 1,
      "applies_on": "subtotal",
      "application_scope": "per_booking",
      "is_taxable": true,
      "is_tax_addon": false,
      "tax_code": null,
      "tax_inclusive": false,
      "client_visible": true
    }
  ]
}

5.4 Booking Submission

POST /api/connotes/

Request:

{
  "customer_id": 456,
  "invoice_to": "customer",
  "third_party_customer_id": null,
  "job_type_id": 2,
  "activity_type_id": 1,
  "service_level_id": 3,
  "special_instructions": "Handle with care",
  "pickup_address": {
    "address_line1": "123 Main St",
    "suburb": "Parramatta",
    "state": "NSW",
    "postcode": "2150",
    "contact_name": "John Smith",
    "contact_phone": "0412345678",
    "contact_email": "john@example.com",
    "company_name": "Acme Corp",
    "country": "Australia"
  },
  "delivery_address": { },
  "local_start_address": null,
  "load_type": "freight",
  "packages": [
    {
      "packaging_type": "Carton",
      "quantity": 2,
      "length_cm": 60,
      "width_cm": 40,
      "height_cm": 30,
      "weight_kg": 25
    }
  ],
  "base_rate": 150.00,
  "flat_rate": 150.00,
  "computed_total": 195.00,
  "fuel_levy_percentage": 20,
  "tailgate_fee": 0,
  "is_tailgate_pickup": false,
  "is_tailgate_delivery": false,
  "gst_rate": 10,
  "addon_line_items": [
    {
      "addon_id": 1,
      "alias": "residential",
      "name": "Residential Surcharge",
      "value_type": "Fixed amount",
      "raw_value": "25",
      "amount": 25.00,
      "applies_on": "subtotal",
      "client_visible": true
    }
  ]
}

Response:

{
  "success": true,
  "message": "Booking created successfully",
  "booking_id": 789,
  "connote_number": "CON-2026-000789"
}

---

6. Rate Calculation Flow

6.1 Calculation Sequence

1. User fills in required fields:
   - Customer (required)
   - Pickup address (required) → auto-resolves zone via /api/rate-entries/check-zone
   - Delivery address (required) → auto-resolves zone
   - Load type and items (recommended)
   - Service level (optional)

2. Trigger: "Auto Calculate" button click or auto-trigger
   │
   ▼
3. calculateRatesFromAPI()
   ├─ Validate required fields present
   ├─ Collect booking data (customer, addresses, items)
   ├─ POST /api/rate-entries/compute-rate
   │   ├─ Success → store in lastComputedRate, show Apply button
   │   └─ No results → fallback to POST /api/rate-entries/check-entry
   └─ Show computation modal with detailed log

4. User clicks "Apply Rate"
   │
   ▼
5. applyComputedRate()
   ├─ Set base_price field
   ├─ Set flat_rate field
   ├─ Store in _computedEngineTotal
   └─ Call updateTotalCost()

6.2 Weight Calculation

totalWeight    = SUM(quantity * weight for each item)
cubicWeight    = SUM(L * W * H / 5000 for each item)  // Australian standard
chargeableWeight = MAX(totalWeight, cubicWeight)

Updated in real-time as items change. Displayed in #total-cubic-weight and #chargeable-weight.

6.3 Total Cost Calculation

subtotal = base_price (from rate engine or manual)

For each addon in _activeAddonItems (ordered by calculation_order):
  if value_type == "percentage":
    amount = subtotal * (raw_value / 100)
  else:
    amount = raw_value  (fixed)

  if application_scope == "per_unit":
    amount *= unitQuantity

  runningTotal += amount

For each tax addon (is_tax_addon == true):
  taxableSubtotal = sum of non-tax, taxable addon amounts
  if tax_inclusive:
    display as "(X% incl.)"
  else:
    tax = taxableSubtotal * (tax_rate / 100)
    runningTotal += tax

final = runningTotal + fuel_levy + tailgate_fee

---

7. Form Submission Flow

1. User clicks "Save Booking"
   │
   ▼
2. Button disabled, loading state shown
   │
   ▼
3. submitBooking()
   ├─ Collect all form data:
   │   ├─ Customer info
   │   ├─ Pickup/Delivery addresses & times
   │   ├─ All items/packages (via collectPackageData())
   │   ├─ Pricing fields
   │   └─ Active addons
   ├─ Build JSON payload
   └─ Validate required fields
   │
   ▼
4. POST /api/connotes/
   │
   ▼
5. Backend creates:
   ├─ Connote record
   ├─ Address records
   ├─ Item/package records
   ├─ Pricing records
   └─ Addon line items
   │
   ▼
6. Response handling:
   ├─ Success → show success alert with connote number,
   │            offer "View Details" / "Create Another"
   └─ Error → display validation errors, re-enable Save button

Validation

Client-side: Customer (required), Pickup Address (required), Delivery Address (required), Base Price (required when not auto-computed), Job Type (required).

Server-side (in /api/connotes/): Customer fields, address structure, package data, pricing fields, addon data structure.

---

8. Conditional Logic & Interactions

8.1 Job Type Controls Field Visibility

Job Type	Effect
FTL	Vehicle required, Load details shown
LTL	Item entry required, Packaging shown
Empty Run	Vehicle required
Towhaul	Special towhaul form (coupling, braking, dimensions)
Hourly	Hours + Vehicle type fields shown

8.2 Activity Type Controls Tab Visibility

Activity Type	Visible Tabs
Pickup	Load Details, Pickup
Pickup and Delivery	Load Details, Pickup, Delivery
Delivery Only	Load Details, Delivery
Local Start	Load Details, Local Start

8.3 Load Type Controls Input Fields

Load Type	Fields Shown	Hidden Value
Freight	Qty, L, W, H, Weight (multiple rows)	selected_load_type=freight
Pallet	Qty, L, W, H, Weight, Brand radio	selected_load_type=pallet
Container	Container type dropdown	selected_load_type=container
Special/Towhaul	Asset classification, identity, technical specs	selected_load_type=special

8.4 Pallet Brand Controls Hire Details

Brand	Hire Details Shown
Standard	No
CHEP	Yes - Transaction type, Docket #, Sender/Receiver accounts
LOSCAM	Yes - Transaction type, Docket #, Sender/Receiver accounts

8.5 Handling Option Buttons Trigger Addons

Button	UI Binding	Auto-added Addon
Residential Address	pickup_residential / delivery_residential	Residential surcharge
Tailgate Required	pickup_tailgate / delivery_tailgate	Tailgate surcharge
Manual Handling	pickup_manual_handling / delivery_manual_handling	Manual handling surcharge
Time Slot Required	pickup_time_slot / delivery_time_slot	Time slot surcharge

---

9. External Dependencies

JavaScript Libraries

Library	Version	Source	Purpose
jQuery	3.6.0	CDN	DOM manipulation, AJAX
Bootstrap	5.3+	CDN (via base template)	Modals, buttons, layout, grid
Flatpickr	Latest	CDN	Date/time picker inputs
SortableJS	1.15.0	CDN	Drag-and-drop tab reordering
Google Maps API	Latest	Via google_maps_api_key	Address autocomplete (AU only)
Bootstrap Icons	Latest	CDN	Icons

Custom JavaScript Files

File	Purpose
static/js/create_booking_skeleton.js	Loading skeleton screens
static/js/booking-tabs-manager.js	Dynamic tab creation and management for multiple pickups/deliveries

Inline Scripts

The majority of form logic is in <script> blocks within the template (~3,500+ lines):

• Addon management (~200 lines)
• Load type handling (~500 lines)
• Rate calculation (~1,000 lines)
• Form submission (~1,000 lines)
• Address handling (~400 lines)
• Google Maps init (~100 lines)
• Addon system initialization (~300 lines)

---

10. File Locations Reference

Component	Path
Template	templates/portals/operations/create_booking.html
Route Handler	portals/operations/routes.py (line ~4116)
Booking Tabs Manager	static/js/booking-tabs-manager.js
Skeleton Loader	static/js/create_booking_skeleton.js
Rate Entries API	api/rate_entries_api.py
Connotes API	api/connotes_api.py
Addons API	api/addons_api.py
Service Levels API	api/service_levels_api.py
Customers API	api/customers_api.py
Transport Equipment API	api/transport_equipment_api.py
Operations Base Template	templates/portals/operations/base.html

---

11. Security

• All form data sanitized on backend
• CSRF protection via Flask-WTF
• Google Maps API key validated server-side
• Rate calculation validated on backend (client cannot set arbitrary rates without server confirmation)
• File upload restricted to safe types: PDF, JPG, PNG, DOC, DOCX (max 10MB each)
• @login_required on the route handler