Need Detailed Instructions for Creating Templates with Placeholders

[JMichaelTX (Jim Underwood)]

Running Script Debugger 6.0.4 (6A198) on macOS 10.11.6

###Need Detailed Instructions for Creating Templates with Placeholders

Mark (@alldritt) , I can see that you have provided us with a very powerful system to create templates. Many thanks for this.

I would like to take advantage of this but, sorry, I do not find the SD6 Help system to be very helpful in trying to learn how to create script templates using placeholders.

• I have become very frustrated after wasting about an hour with the Help system. (and now I’m spending more non-productive time writing this post). SD6 is supposed to be a great tool to make us more efficient, to do things quicker, but in this case I have to tell you that it fails in that respect.
  .
• I have searched the Help extensively, and read all of the sections on template, placeholders, and expressions, yet I still am unable to obtain a comprehensive understanding of how to do this.
  .
• There is much discussion in the Help system about using existing templates, clippings, etc, but very little about creating them.
  .
• The various terms are confusing and not clear when/where to use which:
  • clippings
  • clipping menu (where is it?)
  • expressions
  • placeholders
  • tokens

I think an example script which shows how to use all of these in creating templates would be very helpful.

---

###Here is what I get when I search Help for “template”

My first reaction is that I don’t want to “Choose” a template, I want to create one.

Finally, at the bottom of this page, it discusses briefly “User Templates”:

From the “Expressions” page, I don’t see how this is used with templates, given the definition provided:

An expression is a snippet of AppleScript code that has a value. Expressions are evaluated every time the script pauses.

So, I backup in Help, and finally discover this one line buried at the bottom:

I’m looking for “placeholders”, not “clippings”, but I follow this link anyway.

So then I see this Help page, which doesn’t seem to relate at all to templates:

So, initially I back up in Help and look elsewhere.
Finally, after much wasted time, I come back to here and discover this in the middle of the “Clippings” page:

It is still not clear if I can use this with templates, and if so, how I do it.
So, I make a guess and try using “[[template:text]]”

I find this works ONLY if put in quotes, like:

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

This will NOT compile:

set myString to [[template:text]]

For example, how do I create a placeholder that will be an AppleScript variable?
I tried these, but neither will compile:

	set x to [[select:Your Variable]]
	set x to [[template:Your Variable]]

What is the difference between using “select” and using “template” ?

How do I create placeholders in my template that will look like this when I create a new script using the template:

@alldritt, sorry for the rant, but I hope you find it helpful in understanding how (some) of your users find that the Help system is NOT very helpful, at least in some cases.

Perhaps you don’t intend for it to provide the type of detailed instructions I’m looking for. If so, then maybe it would be a good idea to put a link to external instructions/videos/examples in the Help system.

In the meantime, I’ll trying to “drain the swamp”, and need instructions on how to create placeholders in my custom script templates.

Thanks.

[JMichaelTX (Jim Underwood)]

Can I please get some help in doing this?

For example, how do I create a placeholder that will be an AppleScript variable? I tried these, but neither will compile:

set x to [[select:Your Variable]]
set x to [[template:Your Variable]]

What is the difference between using “select” and using “template” ?

How do I create placeholders in my template that will look like this when I create a new script using the template:

[sphil (Phil Stokes)]

Create a .txt file with BBEdit or TextWrangler whatever, that contains this:

set {[[template:theFirstVariable]], [[template:theSecondVariable]]} to {[[template:theSecondVariable]], [[template:theFirstVariable]]}

Save that text file into SD’s clippings folder (you can open it from here:

Next, create a new script, add your clipping, and save that as a template.

You should end up with something that looks like this:

’

EDIT: No, you’re right. This doesn’t work as expected when you create a new script with the clipping already saved in the template. Let me go back and have another go…

[sphil (Phil Stokes)]

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.

[JMichaelTX (Jim Underwood)]

Good news, and bad news, Jim.

Good news is it ain’t just you!

Thanks for confirming, Phil.

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

[alldritt (Mark Alldritt)]

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

[ShaneStanley]

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.

[sphil (Phil Stokes)]

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

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

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

[JMichaelTX (Jim Underwood)]

Firstly, clippings directives are not intended for use through Script Debugger’s scripting interface.

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

I like to think clippings files are fairly straight forward

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?

For script templates, it is more sketchy . . .

A gross understatement, don’t you think?

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 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:

For example, how do I create a placeholder that will be an AppleScript variable? I tried these, but neither will compile:

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?

[JMichaelTX (Jim Underwood)]

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.

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

[JMichaelTX (Jim Underwood)]

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.

[estockly (Ed Stockly)]

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.

[sphil (Phil Stokes)]

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

JMichaelTX:
For example, how do I create a placeholder that will be an AppleScript variable? I tried these, but neither will compile:

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

Next, create a new script, add your clipping, and save that as a template.

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.

[alldritt (Mark Alldritt)]

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.

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.

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.

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.

[JMichaelTX (Jim Underwood)]

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.

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.

[JMichaelTX (Jim Underwood)]

Running Script Debugger 6.0.4 (6A198) on macOS 10.11.6

Need Detailed Instructions for Creating Templates with Placeholders

Mark (@alldritt) , I can see that you have provided us with a very powerful system to create templates. Many thanks for this.

I would like to take advantage of this but, sorry, I do not find the SD6 Help system to be very helpful in trying to learn how to create script templates using placeholders.

• I have become very frustrated after wasting about an hour with the Help system. (and now I’m spending more non-productive time writing this post). SD6 is supposed to be a great tool to make us more efficient, to do things quicker, but in this case I have to tell you that it fails in that respect.

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.

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/Script%20Debugger%207.app/Contents/Resources/English.lproj/sd7help/indexfolder/developfolder/editfolder/editingafolder/clippingfolder/placeholder.html)

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 . . .

[JMichaelTX (Jim Underwood)]

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

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.

[ShaneStanley]

How can I create a placeholder picklist for the modifier keys

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

[JMichaelTX (Jim Underwood)]

You can’t. Picker placeholders are only available for the specific templates

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

[sphil (Phil Stokes)]

Picker placeholders are only available for the specific templates listed in the documentation: application

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!!