You can create an input in three places, depending on where you're working.
From the Inputs page
Click the Inputs icon in the navbar to open the Inputs page. This is your library of every input in your enterprise. You can see how each one is set up and which Dynamic Content uses it. Create an input here when you want to build it on its own, before connecting it to anything.
From the Dynamic Content editor
You can also create an input while building a piece of Dynamic Content. Type &: followed by a name for your new input, and it shows up in the list of inputs next to the editor, where you can click to set it up. See Using Inputs in Dynamic Content below.
From the input side panel
When you open an existing input from a query or a template, Matik shows it in a side panel so you can adjust it right there, without leaving what you're working on.
Note: Input names can only contain letters, numbers, hyphens (-), and underscores (_). As you type, Matik automatically turns spaces and most other characters into underscores, so you don't have to format them yourself.
Using Inputs in Dynamic Content
Inputs do their work inside Dynamic Content, where they act as filters that decide which data Matik pulls. For a full walkthrough, see the Dynamic Content Overview article.
To use an input, type &: followed by the input's name wherever you want its value to go. In the editor, inputs you've referenced appear in orange: an input that already exists has a solid underline, and a new one you haven't created yet has a dashed underline. Matik also lists your inputs next to the editor, where you can click one to create or configure it.
For example, typing &:account_name adds an input called account_name. Whatever the person selects for that input is then passed into the generated presentation wherever this Dynamic Content is used.
You can use the same &: + input name in SQL queries, API filters, and spreadsheets, so inputs can feed calculations as well as filters.
Note: If you write SQL queries, keep in mind that commenting out a line does not remove any inputs in it. An input inside a comment is still required at generation time. For example, in SELECT col1 FROM table1 -- WHERE col2 = &:input1, the person is still asked for input1, even though the commented-out WHERE clause never runs. To remove an input entirely, delete the &: or add a space between & and :.
Configuring an Input
Every input has an Input Format (how the user fills it in) and an Input Source (where its options come from). You can also give it a display name and a description.
Input Format
The Input Format sets what someone does with the input at generation time. The possible formats are:
| Input Format | How the user fills it in | How it's inserted into Dynamic Content |
|---|---|---|
| Text (Single Value) | Types a single value, or picks one option from a dropdown (when the options come from a list or your data). | A single value. Text is wrapped in quotes (e.g., 'Acme Corp'); numbers are inserted without quotes (e.g., 42). |
| Text (List) | Enters or picks one or more values (a multi-select dropdown when the options come from a list or your data). | A comma-separated list in parentheses, ready for an IN clause (e.g., ('Acme','Globex')). |
| Date | Picks a single date. | A single date value (e.g., '2025-01-01'). |
| Date Range | Picks a start and end date. | A BETWEEN clause spanning the two dates (e.g., BETWEEN '2025-01-01' AND '2025-04-01'). |
| True/False | Sets a yes/no (true or false) value. | The word TRUE or FALSE. |
Matik adapts the exact syntax to each data source — for example, the quote character or date format can differ. The one exception is when Use raw input value is turned on for a Text (Single Value) input: then Matik inserts the value exactly as typed, with no formatting. See Advanced Options.
Note: If the field you're filtering on stores a date and a time (a "datetime") rather than only a date, be aware of how your data source converts between the two. It might read 01/01/2025 as 2025-01-01T00:00:00 — that is, midnight at the very start of the day. To capture a full day of data, extend your range. For example, use 01/01/2025 - 04/02/2025 to include everything through the end of April 1.
Input Source
The Input Source decides where an input's options come from. Which sources are available depends on the format you chose:
- User Entry: There are no preset options — the user types their own value.
- Static List: The options come from a fixed comma-separated list, specified as part of input configuration. Available for the Text formats.
- A connected data source: The options are pulled live from one of your data sources through a query or API call. Available for the Text formats.
Note: The Date, Date Range, and True/False formats always use User Entry.
Display Name and Display Description
You can optionally set a display name and/or display description. These will be shown to the user in the inputs form when generating:
- Display Name: A friendly name shown in place of the input's name. If you leave it off, Matik shows the input's name instead.
- Display Description: A short note shown with the input to explain what to provide. Leave it blank to skip it.
Embedded (Dependent) Inputs
You can set up an input so its options depend on another input. This keeps choices short and relevant.
Imagine a company with 10,000 accounts and 100 sales reps. Without this, a rep would have to scroll through all 10,000 accounts to find theirs. Instead, you can connect an &:account_name input to a &:rep_name input. When someone generates a presentation, they first pick their name, and the "Account Name" input then shows only the accounts that belong to them.
Input Mapping
Sometimes the value your data needs isn't the value that makes sense to an end user. Input Mapping lets you show a friendly value while sending a different one behind the scenes. For example, your data might filter on a company_id, but most people don't know IDs — so you can let them pick a company_name while Matik quietly passes the matching company_id into your query.
To set this up, turn on the Input Mapping toggle, then pick a Display Field (what people see, like account_name) and an Inserted Field (what gets sent to your data, like account_id).
Input Mapping needs your query to return exactly two fields — one to display and one to insert.
For more, see the Input Mapping help article.
Setting a Default Value
A default value fills in an input ahead of time, so people don't have to set it themselves to generate a presentation — though they can still change it. It's helpful when an input usually uses the same value. The field is labeled Default Value (Optional) for most formats, and Default Value for True/False inputs.
- For Date and Date Range inputs, you can pick a fixed date or choose Relative to generation date, so the default shifts automatically based on when the presentation is created.
- For inputs powered by a query or API, the list of possible defaults refreshes when you save the input.
Note: A dependent input can't have a fixed default value. For a Text (List) input, you can instead default to selecting everything, or to no default at all.
Preview
The preview pane appears once the input’s required attributes are filled out. This preview shows you how the input will be presented in the input form to end users. For example, you can see how the form will display:
- The input name and (if applicable) description
- The format of the form component (for example, if it will be shown as a text box, or a dropdown, or a date picker, etc)
- The available input options, including applying settings like Input Mapping
When an input pulls its options from a query or API, Test API or Test Query to populate the options in the preview.
Query Results Settings and Advanced Options
These settings give you extra control over inputs that pull their options from a query or API. They are not required.
Query Results Settings
- Include NULL values: By default, Matik leaves empty (null) results out of the list. Turn this on to include them — Matik shows "No value" as a choice, and passes an empty value to your data source when someone picks it.
- Include first row of values: Turn this on if your data doesn't have a header row, so the first row isn't mistaken for one and dropped from the options.
Advanced Options
- Use raw input value: Inserts what the user enters into your query exactly as-is, with no formatting added. Use this for advanced use cases like passing table names or column references directly into a query. This is available only for the Text (Single Value) format.
- Allow user to override return value: Allows users to type in their own value(s), even if those options aren’t present in the list. Use this when you want to offer the user a list to choose from, but also give them the freedom to enter their own values.
Input Sync
Inputs that pull their options from a query or API refresh those options whenever the input is shown. Depending on how fast the query or API responds, the list can take a few moments to update — you'll see "Syncing inputs" next to the input's name while it does. If the value you need is already there, you can select it without waiting for the sync to finish.
User-Based Inputs
Matik can also use details about the person who's logged in and generating the presentation as an input. This is useful for tailoring the data to that person, or for dropping their information into a presentation. For more, see the User-Based Inputs article.
Best Practices
A few more ways to make inputs easier and more reliable to use:
- Give your inputs clear, friendly display names: This helps users understand exactly what to provide when they generate a presentation.
- Refine the list of input options as much as possible: Minimizing the number of values returned improves performance and makes it easier for users to find the relevant option in the list. You can use filters and dependent inputs to refine your input query.
- Use dependent inputs: Narrow the choices based on an earlier selection. This helps ensure end users do not need to wade through options that are not relevant to them.
- Prefer pulling options from your data: Build inputs on a query or API so their choices stay up to date automatically (like sales rep names from Salesforce), instead of typing lists by hand that can go out of date.
- Use Input Mapping: Use Input Mapping so users can choose from familiar names, while your query gets the IDs it needs behind the scenes.
Comments
0 comments
Please sign in to leave a comment.