Code placeholders and Editable Template Tokens in Xcode
Forgive me for this next rather geeky section, but I found this to be very interesting and I am always looking for ways to improve my starter project code. I can appreciate that this might not be for everyone.
You probably already know that you can insert code placeholders in your Xcode project. This is particularly useful when you are creating code snippets. I have an entire video on this topic. It dates back to January, 2020, but the content is still relevant.
A code snippet is formed using the <#Placholder Text#> syntax. When you have a snippet in your project that has a placeholder, and you invoke the snippet, when you tab into the placeholder it become replaceable text. This is what you see when you use Xcode's code completion feature.
For example, if you want to get the basic format for a Switch statement, you can just start typing switch and then hit the tab key after selecting the Xcode code snippet and it will expand to provide you with the code with 4 placeholders. One for the value, one for a single case pattern and two for your code blocks. Tabbing will highlight each of the placeholders in your tint color and typing will replace the placeholder with whatever you type.
If you are interested in more about this, I recommend you check out my video.
The problem with these placeholders is that if you do not replace the placeholder with compilable code, your app will not build.
What I didn't know however was that there is another placeholder format that I was completely unaware of.
I discovered this when I was working through the Modern Persistence series using SQLiteData, on the Point•Free web site https://www.pointfree.co/ I will be talking more about SQLiteData in a future video. I am still working through the series and using it to build out a new app idea I have.
In their sample code, they use a lot of placeholders as well, but their placeholders were entirely different than the ones I was using. Their placeholders included code and the views in the starter projects compiled just fine. They were not using snippet here.
It turns out that these are editable template tokens generated inside code files.
What These Tokens Are
These comment blocks are interactive placeholders that Xcode inserts into generated SwiftUI files.
They mark spots where Xcode wants you to fill in something. They behave like the placeholders.
They are not runtime code and they never ship in your build. They exist only in the editor.
Why They Exist
Apple uses them in SwiftUI templates so Xcode can offer:
- Quick editing popovers
- Inline pickers (for example, system images, colors, layouts)
- Easy tab navigation when creating a file
- Structured editing (like when choosing a preview device)
They are basically the SwiftUI version of placeholders used in Interface Builder templates.
You see this every time you create a new SwiftUI file. The Text View with "Hello, World" is one of these tokens.
It is not until you tap on Hello world, it becomes selected and highlighted in your accent color (likely blue). If you tap enter on your keyboard, it will use the placeholder text that was provided. If you start typing it will replace the text with whatever you type.
If you want to create placeholders like this in your own code files, the syntax is
Text(/*@START_MENU_TOKEN@*/"Hello, World!"/*@END_MENU_TOKEN@*/)
Anything between the /*@START_MENU_TOKEN@*/ and /*@END_MENU_TOKEN@*/ is what becomes the placeholder.
You may wonder, why would I do that, when I could have just as easily typed:
Text(<#"Hello, World"#>)
Well that would not compile because the placeholder is including the quotation marks and the Snippet placeholder will not compile, whereas the same placeholder in a menu token will..
This is especially interesting for me because I want to share starter code with others and when they load the view, I want to make sure that it compiles without error. You cannot do this with simple placeholders or menu tokens without an additional argument that will allow you to specify a string for display of the placeholder, but behind the scenes, you can use code that will compile but never been seen by user.
Take a look at the following code. With normal snippet placeholders, this would not compile because all you are allowed are strings for the placeholder text.
What you can do is specify both a placeholder for a menu token as well as other compilable code or variables.
You still bookend your token with the same tags as before, but you also add a new argument to the token that is the placeholder for display purposes.
/*@PLACEHOLDER=placeholderString@*/
This is followed by the hidden compilable code that you want and it can be as simple as a variable or constant as a binding.
compilableCode
/*@START_MENU_TOKEN@*//*@PLACEHOLDER=placeholderString@*/compilableCode/*@END_MENU_TOKEN@*/
So, for example, the first token above is:
/*@START_MENU_TOKEN@*//*@PLACEHOLDER=someStateVar@*/observedVar/*@END_MENU_TOKEN@*/
It is the hidden observedVar that is a valid variable name that will compile without error.
The entire line of code is written like this where the token becomes just part of the complete line of code
@State private var /*@START_MENU_TOKEN@*//*@PLACEHOLDER=someStateVar@*/observedVar/*@END_MENU_TOKEN@*/ = false
The entire view is written like this:
