Settings forms

A snippet can have a settings form: a few fields, such as a colour, an ID or a list of redirects, shown above the code. The code reads the values, so you (or a client) change what the snippet does by filling in the form, not by editing code.

Every generator makes a snippet with a settings form. With Snipfire Pro you can add a form to any snippet yourself.

The Settings form and Code tabs #

A snippet with a settings form opens on its form. Two tabs above the editor switch between Settings form and Code.

Change the values and click Save, as for any change. The form says how the code reads the values, and reminds you: Save to use the new values. Saving runs the usual checks and, for a snippet that's on, a test load of your site. Each save is kept in the snippet's history, values included.

Field types #

A value that doesn't fit its field is cleaned when you save: a choice that isn't in the list, a colour or address in the wrong form, or HTML in a text field is dropped.

A snippet can have up to 50 fields. Each field has a key that the code uses: lowercase letters, numbers and underscores, starting with a letter, up to 40 characters.

Using the values in code #

In PHP: $settings #

$settings holds every field of the form. A field without a value has its default, or else an empty value: false for on/off, an empty list for checkboxes and rows, '' for the rest. Numbers are numbers, on/off is true or false, checkboxes are a list of the ticked values, and rows are a list of arrays keyed by column.

// Fields: message (text), show_to_guests (on/off)
add_action( 'wp_footer', function () use ( $settings ) {
    if ( is_user_logged_in() || $settings['show_to_guests'] ) {
        echo '<p class="notice">' . esc_html( $settings['message'] ) . '</p>';
    }
} );

Inside a function you hook in, add use ( $settings ), as above. Escape values before printing them, as with any input.

In HTML, JavaScript and CSS: {setting:key} #

{setting:key} is replaced with the value, escaped for where it lands:

• HTML: HTML-escaped. Checkboxes and rows are joined with commas; on/off is 1 or empty.
• JavaScript: text is escaped for use inside a string, so put quotes around it: '{setting:message}'. Numbers go in as numbers, on/off as true or false, and checkboxes and rows as JSON.
• CSS: characters that could end the rule or the stylesheet (;, {, }, <, >, \, */, line breaks) are removed.

/* Fields: accent (colour), radius (number) */
.button {
    background: {setting:accent};
    border-radius: {setting:radius}px;
}

{setting:…} works whether or not smart tags are switched on. A key that isn't a field of the form is left as it is.

In SCSS and LESS Pro #

The values arrive as variables before your code, so you use them like your own:

// Fields: accent (colour), rounded (on/off)
.button {
    background: $accent;
    @if $rounded { border-radius: 6px; }
}

Numbers and colours are plain values, on/off is true or false, an empty field is null, and everything else is a quoted string. Checkboxes and rows aren't available as variables. The live preview uses the form's current values too.

Add fields to any snippet Pro #

With Snipfire Pro, the settings panel of every snippet ends with Settings form: Fields shown as a form above the code, for you or a client.

1. Click + Add a field.
2. Fill in the Label. The Key (used in the code) follows the label until you change it yourself.
3. Pick the Type. For a choice or checkboxes, list the Choices, one per line (value: Label). For rows, list the Columns, one per line (key | Label | type).
4. Optionally set a Default value (or On by default) and a Help text, then click Done.
5. Save the snippet. It now opens on its Settings form tab.

Click a field to change it, ↑ to move it up, and × to remove it.

Let clients change the values, not the code Pro #

A settings form is a safe way to hand part of a snippet to someone who shouldn't edit code. With Snipfire Pro's team access, people with the CSS, JS and HTML (no PHP) level can change the values of a snippet they can't otherwise edit, such as a PHP snippet:

• The snippet opens read-only, on its form, with You can change these settings; the code stays as it is. and a Save settings button.
• Save settings saves only the values. The code, the fields, the location and the conditions can't change this way; the server makes sure of it.
• The save is checked and, for a snippet that's on, test-loaded like any other, and kept in the history (and the activity log).

People with View only access see the form but can't change it.

Think about what a value can do before you hand it over: a Redirects form, for example, lets whoever fills it in send any address on your site anywhere.

Without Snipfire Pro #

Settings forms themselves are part of the free plugin: snippets made with a generator, imported, or synced from a site with Pro keep their form, and their code keeps reading the values. You need Pro to add or change fields in the editor, and for values-only saving.

From the command line and the API #

The fields and values are the snippet's fields and values, in WP-CLI, the REST API, abilities and exports:

wp snipfire create --title="Promo bar" --type=html --hook=wp_body_open \
  --fields='[{"key":"message","label":"Message","type":"text","default":"Free shipping this week"}]' \
  --code='<div class="promo">{setting:message}</div>'
wp snipfire update 12 --values='{"message":"Sale ends Sunday"}'

values replaces all the values at once: a field you leave out goes back to its default. Send every value you want to keep. The field format is in Snippet fields.