Using placeholders
A placeholder is a question you leave in a template. Write {{client_name}} where a client's name
belongs, and Prefab asks you for it once as the folder is created, then writes your answer
everywhere the placeholder appears.
Three words come up throughout these pages. The placeholder is what you write into the
template. The key is the name between the braces, client_name. The value is what you type
at deploy time, and what ends up on disk.
The syntax
Two braces either side of a key: {{client_name}}. A key can hold letters, numbers and
underscores, and has to start with a letter or an underscore. Case matters, so {{client}} and
{{Client}} are two different placeholders.
Prefab replaces only the keys it has a value for. A misspelt {{clientnme}} reaches the disk as
{{clientnme}} rather than as an empty gap, which is usually how you notice.
Where placeholders work
The same placeholder can appear in any of these, as many times as you like:
- Folder names
- File names
- The contents of text files
- The Finder tag names a folder is given (macOS only, but they travel)
- The text of a terminal command in an action
Files that Prefab stores whole - images, .docx, anything that isn't text - are copied byte for
byte, so a placeholder written inside one is not replaced. See
Files and contents.
Answering them at deploy
If a template has placeholders to ask about, Prefab shows a prompt headed Create from and the template's name, with one field per placeholder. The label sits above the field, help text below it, and an asterisk marks a placeholder you have to answer. Create builds the folder.
The field matches the placeholder's input type. A Selection placeholder becomes a pop-up of its options, Yes/No becomes a checkbox, and Multi-line Text becomes a box you can type paragraphs into. Every other type is a single-line text field.
Leave a field empty and Prefab uses the placeholder's default value instead. A placeholder marked required with no default to fall back on is different: Create does not close the prompt, and the text at the top names what is still missing.
The four built-in placeholders - {{date}}, {{year}}, {{author}} and {{folder}} - are never
part of the prompt, because Prefab already knows their values. See the
placeholder reference.
A template with nothing to ask about deploys straight away, with no prompt at all. So does a deploy
link carrying prompt=0, which uses each placeholder's default value so that a scripted deploy
always produces the same folder. A placeholder with no default resolves to nothing on that path -
the braces are removed and nothing takes their place. See
Deploy links.
When a template embeds another one, the prompt asks for both sets of placeholders together, so nothing nested is left unfilled. See Templates inside templates.
Defining a placeholder
Placeholders belong to the template that uses them, and live in its Placeholders tab.
The tab sits between Structure and Automation.
Add Placeholder adds a blank one for you to fill in. The Presets menu beside it adds a ready-made placeholder instead - Client Name, Project Name, Matter Number and sixteen others - with its key, label and input type already chosen.
The key is the text you type between braces. The label is what the prompt shows above the field, so write it as a question you would want to be asked.
Type the key in braces - {{client_name}} - into a folder name, a file name or a file's
contents. Each row in the list has a copy button that puts the placeholder on the clipboard,
braces and all.
Key and label
The key is machine-facing and the label is human-facing, and they are worth keeping distinct. A key
of matter_number with the label "Matter number" reads well in both places. Changing a label
changes only what the prompt says. Changing a key means changing every {{matter_number}} that
refers to it.
Default value
The default value is what the field starts with, what Prefab falls back on if you leave the field
empty, and what a deploy that never prompts uses. Set it to the answer that is right most of the
time - a version of 0.1.0, a licence of MIT - rather than leaving it blank.
Hint text and help text
Hint text is the grey text inside an empty field. It is a suggestion, not a value, and nothing is written to disk if you leave the field alone. Help text is a line of explanation under the field, for anything the label alone cannot carry.
Required
A required placeholder is marked with an asterisk at the prompt. If it also has no default value, the prompt refuses to close until you fill it in. Turn Required off for a placeholder that is reasonable to skip.
The Presets menu in the Placeholders tab adds a ready-made placeholder. A value preset is a saved set of answers you apply at the deploy prompt. They are unrelated.
Placeholders Prefab finds for you
You do not have to define a placeholder before using it. Prefab reads the whole template - folder names, file names and file contents - and lists anything written in braces that nothing defines, under Suggestions at the foot of the Placeholders tab.
Create turns a suggestion into a real placeholder. The label is made from the key, and the
input type is guessed from it: a key containing date becomes a date, email an email address,
url or link a URL, and number, count or amount a number. Everything else becomes plain
text.
Anything already accounted for is left out, so built-ins and global placeholders never appear as suggestions.
Reshaping a value
A placeholder can carry a transform, written after a colon: {{client_name:kebab}} turns
Acme Rebrand into acme-rebrand. The same value can go into a folder name one way and into a
file's contents another. There are six of them, and they work anywhere a placeholder does. They
are listed in the placeholder reference.
When the same answer keeps coming up
A placeholder you write in more than one template is better defined once, in Globals, than copied into each of them. And a set of values you always type together - a client's name, their reference, their contact - can be saved as a value preset and applied to the prompt in one go.