Like any developer who has written more than one project, you often create a similar files or copy already written code from previous projects over again. But if you heard anything about custom xCode file template you would know how it can do your life easier.
Thus sometimes you should set aside time once to avoid
monkey-job routine in future.
This article should explain how to create custom xCode File Template.
If you don’t want to dive deep you can download template here and just use it ☺️
Explore native xCode’s templates
First of all, I recommend to explore native xCode’s templates. Open Finder window and press
Go To Folder option in MenuBar)
Then paste the way:
For macOS X:
They have a similar structure, but about this in a next step
So, (as you can see in native folders), all templates have
.xctemplate file extension. Name of this folders are displayed as name of template in xCode window.
Required files in .xctemplate folder
Each file template folder must contain at least 3 files (for describing in templates window):
TemplateInfo.plist– responsible for describing the template window
TemplateIcon.png– icon shown in the Xcode in
New filedialog window
___FILEBASENAME___.swift– the actual template file what will be created. Template file can be any another type (.swift, .h, .m, .xib, .storyboard…). Of course, you can create more than one. (For example, Cocoa Touch Class can create two files at once: subclass of UIViewController with .xib file)
Required fields in TemplateInfo.plist
- Kind (type: string) (The name speaks for itself) For ‘File Template’ it’s
- Description (string)
- DefaultCompletionName (string) the default name of file (without extension).
- SortOrder (number) used to rearrange the order in a category.
- Summary (string)
Optional fields in TemplateInfo.plist
- Platforms (array) By default the template will be available for all platforms. If you want your template only for one platform you should define this (
- MainTemplateFile (string) In case a template has more than one file, MainTemplateFile specify which file should be opened first after template’s files has been created.
- DefaultCompletionName (string)
- Options (array) determine the options what you can configure in the first step of creating a new File.
Few possible Options keys for generating own creating new file window
If you decide configure own “Choose options..” window you should get to know about Options. If your .plist have no Options, “Choose options..” will be skipped.
Primary item that you must add, is an option (with text type) with Identifier ‘productName’. Otherwise, the future file won’t be created.
- Default (string) selection or text.
- Description (string) of option. You can see the text when the mouse hovers over the option.
- Identifier (string) are used to uniquely identify options. You can use them for creating references for using in other options or template file.
- Name (string) Text is shown on the left side of the control.
- Required (bool) – determinate is option a required. If a Required option does not have a valid value the Next button on dialog window will be unavailable.
- SortOrder (number) determinate position of option. By default they are displayed in the same order as their position in the Options array.
- Type (string) of option. Eg
NotPersisted (bool) determinate is the value that will be saved for the next time.
RequiredOptions (dictionary) are referenced an another options required values, otherwise, its option is grayed out.
Values (array) using for defining option of combo box.
Creating own template
First of all, you should create a folder for your template.
It’s not recommended to modify existing Apple’s templates or create your own custom templates in the same location as native templates. Consequently, you have to create the folders where you can put own custom Templates (named “File Templates” and “Project Templates” respectively). By default, the folder doesn’t exist on your system.
You have two ways to do this:
- Using Finder open
~/Library/Developer/Xcode/Templates/File Templates/, then create new folder (in this article it’s named “My templates”)
- Open Terminal and do next command:
mkdir -p ~/Library/Developer/Xcode/Templates/File\\ Templates/My templates
As I mentioned above it is suitable for both platforms (iOS and macOS X).
Result should be like this:
Then, download template example from here and put template folder into ‘My templates’. I created folders for both platforms. You should get the next:
As I said before, Name of folder (screenshot above) contained your template is a category name which will be displayed in section of creating new file window (screenshot below). It means you can create your own folders hierarchy.
In our case it’s “Helpers” folder.
TemplateInfo.plist and explore its structure. “Choose options for your new file” window will contain a one class type field (as I understood it’s a subtype of combo box) and one static field, in spite of ‘Options’ has a 3 items. First one is a ‘productName’ item, as I mentioned above, this option affects the name of the file and will not be shown in a template window. Empirically I got that if template contains ‘class’ option, .xctemplate have to contain a folder named as ‘Default’ value of class type option item. In ‘Values’ you can enumerate preferred classes. The last option is static type is a name preview of created file.
What about template file?
As I mentioned previously, template file can be any allowed type.
You can use text macros and the Option Identifier key to create a Variable Placeholder which will be replaced by the relative text.
Full list of all macros is available here
Example of using variables macros:
Here you can see
___VARIABLE_subclassName___ that defined in
Сustom xCode File Template at work
An image below illustrates “Choose options for new file” window.
This is how created file looks like:
Even more, one common reason to spend time on creating xCode Templates is usage Design Patterns which requires creating a lot of files at once and setting up references between them.
Also you can create Project Templates for setup new needed files and directories for new projects.
That’s it, about creating custom xCode File Template.
I hope you learned something useful from this article.
You can download source files from here
Check my previous articles:
- Handling Internet Connection reachability in iOS (Swift 5)
- Basic typography design system for iOS using Swift
- iOS Localization Advices (Swift 5)
You may check my apps.
If you have any questions or spot any errors please let me know.
Thanks Miloskiy for template icon.
Written with ❤️ by Rita