Query parameters allow you to pass values to a Cameo form via the URL of the page it is embedded in. This allows a form to change its behaviour accordingly. Cameo forms let you customise the names of query parameters they can use. In many cases you can also set a default value for use when the URL does not provide a query parameter.

The structure of a URL with query parameters can be quite complicated. Unfortunately Cameo cannot control this: it is how they are specified.

Query parameters are the part of a URL which appear after a ?. Each looks like this:
            name=value
When there is more than one query parameter name/value pair, they are separated with an ampersand: &. For example, this URL has two query parameters called first and last:
            https://example.com/page/?first=Jiminy&last=Cricket

Common uses are to provide defaults or to personalise the form.

Forms which use query parameters allow you to give their names and default values (when the query parameter is not present in the URL). We recommend not changing names unless it is essential: for example, if your website already uses the same name for something else.

Query parameter names should only use alphanumeric characters or underscore1.

Cameo forms query parameter defaults are used when the query parameter is not provided in the embedding page’s URL.

Percent encoding

Query parameter values (the parts after the =) in a URL represent most non-alphanumeric characters by % followed by a 2-character code. This is called encoding or, more specifically, percent-encoding. It’s needed2 to avoid clashing with characters like ? & = % #. These have special meanings in a URL.

For example, a space is represented by %20. Some symbols, emoji, accented and non-Latin characters need more than one. For example, â is represented by two: %C3%A2 and the emoji 🎁 by %F0%9F%8E%81.

You don’t need to know where the numbers come from3, just that they are needed when you construct URLs by hand for the page embedding the form. You may find this encoder useful.

A further example: Jiminy Cricket's Friend would appear in a query parameter called person in a URL like this:
https://example.com/page/?person=Jiminy%20Cricket%27s%20friend

Incidentally, don’t try to encode default values in Cameo’s query parameter naming form: Cameo deals with that for you.

Footnotes

1 While URLs in general can have other characters for query parameter names, they must be percent-encoded. However, Cameo restricts the names you can use.

2 While strictly speaking only these characters should be encoded:
            ! * ' ( ) ; : @ & = + $ , / ? # [ ]
in practice,

  • most browsers will only have a problem with characters that are special in the context of query parameter values,
                ? & # % =
    so a comma, for example, would be OK, even though it really should be escaped, and
  • to avoid portability and email app problems, anything unusual is better encoded.

3 The numbers are actually the byte values in hexadecimal of the string represented in the UTF-8 encoding of the universal Unicode character set. But really, just use an online encoder.