This article complements the QMod Developer Document and focuses on practical best practices for integrating QMod components into your site.

It covers:

Script & Loader Placement

Use HTTPS

Always use the HTTPS loader:

<script
  id="qmod"
  type="application/javascript"
  src="https://qmod.quotemedia.com/js/qmodLoader.js"
  data-qmod-wmid="YOUR_WMID">
</script>

  • Prevents mixed‑content issues.

  • Ensures browser security policies work as expected.

Position near the end of <body>

Place the loader near the bottom of your HTML, just before the closing </body>:

  • Ensures that your component <div class="qtool"> elements are present when QMod scans the DOM.

  • Avoids blocking your initial page render.

If you must load QMod in <head>, make sure:

  • Your component <div>s are added before QMod initializes (e.g., QMod is triggered after DOMContentLoaded).

One loader per page

Load the QMod loader script only once per page:

  • Multiple <script id="qmod"> tags can cause duplicate initialization and unexpected behavior.

Component Markup and Structure

Use the standard pattern

Each QMod component should follow this basic pattern:

<div
  data-qmod-tool="TOOL_NAME"
  data-qmod-params='{ "symbol": "GOOGL" }'
  class="qtool">
</div>

Key points:

  • class="qtool" is required (QMod uses this to find components).

  • data-qmod-tool must match the tool name from your QMod configuration.

  • data-qmod-params contains a JSON object with parameters.

One tool per qtool container

Keep one QMod tool per .qtool <div>:

  • Don’t nest QMod components inside each other.

  • If you need multiple components, use multiple sibling <div class="qtool"> elements.

Parameters, JSON, and Configuration

Ensure data-qmod-params is valid JSON

data-qmod-params must contain valid JSON:

  • Property names and string values must be in double quotes.

  • No trailing commas.

  • Properly escape any embedded quotes.

Valid example:

<div
  data-qmod-tool="detailedquotetabchartnews"
  data-qmod-params='{ "symbol": "T", "chfill": "aaaaaa", "chfill2": "111111" }'
  class="qtool">
</div>

If you need complex structures (arrays, booleans, nested objects), ensure JSON syntax is strictly valid:

<div
  data-qmod-tool="somecomplexcomponent"
  data-qmod-params='{
    "symbol": "AAPL",
    "studies": ["sma50", "sma200"],
    "showNews": true
  }'
  class="qtool">
</div>

Use the QMod Developer Utility

Whenever possible, use the:

to:

  • Discover supported parameters and defaults.

  • Test configurations.

  • Copy working parameter JSON directly into your integration.

Styling, Theming, and Responsiveness

Control layout with CSS, not inline attributes

  • Avoid hardcoding width/height inline.

  • Use CSS classes and responsive layouts to control how QMod components fit into your design.

Example:

<style>
.my-qmod-container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
}
</style>
<div class="my-qmod-container">
  <div
    data-qmod-tool="technicalchart"
    data-qmod-params='{ "symbol": "MSFT" }'
    class="qtool">
  </div>
</div>

Start from base CSS and then customize

  • QMod’s default styles are intentionally minimal.

  • Override classes with your own theme:

    • Fonts, colors, spacing, borders.

    • Hover states, focus styles, etc.

Tip: Use browser dev tools to inspect elements and see which QMod classes to override.

Performance and Loading Behavior

Minimize the number of heavy tools per page

Some tools (e.g., advanced charts, screeners) are more resource‑intensive:

  • Limit the number of heavy components on a single page where possible.

  • Consider lazy‑loading non‑critical tools below the fold or in hidden tabs.

Prefer a single QMod loader per site shell

If your site uses a common layout (e.g., SPA shell, portal header/footer):

  • Load QMod once in the shell.

  • Swap or mount different QMod components as the user navigates.

Error Handling and Failover

Let QMod fail gracefully

QMod is designed so that:

  • If a component fails to load, your page still renders.

  • The component area may display an error state or remain empty.

As best practice:

  • Ensure your layout looks acceptable even if a component doesn’t render (e.g., no massive blank sections breaking layout).

  • Consider adding surrounding copy or headings that still make sense without the widget.

Use browser dev tools during integration

When something doesn’t work:

  • Check Console for JavaScript errors (JSON parsing, invalid params, etc.).

  • Check Network tab for failed requests to QMod / QuoteMedia endpoints.

Accessibility Considerations

Many QMod tools support accessibility‑focused behaviors and ongoing work towards WCAG 2.1 AA.

Best practices:

  • Ensure your page provides sufficient contrast, keyboard focus outlines, and readable fonts for embedded components.

  • When available, use accessibility‑related parameters/flags documented for a given tool.

  • When customizing templates:

    • Preserve or enhance semantic HTML structure (e.g., use <table>, <th>, <tr>, <td> appropriately for tabular data).

    • Maintain proper heading levels and ARIA roles where provided.

When in doubt, test your implementation with keyboard only (no mouse) and with a screen reader to confirm that QMod components remain operable and understandable.

Security, Entitlements, and Environments

Use the correct environment for your stage

  • Integrate against the environment specified in your onboarding docs (e.g., production vs sandbox).

  • Keep configuration (WMIDs, keys, environment URLs) in a central config so you can easily switch between test and production.

Respect entitlements and access controls

For premium content (authenticated watchlists, portfolios, premium data):

  • Coordinate with QuoteMedia to understand:

    • Domain restrictions.

    • Any token or referrer checks.

    • How user entitlements are enforced.

  • Ensure your site enforces appropriate authentication/authorization before exposing premium QMod tools.

Testing and Troubleshooting

Test with realistic symbols and use cases

  • Use representative symbols (e.g., active equities, ETFs, FX pairs) that match your intended market coverage.

  • Verify edge cases:

    • Halted symbols.

    • Delisted/invalid symbols.

    • Empty or missing data sets.

Check multiple browsers and devices

  • Confirm layout, scrolling, and interactions in:

    • At least one modern Chromium browser, Firefox, and Safari.

    • Mobile and tablet views.