Need Detailed Instructions for Creating Templates with Placeholders


(Jim Underwood) #1

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.


(Jim Underwood) #2

Can I please get some help in doing this?

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

(Phil Stokes) #3

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…

(Phil Stokes) #4

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.

(Jim Underwood) #5

Thanks for confirming, Phil.

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

(Mark Alldritt) #6

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

(Shane Stanley) #7

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.

(Phil Stokes) #8

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

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

(Jim Underwood) #9

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?

(Jim Underwood) #10

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

(Jim Underwood) #11

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.

(Ed Stockly) #12

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.

(Phil Stokes) #13

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.

(Mark Alldritt) #14

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.

(Jim Underwood) #15

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.