Need Detailed Instructions for Creating Templates with Placeholders

Good news, and bad news, Jim.

Good news is it ain’t just you!

Bad news is I couldn’t figure out how to save a clipping into a template either. When you save as a template, it’ll automatically compile, and then you lose the placeholders. There must be a way to do it, because some of the built-in templates open with placeholder, but I guess we’ll have to wait for Shane or Mark to reveal the secret.

And I agree, the Help is not much help, either.

1 Like

Thanks for confirming, Phil.

I look forward to hearing from Mark and/or Shane.

Firstly, clippings directives are not intended for use through Script Debugger’s scripting interface. They are limited to two contexts: creating new scripts via templates and inserting clippings.

I like to think clippings files are fairly straight forward and we provide lots of examples you can examine within Script Debugger’s Clippings directory (~/Library/Application Support/Script Debugger 6/Clippings).

For script templates, it is more sketchy. Firstly, if you intend to use clippings directives within the code of your template, your template must be a .applescript (i.e. text) file. This is because the syntax of clippings directives results in invalid AppleScript statements. Only with a text script file can you avoid the need to compile the script before saving it.

Here are the steps:

  1. Create a new script

  2. Change its format to Text (File > Script Format > Text)

  3. Create your template, for example:

    use AppleScript version "2.4" -- Yosemite (10.10) or later
    use scripting additions
    set [[linked-template:abc]] to [[linked-template:abc]] + 1
    display dialog "Abc: " & [[linked-template:abc]] buttons "OK" default button "OK"
  4. Issue the File > Save as Template command

There’s one other context they are used in that’s slipped Mark’s mind: Text Substitutions. There are several examples in the default set, many of them not enabled by default.

Yeah, that was the missing step for me, thanks.

I still think Jim has a point that the Help doesn’t make this clear.

I have no idea what that means.
What other interface is there for SD other than the scripting interface?

You may like to think that, but then you know SD inside/out.
New users do NOT.
How would a new user even know where the Clipping menu is?
You don’t tell us or show us in the Help system.
How would anyone know this is the Clipping Menu?

A gross understatement, don’t you think?

This is not practical.

Surely it is obvious to an experienced AppleScripter like yourself that one would need to compile a script, and test, before saving as a template.

I don’t think you have yet answered my original question:

Why is it that this works:

set myString to "[[template:text]]"

but this does not?

set myString to [[template:text]]

Frankly, I don’t think your template system is very well thought through, from an end-user’s perspective. Or maybe it is just not properly documented.

Do you plan to make the Help system more helpful?

I have no idea what this means.
Can you please elaborate?

Mark (@alldritt) and Shane (@ShaneStanley),

I think that, while you guys are brilliant, you often fall into the age old developers trap: It is very hard for the developer of a system to have the perspective of a new user to their system. In fact, it may be impossible.

What may be extremely obvious to you may not be clear at all to new users, or even to experienced users who are trying a new feature for the first time.

My 2 ¢:

Script Templates is not something for beginners, and neither are writing and using placeholders.

I agree that using placeholders in Script Templates could be better documented. I didn’t think it was doable and now that I know it is it makes templates much more attractive.

Go back to my first post in this thread, Jim. Do what I said before only when you get to this step:

before saving it as a template, go File > Script Format > Text

Then File > Save As Template…

I had no problems getting this to work doing it that way.

I agree. It is for this reason that I never write documentation for my own software. I accept that the information in the Script Debugger help guide can be improved. But, the scope of the information presented is for clippings and text substitutions. We do not document the nature and inner workings of script templates.

I apologize for all the time that you’ve wasted trying to make this work. I can appreciate how frustrating it must be.

While I will do what I can here to help you be successful creating script templates, the official user-level interface for creating templates is the Save as Template command. You can lift the curtain and edit the templates directly to take advantage of other SD capabilities, but when you do so you are moving beyond what we document.

Script templates are very hard to create. There is a lot about them that I do not document because it is difficult, even for me, to use. As I say, I will do what I can here to help you succeed.

So, lets start again. If you want to introduce clippings directives into the code of your script template, then you must accept that your template will no longer compile. This is an unavoidable consiquence of the conflict between SD’s clippings pre-processor syntax and AppleScript. I accept that this makes debugging extreamly difficult. I suggest you approach this in two stages:

  1. the creation and maintenance of a runnable template script. This is where you will iterate over your template’s design to ensure it does what you want.

  2. the, probably mechanical, introduction of [[template:...]] tags into a text version of your template script. It is this derived version of your compilable template script that you install into the SD Templates folder.

1 Like

Mark, thank you very much for this post. Your statements here, and the two steps you provided to make the template creation/edit process work with the constraints of SD and AppleScript, are very helpful.

I think if these statements had been in the Help system, in a page dedicated to “Templates”, it would have saved me much time and frustration.

I will start again with my template creation/edit process using your guidelines, and see if I can work out a clear, streamlined process. If I can, then I will try, when I get time, to write an article, maybe create a video, that will hopefully help others more easily understand how to do this.

Thanks again.

Mark @alldritt, well it is a year later, and a SD version later, and, as far as I can tell, no improvement in the documentation for creating:

  • Templates
  • Placeholders
  • Expansion Tags
  • Clippings

I just re-read the Clippings>Placeholders>How clippings Work circle until my head burst. I don’t mean to be mean, but you need to know that from the perspective of anyone who doesn’t already understand all of that, this is among the worst documentation I’ve ever sceen. Sorry to be blunt, but I need to be clear.

There is a endless recursive loop referral in this: Clippings>Placeholders>How clippings Work

I am pretty good at writing clear documentation once I understand the subject matter. If you (or someone) will work with me offline to understand this mess, I’ll do my best (at no charge) to give you documentation that you can use as you see fit.

I can tell this is a powerful system – I just need to understand it.

I have one primary use case that may help you understand my dilemma. I use Typinator a lot, and rather than try to build snippets in every app, I build them in Typinator – then I can use everywhere, and I have only one system to learn. :smile:

So, for example, I’m trying to write a Typinator snippet that will use “picker placeholders”. I can’t get any info from SD7 Help on how to create these. This is all it says:

FROM: [SD7 Help File](file:///Applications/

Special placeholders
Some placeholders have a special appearance.

A placeholder with a down-pointing chevron is a picker. It produces a pop-up menu of items that you can choose from to replace the placeholder. For example, the “application” placeholder here is a picker; its pop-up menu is the same as the list of running, recent, and favorite applications that appears elsewhere:


Can you please tell me how to create a picker placeholder in a text file?

I have learned by reverse engineering how to create a “normal” placeholder in plain text, that when pasted into SD7 works:

set msgStr to "#~Replace with MESSAGE~#"

It would be really great if you would document stuff like that in the Help file (or somewhere). What are the options/formats for creating placeholders? Even the unix man manual is better than this. LOL

I mostly love SD7, but there are a few things . . . :wink:

Mark, let me give you a concrete example. How can I create a placeholder picklist for the modifier keys to be used:

	tell application "System Events"
		keystroke "m" using {#~Choose Zero or More: <option down, command down>~#}
	end tell

I’d like a popup picklist for the modifier keys, with an option to pick one or more. Can this be done.

Here’s a bad mockup, but I think you’ll get the point.


You can’t. Picker placeholders are only available for the specific templates listed in the documentation: application, applicationid, applicationhfs, applicationposix, library, and framework.

Too bad. I’ll have to see if another tool can do this then.
Any chance you guys could add this feature to SD?

Hah! Cool. I’d never noticed that in all the times I’ve used the “ta” shortcut (which is probably every single time I use SD).

I was also just going to say “unfortunately, I’d never use it as it means taking my hands of the keyboard”, but a quick trip to the docs told me that you can activate the picker’s menu with ‘esc’ or ‘return’. Doubly-cool!! :+1:

It is amazing how different each of our experiences is with SD. After a few “misfires” with SD Text Expansion, I turned it off. As a result, I never discovered the “ta” shortcut expansion.

But you’re right – it is very cool! And I just thought of an extension of this expansion, which I often use in UI scripting:

tell application "System Events"
  tell application process "#~application~#"
end tell

We do have a feature request section here…

FWIW, user-defined pickers are something I’d find handy. But it would involve a fair bit of work, and until now no-one has asked.

But before you get too excited, a couple of things:

  • The expansion tags are designed for use in clippings and text substitutions, not direct entry. Some of them can be reproduced using #~ and ~#, but not all, and that’s an implementation detail that could change. You’re of course free to use it, but we’re also free to change it.

  • Pickers are implemented as popup menus similar to contextual menus. And like contextual menus they have no prompt text, and they don’t have any concept of multiple selection — they are not tables. So your specific example can’t be implemented as a picker.

That’s why I like focused forums! :wink: I can learn a lot.

But yes, “ta” + return(twice) + Fi (the menu has type selection, another bonus) + tab and you’ve got this in half a dozen keystrokes:

tell application "Finder"
	#~-- your code goes here...~#
end tell