Updated for Xcode 12
Xcode template is an ability that allows developers to create projects and files with predefined files and structures automatically. Practically we can also define custom templates to reduce boring repetitive tasks but Apple explains almost nothing about it. Maybe they have not decided to release it publicly yet but I found it very useful in daily routines. So the following article is my findings based on my and the other’s trial and errors. For sure, these are not complete and you can help the community to make it more complete until Apple reveals it officially.
The Xcode templates are divided into two categories, Project templates, and File templates. When you create an iOS Single View App, you are using project templates and when you add a file to your project, for instance a Swift file, you are using file templates. Apple’s predefined project and file templates are stored normally in the following path:
/Applications/Xcode.app/Contents/Developer/Library/Xcode/Templates/
To go there fast, open Finder, press Command + Shift + G, paste the above path, then press return. To be honest, I have tried to reverse engineer the file templates to create my templates. One of the most complex file templates that you have used before in your projects is likely Cocoa Touch Class file template. To check its file templates source, look for that here:
/Applications/Xcode.app/Contents/Developer/Library/Xcode/Templates/File Templates/macOS/Source/Cocoa Class.xctemplate
Making Custom File Templates
Now I’m going to create a calss template that asks the name of the class during creation process and makes a Swif file with that class definition automatically. First of all, our custom file templates should be placed in the followding path:
/Users/<curren user>/Library/Developer/Xcode/Templates/File Templates
Your mac user name goes in <current user>. If that path does not exists, create it first. If you can’t see the Library folder, press the “Command + Shift + .” to see hidden folders. Then it is a good idea to use Apple’s templates as a template for our custom templates. To do so copy the Xcode Swift file template from this path:
/Applications/Xcode.app/Contents/Developer/Library/Xcode/Templates/File Templates/MultiPlatform/Source/Swift File.xctemplate
Paste it in the custom directory that I described earlier. Next change the “Swift File.xctemplate” name to “AEServiceProvider.xctemplate”. I added the AE prefix just for finding my templates easier in the list of Apple’s templates in Xcode. You can replace it with anything you want. Take a look inside the template folder. There is a Swift file which is called ___FILEBASENAME___.swift, two png files and a templateinfo.plist. The png files are used to show the temlate file icon in Xcode. The ___FILEBASENAME___.swift is the file that is created by Xcode. Xcode asks you for the file name at creation time and replace the ___FILEBASENAME___ with it. This is a simple Swift file that you can write your custom template codes there. In this example this code is like bellow to create a class with the specified name:
//___FILEHEADER___
import Foundation
class ___FILEBASENAME___ {
}Save or close the ___FILEBASENAME___.swift and try to create a file in a project. You will see that your file template has added to the list of file templates in Xcode.
You can find more about ___FILEBASENAME___ in the following Apple’s documentation:
Text macro reference
https://help.apple.com/xcode/mac/10.2/#/dev7fe737ce0
Text macro format
https://help.apple.com/xcode/mac/10.2/#/devc8a500cb9
Let’s play a little more. Add another Swift file to the AEServiceProvider folder and rename it to ___FILEBASENAME___Input.swift and replace its contents with the followings:
//___FILEHEADER___
import Foundation
protocol ___FILEBASENAME___ {
}also change the content of the ___FILEBASENAME__.Swift to
//___FILEHEADER___
import Foundation
class ___FILEBASENAME___: ___FILEBASENAME___Input {
}Again try to create an AEServiceProvider in a project. It creates a protocol and a class that conforms the protocol with the name you have specified. That is greate. If you are familiar with Clean Architecture, we have created a template for a service with an input boundary, automatically. But this is not all abut Xcode templates. There is a templateinfo.plist which is the engine of the Xcode templates. Remember when you try to create a Cocoa Touch class, you see a dialog with text input, drop down menus and a check box there. All of them are created by setting up the templateinfo.plist. Now suppose I want the AEServicePorvider to make a data madel structure for me. So I need to pass the name of that data model besides the service provider name. Again the best place to begin with is Apple’s templates. Open the Cocoa Class TemplateInfo.plist. There is an Options node which is an arry of items. Each item has different attributes that I can explain only some of them.
Identifier
It acts as a variable name for user input and can be used in the templates.
Default
The default value for the Identifier
Name
The title for the Identifier variable which is showed by Xcode.
Description
The description which is showed in Xcode when we place the mouse course on the item.
Type
The item can be boolean, text and popup
Note 1
An item with the “productName” identifier should be available allways. After defining options for a template, the value of the ___FILEBASENAME___ is infered by “productName” instead of a file dialog. The type also must be text for “productName”.
Note 2
you can can access the values of the identifier variables using this pattern:
___VARIABLE_identifier___
Now let’s add the data model file to our AEServiceProvider template. To do so, create the options section in the TemplateInfo.plist as illustrated in the following image:
Than add another Swift file to the templates with name ___VARIABLE_dataModel___.swift and with this code:
//___FILEHEADER___
import Foundation
struct ___FILEBASENAME___ {
}Now try to add AEServiceProvider again. This time you will see the following dialog which asks you for the service provider class name and data model name.
As another example I have created the following template structure for you to download and analyze. This template asks you for the name of three files. The name of a service, the name of the input protocol and the name of the delegate. Then it creates all files and also defines an instance of the delegate in the service automatically.
Download AEService Custom Template
Move the “AEService.xctemplate” folder into the following directory.
/Users/<current user>/Library/Developer/Xcode/Templates/File Templates/Ario
As I said before, if the above directory does not exist, makes it yourself. Aslo the “Ario” folder helps you to categories your custom templates in Xcode. Surely you can rename it to your own nickname!
To test this template, make a project, then press “Command + N” to add a new file. In the “Choose template dialog” select the “AEService”. Have a nice coding!
I hope you enjoy custom template feature as much as me. Feel free to wirte comments below here.