# Developer Quick Reference

**Last Updated:** 2026-03-20

Quick reference guide for common development tasks related to forms, components, and HubSpot integration.

## Form Endpoints Quick Reference

| Endpoint                           | Form GUID                              | Constant                         | Used By                    |
| ---------------------------------- | -------------------------------------- | -------------------------------- | -------------------------- |
| `collect-lead.php`                 | `a91b263c-7ca2-418b-b35c-9664c30e968b` | `HUBSPOT_FORM_GUID_TOOLS`        | Tools/calculators          |
| `submit-template.php`              | `11e392f7-aece-4969-8c39-402ee6cb2330` | `HUBSPOT_FORM_GUID_TEMPLATE`     | Template pages             |
| `addon-request.php`                | `c2022eda-c9b4-4010-a02d-d920852585b1` | `HUBSPOT_FORM_GUID_ADDON`        | Pricing pages              |
| `export-workdays.php`              | `a91b263c-7ca2-418b-b35c-9664c30e968b` | `HUBSPOT_FORM_GUID_WORKDAYS`     | Arbeitstage-Rechner        |
| `shiftops-hubspot.php`             | `41d07332-6697-4daa-b27e-dd60515f9c0f` | `HUBSPOT_FORM_GUID_SHIFTOPS`     | ShiftOps report            |
| `shiftops-nps.php`                 | `804459f7-c18d-4da6-8a0b-a81f44bb8275` | `HUBSPOT_FORM_GUID_SHIFTOPS_NPS` | ShiftOps NPS               |
| `lead-capture.php`                 | `9f9d4e35-d8d9-4283-93b6-1a789e0a1281` | `HUBSPOT_FORM_GUID_LEAD_CAPTURE` | Lead capture popup         |
| `webinar-registration.php`         | N/A                                    | N/A                              | Product webinars (CRM API) |
| `payroll-webinar-registration.php` | N/A                                    | N/A                              | Payroll webinars (CRM API) |

## Component Quick Reference

### Email Modal

```javascript
// Show email modal
window.submitEmailToHubSpot({
  toolName: "Tool Name",
  toolDescription: "Tool Description",
  toolData: {
    /* calculation data */
  },
  source: "Tool Name Export",
  onSuccess: function () {
    /* success handler */
  },
  onError: function (error) {
    /* error handler */
  },
});
```

### UTM Tracking

```javascript
// Get UTM data for API
const utmData = window.utmTracker.getUTMDataForAPI();

// Check email collected
const collected = window.OrdioEmailModalUtils.checkEmailCollected("Tool Name");
```

### GTM Form Tracking

```javascript
// Track API form
window.GTMFormTracker.trackAPIForm("endpoint.php", {
  formName: "Form Name",
  formId: "form-id",
  hubspotFormGuid: "form-guid",
});

// Track custom HTML form
window.GTMFormTracker.trackCustomHTMLForm(formElement, {
  formName: "Form Name",
  hubspotFormGuid: "form-guid",
});
```

### Lead Capture Popup

```php
<!-- Include component -->
<?php include '../components/lead-capture-popup.php'; ?>
<script src="/v2/js/lead-capture-triggers.min.js"></script>
```

```javascript
// Manual trigger
window.leadCapturePopup.show("manual-callback");
```

On **canonical `/tools` URLs** (hub + calculators), automatic triggers are disabled in `lead-capture-triggers.js`; use manual CTAs only. See `docs/systems/lead-capture/TRIGGER_CONFIGURATION.md`.

## Common Code Patterns

### Extract hubspotutk

```php
// PHP (cookie-first pattern)
$hubspotutk = isset($_COOKIE['hubspotutk']) ? $_COOKIE['hubspotutk'] : (!empty($input['hubspotutk']) ? trim($input['hubspotutk']) : '');
```

```javascript
// JavaScript
const hubspotutk = window.utmTracker ? window.utmTracker.getHubspotutk() : "";
```

### Forms API v3 Context

```php
"context" => array_filter([
    "hutk" => !empty($hubspotutk) ? $hubspotutk : null,
    "ipAddress" => $_SERVER['REMOTE_ADDR'] ?? null,
    "pageUri" => getActualPageUrl($page_url, $referrer),
    "pageName" => getPageNameFromUrl($page_url, $defaultPageName)
])
```

### Standardized API Response

```php
// Success
$response = createHubSpotSuccessResponse(
    ['contactId' => $contactId],
    'Success message',
    ['httpCode' => 200, 'attempts' => 1]
);

// Error
$response = createHubSpotErrorResponse(
    'Error message',
    400,
    ['endpoint' => 'endpoint-name']
);
```

## File Locations

### API Endpoints

- `v2/api/collect-lead.php`
- `v2/api/submit-template.php`
- `v2/api/addon-request.php`
- `v2/api/export-workdays.php`
- `v2/api/shiftops-hubspot.php`
- `v2/api/shiftops-nps.php`
- `v2/api/lead-capture.php`
- `v2/api/webinar-registration.php`
- `v2/api/payroll-webinar-registration.php`

### Shared Components

- `v2/js/shared/email-modal.js`
- `v2/js/shared/email-modal-utils.js`
- `v2/js/utm-tracking.js`
- `v2/js/gtm-form-tracking.js`
- `v2/components/lead-capture-popup.php`
- `v2/js/lead-capture-triggers.js`

### Configuration

- `v2/config/hubspot-config.php` - Form GUIDs and API tokens
- `v2/config/hubspot-api-helpers.php` - API helper functions

## Documentation Links

- **[Form-to-Page Mapping](forms/FORM_TO_PAGE_MAPPING.md)** - Which forms are used where
- **[Form Configuration Reference](forms/FORM_CONFIGURATION_REFERENCE.md)** - Field mappings
- **[HubSpot API Reference](apis/HUBSPOT_API_REFERENCE.md)** - Complete API documentation
- **[Component Usage Guide](shared-components/COMPONENT_USAGE_GUIDE.md)** - Integration patterns
- **[Data Flow Diagrams](forms/DATA_FLOW_DIAGRAMS.md)** - Visual data flows

## Common Tasks

### Add Email Collection to Tool

1. Load email modal scripts
2. Add export button
3. Initialize email modal on click
4. Add GTM tracking
5. Update form-to-page mapping

### Add Template Download Form

1. Create form HTML
2. Add form submission handler
3. Collect UTM data
4. Submit to `submit-template.php`
5. Add GTM tracking
6. Update form-to-page mapping

### Add Lead Capture to Page

1. Include lead capture component
2. Include trigger script
3. Test triggers (on `/tools`, expect **manual-only**; on other pages, time/scroll/exit-intent)
4. Verify copy detection

### Create New API Endpoint

1. Create endpoint file in `v2/api/`
2. Use Forms API v3 pattern
3. Extract hubspotutk (cookie-first)
4. Add context fields
5. Use `makeHubSpotAPICall()` helper
6. Add to form configuration reference
7. Update form-to-page mapping

## Testing Checklist

- [ ] Form submission works
- [ ] UTM data collected
- [ ] hubspotutk included
- [ ] GTM tracking fires
- [ ] HubSpot contact created
- [ ] Error handling works
- [ ] Mobile responsive
- [ ] Accessibility tested

## Related Documentation

- **[Systems Documentation](README.md)** - Complete systems documentation index
- **[Component Usage Guide](shared-components/COMPONENT_USAGE_GUIDE.md)** - Detailed integration guide