# Component Usage Guide

**Last Updated:** 2026-03-31

Practical guide for using shared components in new pages and forms.

## Overview

This guide provides step-by-step instructions for integrating shared components into new pages, forms, and tools.

## Quick Reference

| Component          | File                                   | Global Object                 | Purpose                    |
| ------------------ | -------------------------------------- | ----------------------------- | -------------------------- |
| Email Modal        | `v2/js/shared/email-modal.js`          | `window.submitEmailToHubSpot` | Email collection for tools |
| Email Modal Utils  | `v2/js/shared/email-modal-utils.js`    | `window.OrdioEmailModalUtils` | Email validation, storage  |
| UTM Tracking       | `v2/js/utm-tracking.js`                | `window.utmTracker`           | UTM parameter tracking     |
| GTM Form Tracking  | `v2/js/gtm-form-tracking.js`           | `window.GTMFormTracker`       | Form submission tracking   |
| Lead Capture Popup | `v2/components/lead-capture-popup.php` | `window.leadCapturePopup`     | Two-step lead capture      |
| Social proof trust card | `v2/sections/social-proof-trust-card.php` + `v2/data/social-proof-trust-section.php` | — | Homepage-style customer logos, CTA to `/kunden`, Google + OMR review tiles; edit **data file** for copy, counts, and asset paths |
| OMR composite badge strip | `v2/sections/partials/omr-review-badges-strip.php` + `v2/data/omr-review-badges.php` | — | Single raster row of OMR shield badges (not the OMR logo tile). Optional `omr-reviews-rating-tiles.php` + `omr-reviews-ausgezeichnet-section.php` for pricing-style blocks. See `docs/systems/shared-components/OMR_REVIEW_BADGES.md`. Validation: `php v2/scripts/dev-helpers/verify-omr-review-badges.php` |
| Pricing block (canonical) | `v2/sections/pricing-data.php` + `pricing-period-toggle.php` + `pricing-cards-grid-simple.php` → `pricing-card-modern.php`; optional `enterprise-box-modern.php`; `pricing-addons.php`; **„Alle Pakete im Vergleich“** = `v2/data/comparison-table-data.json` + `comparison-table-modern.php` | `window.currentPricingPeriod` + `pricing-page.min.js` | Live `/preise` = `v2/pages/static_pricing_new.php`. **Do not** duplicate monthly/yearly toggle markup or add-on grids—use partials. Add-on CSS ships in `pricing-page.min.css`. Validation: `php v2/scripts/dev-helpers/verify-pricing-modularization.php` |
| Reporting insights (dark section) | `v2/data/reporting-insights-section.php` + `v2/sections/reporting-insights-section.php` | — (loads `reporting-key-figures.min.js` once per page via partial) | Homepage section-3 and aligned LPs/product pages: wave or product SVG transition, key figures, hero WebP cards, four feature cards + mobile carousel. Overrides: `$reporting_insights_overrides` (`top_transition` = `wave_home` \| `svg_product`, `inner_padding_class`, …). CSS: `reporting-insights-section.min.css`. Validation: `php v2/scripts/dev-helpers/verify-reporting-insights-section.php` |
| Customer logo marquee | `v2/data/customer-logos-marquee.php` + `v2/sections/partials/customer-logo-marquee.php` | — (`ordio_customer_logo_marquee_enqueue_assets()` in partial) | Infinite logo strip with correct -50% loop, reduced motion, off-screen pause, configurable edge fade (`fade_bg` / `--ordio-marquee-fade-bg`), `label_preset` vs `label_class`. **Do not** use raw `logo-slider` or `animation: slide` for this. See `docs/systems/shared-components/CUSTOMER_LOGO_MARQUEE.md`. Validation: `php v2/scripts/dev-helpers/verify-customer-logo-marquee.php` |
| Feature showcase grid (8 cards) | `v2/sections/partials/feature-showcase-grid.php` → `v2/components/feature-cards-grid.php` | `feature-showcase-grid.min.js` (deferred once per page via component) | Product/feature cards with scoped SVG ids (`ordio-fsg-{instance_id}-…`), `data-ordio-fsg-role` for animations. Set `$feature_showcase_options['instance_id']`. **Do not** duplicate grid markup. See `docs/systems/shared-components/FEATURE_SHOWCASE_GRID.md`. Validation: `php v2/scripts/dev-helpers/verify-feature-showcase-grid.php` |
| Three-card testimonials | `v2/data/three-card-testimonials.php` + `v2/sections/partials/three-card-testimonials.php` | — | Zappes / Fette Kuh / Heilandt quotes, stars, avatars, mandatory link to `/kunden`. Use `$three_card_testimonials_options`: `layout` = `full` \| `grid_only`, `heading_variant` = `kunden_sagen` \| `teams_daily`, optional `section_class`, `outer_section_class` + `inner_wrapper_class`, `heading_id`, `card_shadow_class`, `grid_only_wrapper_class`. **Do not** paste the three-card HTML into pages. See `docs/systems/shared-components/THREE_CARD_TESTIMONIALS.md`. Validation: `php v2/scripts/dev-helpers/verify-three-card-testimonials.php` |
| FAQ accordion (site-wide) | `v2/components/site-faq-section.php` + optional `render-faq-json.php` / `render-compare-faq.php`; data under `v2/data/**/*.json` | — | Set `$ordio_faq_json_relpath` or `$site_faq_items`. Answers may contain HTML (`<p>`, `<a>`, lists); sanitization loads via `blog-template-helpers.php` when needed. **FAQPage JSON-LD:** build with `ordio_faqpage_schema_node()` in `v2/helpers/faq-jsonld.php` from the same items as the visible FAQ—pricing: `static_pricing_new.php` + `pricing-faq.json`. See `docs/content/FAQ_WEBSITE_STANDARD.md`. Checks: `verify-faq-jsonld-parity.php`, `audit-faq-json-internal-links.php` |

## Integration Patterns

### Pattern 1: Tools/Calculator Pages

**Use Case:** Calculator or tool page that requires email collection for export/download.

**Required Components:**

1. Email Modal Component
2. Email Modal Utils
3. UTM Tracking
4. GTM Form Tracking

**Step-by-Step:**

#### 1. Load Required Scripts

```php
<!-- In head.php or before closing </body> -->
<script src="/v2/js/shared/email-modal-utils.min.js?v=<?php echo filemtime(__DIR__ . '/../js/shared/email-modal-utils.min.js'); ?>"></script>
<script src="/v2/js/shared/email-modal.min.js?v=<?php echo filemtime(__DIR__ . '/../js/shared/email-modal.min.js'); ?>"></script>
<script src="/v2/js/utm-tracking.min.js?v=<?php echo filemtime(__DIR__ . '/../js/utm-tracking.min.js'); ?>"></script>
<script src="/v2/js/gtm-form-tracking.min.js?v=<?php echo filemtime(__DIR__ . '/../js/gtm-form-tracking.min.js'); ?>"></script>
```

#### 2. Add Email Collection Button

```html
<button id="export-email-btn" class="btn-primary">
  Ergebnisse per E-Mail erhalten
</button>
```

#### 3. Initialize Email Modal

```javascript
document.addEventListener("DOMContentLoaded", function () {
  const exportBtn = document.getElementById("export-email-btn");

  exportBtn.addEventListener("click", function () {
    // Check if email already collected
    const toolName = "My Calculator";
    const emailCollected =
      window.OrdioEmailModalUtils.checkEmailCollected(toolName);

    if (emailCollected) {
      // Email already collected, proceed with export
      exportResults();
    } else {
      // Show email modal
      showEmailModal(toolName);
    }
  });
});

function showEmailModal(toolName) {
  // Get UTM data
  const utmData = window.utmTracker ? window.utmTracker.getUTMDataForAPI() : {};

  // Prepare tool data
  const toolData = {
    // Your calculation results here
    result1: 100,
    result2: 200,
    // ...
  };

  // Show modal and collect email
  if (window.submitEmailToHubSpot) {
    window.submitEmailToHubSpot({
      toolName: toolName,
      toolDescription: "My Calculator Description",
      toolData: toolData,
      source: toolName + " Export",
      onSuccess: function () {
        // Email collected, proceed with export
        exportResults();
      },
      onError: function (error) {
        console.error("Email collection failed:", error);
        alert(
          "Fehler beim Sammeln der E-Mail-Adresse. Bitte versuche es erneut."
        );
      },
    });
  }
}

function exportResults() {
  // Your export logic here
  console.log("Exporting results...");
}
```

#### 4. Add GTM Tracking

```javascript
// In showEmailModal function, before calling submitEmailToHubSpot
if (
  window.GTMFormTracker &&
  typeof window.GTMFormTracker.trackAPIForm === "function"
) {
  window.GTMFormTracker.trackAPIForm("collect-lead.php", {
    formName: toolName + " Export Form",
    formId: "calculator-export-" + toolName.toLowerCase().replace(/\s+/g, "-"),
    hubspotFormGuid: "a91b263c-7ca2-418b-b35c-9664c30e968b",
    formGuidConstant: "TOOLS",
    contentType: toolName,
  });
}
```

### Pattern 2: Template Download Pages

**Use Case:** Template download page with HubSpot form.

**Required Components:**

1. UTM Tracking
2. GTM Form Tracking

**Step-by-Step:**

#### 1. Load Required Scripts

```php
<script src="/v2/js/utm-tracking.min.js?v=<?php echo filemtime(__DIR__ . '/../js/utm-tracking.min.js'); ?>"></script>
<script src="/v2/js/gtm-form-tracking.min.js?v=<?php echo filemtime(__DIR__ . '/../js/gtm-form-tracking.min.js'); ?>"></script>
```

#### 2. Add Form Submission Handler

```javascript
document
  .getElementById("template-form")
  .addEventListener("submit", function (e) {
    e.preventDefault();

    // Collect form data
    const formData = {
      email: document.getElementById("email").value,
      firstname: document.getElementById("firstname").value,
      lastname: document.getElementById("lastname").value,
      phone: document.getElementById("phone").value,
      industry: document.getElementById("industry").value,
      company_size: document.getElementById("company_size").value,
      content_type: "Schichtplan Vorlage - Template",
    };

    // Get UTM data
    const utmData = window.utmTracker
      ? window.utmTracker.getUTMDataForAPI()
      : {};

    // Add UTM data to form data
    Object.assign(formData, utmData);

    // GTM Tracking
    if (
      window.GTMFormTracker &&
      typeof window.GTMFormTracker.trackAPIForm === "function"
    ) {
      window.GTMFormTracker.trackAPIForm("submit-template.php", {
        formName: "Template Download Form",
        formId: "template-download-form",
        hubspotFormGuid: "11e392f7-aece-4969-8c39-402ee6cb2330",
        formGuidConstant: "TEMPLATE",
        contentType: formData.content_type,
        templateType: "Schichtplan",
      });
    }

    // Submit to API
    fetch("/v2/api/submit-template.php", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(formData),
    })
      .then((response) => response.json())
      .then((data) => {
        if (data.success) {
          // Trigger download
          window.location.href = "/templates/schichtplan.xlsx";
        } else {
          alert(
            "Fehler beim Absenden des Formulars. Bitte versuche es erneut."
          );
        }
      })
      .catch((error) => {
        console.error("Error:", error);
        alert("Ein Fehler ist aufgetreten. Bitte versuche es erneut.");
      });
  });
```

### Pattern 3: Lead Capture Popup

**Use Case:** Add lead capture popup to any page.

**Required Components:**

1. Lead Capture Popup Component
2. Lead Capture Triggers

**Step-by-Step:**

#### 1. Include Component

```php
<!-- Before closing </body> tag -->
<?php include '../components/lead-capture-popup.php'; ?>
<script src="/v2/js/lead-capture-triggers.min.js?v=<?php echo filemtime(__DIR__ . '/../js/lead-capture-triggers.min.js'); ?>"></script>
```

**That's it!** The popup will automatically:

- Detect page type
- Show appropriate copy
- Trigger based on page priority
- Handle form submissions
- Sync to HubSpot and Google Sheets

#### 2. Manual Trigger (Optional)

```javascript
// Trigger popup manually
if (window.leadCapturePopup) {
  window.leadCapturePopup.show("manual-callback");
}
```

### Pattern 4: Custom Form with HubSpot Integration

**Use Case:** Custom form that submits to HubSpot.

**Required Components:**

1. UTM Tracking
2. GTM Form Tracking

**Step-by-Step:**

#### 1. Load Required Scripts

```php
<script src="/v2/js/utm-tracking.min.js?v=<?php echo filemtime(__DIR__ . '/../js/utm-tracking.min.js'); ?>"></script>
<script src="/v2/js/gtm-form-tracking.min.js?v=<?php echo filemtime(__DIR__ . '/../js/gtm-form-tracking.min.js'); ?>"></script>
```

#### 2. Add Form Handler

```javascript
document.getElementById("my-form").addEventListener("submit", function (e) {
  e.preventDefault();

  // Collect form data
  const formData = {
    email: document.getElementById("email").value,
    name: document.getElementById("name").value,
    message: document.getElementById("message").value,
  };

  // Get UTM data
  const utmData = window.utmTracker ? window.utmTracker.getUTMDataForAPI() : {};

  // Add UTM data
  Object.assign(formData, utmData);

  // GTM Tracking
  if (
    window.GTMFormTracker &&
    typeof window.GTMFormTracker.trackCustomHTMLForm === "function"
  ) {
    window.GTMFormTracker.trackCustomHTMLForm(this, {
      formName: "My Custom Form",
      formType: "contact_form",
      hubspotFormGuid: "your-form-guid-here",
    });
  }

  // Submit to API
  fetch("/v2/api/your-endpoint.php", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(formData),
  })
    .then((response) => response.json())
    .then((data) => {
      if (data.success) {
        alert("Formular erfolgreich abgesendet!");
        this.reset();
      } else {
        alert("Fehler beim Absenden des Formulars.");
      }
    });
});
```

## Component Dependencies

### Email Modal Component

**Depends on:**

- `email-modal-utils.js` (must load first)
- `utm-tracking.js` (for UTM data)
- `gtm-form-tracking.js` (for form tracking)

**Load Order:**

```html
<!-- 1. Utils first -->
<script src="/v2/js/shared/email-modal-utils.min.js"></script>
<!-- 2. UTM tracking -->
<script src="/v2/js/utm-tracking.min.js"></script>
<!-- 3. GTM tracking -->
<script src="/v2/js/gtm-form-tracking.min.js"></script>
<!-- 4. Email modal last -->
<script src="/v2/js/shared/email-modal.min.js"></script>
```

### Lead Capture Popup

**Depends on:**

- `utm-tracking.js` (for UTM data)
- `lead-capture-triggers.js` (for trigger system)

**Load Order:**

```html
<!-- 1. UTM tracking -->
<script src="/v2/js/utm-tracking.min.js"></script>
<!-- 2. Lead capture component -->
<?php include '../components/lead-capture-popup.php'; ?>
<!-- 3. Triggers last -->
<script src="/v2/js/lead-capture-triggers.min.js"></script>
```

## Common Patterns

### Pattern: Check Email Already Collected

```javascript
const toolName = "My Tool";
const emailCollected =
  window.OrdioEmailModalUtils.checkEmailCollected(toolName);

if (emailCollected) {
  // Email already collected, proceed
  proceedWithAction();
} else {
  // Show email modal
  showEmailModal();
}
```

### Pattern: Get UTM Data

```javascript
// Preferred method
const utmData = window.utmTracker ? window.utmTracker.getUTMDataForAPI() : {};

// Fallback method
const utmData = window.utmTracking || {};
```

### Pattern: Track Form Submission

```javascript
// For API-based forms
if (
  window.GTMFormTracker &&
  typeof window.GTMFormTracker.trackAPIForm === "function"
) {
  window.GTMFormTracker.trackAPIForm("endpoint.php", {
    formName: "Form Name",
    formId: "form-id",
    hubspotFormGuid: "form-guid",
  });
}

// For custom HTML forms
if (
  window.GTMFormTracker &&
  typeof window.GTMFormTracker.trackCustomHTMLForm === "function"
) {
  window.GTMFormTracker.trackCustomHTMLForm(formElement, {
    formName: "Form Name",
    hubspotFormGuid: "form-guid",
  });
}
```

## Error Handling

### Email Modal Errors

```javascript
window.submitEmailToHubSpot({
  // ... config ...
  onError: function (error) {
    console.error("Email collection error:", error);

    // Show user-friendly error
    if (error.message) {
      alert("Fehler: " + error.message);
    } else {
      alert(
        "Fehler beim Sammeln der E-Mail-Adresse. Bitte versuche es erneut."
      );
    }
  },
});
```

### API Submission Errors

```javascript
fetch("/v2/api/endpoint.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(formData),
})
  .then((response) => {
    if (!response.ok) {
      throw new Error("HTTP " + response.status);
    }
    return response.json();
  })
  .then((data) => {
    if (data.success) {
      // Success
    } else {
      // API returned error
      console.error("API error:", data.error);
      alert(data.message || "Fehler beim Absenden des Formulars.");
    }
  })
  .catch((error) => {
    console.error("Network error:", error);
    alert("Netzwerkfehler. Bitte versuche es später erneut.");
  });
```

## Testing Checklist

- [ ] All required scripts loaded
- [ ] Scripts loaded in correct order
- [ ] UTM data collected correctly
- [ ] Form submission works
- [ ] GTM tracking fires
- [ ] Error handling works
- [ ] Email validation works
- [ ] Success states display correctly
- [ ] Mobile responsive
- [ ] Accessibility (keyboard navigation, screen readers)

## Related Documentation

- [Email Modal Component](EMAIL_MODAL_COMPONENT.md) - Complete email modal documentation
- [Email Modal Utils](EMAIL_MODAL_UTILS.md) - Utils reference
- [UTM Tracking System](UTM_TRACKING_SYSTEM.md) - UTM tracking documentation
- [GTM Form Tracking](GTM_FORM_TRACKING.md) - GTM tracking documentation
- [Lead Capture Component](LEAD_CAPTURE_COMPONENT.md) - Lead capture documentation