URL Parameters

Maizzle can automatically append custom parameters to your URLs.

Usage

To add the same parameters to all URLs in all Templates, use the environment config:

config.js

module.exports = {
  urlParameters: {
    _options: {
      tags: ['a'],
      qs: {}
    },
    utm_source: 'maizzle',
    utm_campaign: 'Campaign Name',
    utm_medium: 'email',
    custom_parameter: 'foo',
    '1stOfApril': 'bar'
  }
}

Front Matter

Of course, you may define URL parameters at a Template level, through Front Matter:

src/templates/example.html

---
title: "These URL params are unique to this template"
urlParameters:
  utm_source: custom
  utm_campaign: "Pre-launch August"
---

<x-main>
  <fill:template>
    <!-- your email HTML... -->
  </fill:template>
</x-main>

Options

Configure the tags to process and other transformer options.

tags

Type: Array
Default: ['a']

Array of tag names to process. Only URLs inside href="" attributes of tags in this array will be processed.

You may use CSS selectors to select only certain attributes. For example, this will apply parameters only to anchors that include example.com in their href value:

config.js

module.exports = {
  urlParameters: {
    _options: {
      tags: ['a[href*="example.com"]'],
    },
    utm_source: 'maizzle',
  }
}

strict

Type: Boolean
Default: true

By default, query parameters are appended only to valid URLs.

Disable strict mode to append parameters to any string:

config.js

module.exports = {
  urlParameters: {
    _options: {
      strict: false,
    },
    foo: 'bar'
  }
}

Input:

<a href="example.com">test</a>

Result:

<a href="example.com?foo=bar">test</a>

qs

Type: Object
Default: undefined

Options to pass to the query-string library.

For example, Maizzle disables encoding by default, but you can enable it:

config.js

module.exports = {
  urlParameters: {
    _options: {
      qs: {
        encode: true
      }
    },
    foo: '@Bar@'
  }
}

Result:

https://example.com/?foo=%40Bar%40

API

app.js

const {addURLParams} = require('@maizzle/framework')

const html = await addURLParams('<a href="https://example.com">test</a>', {utm_source: 'maizzle'})