Create custom xCode File Template for iOS and MacOS (Swift 5)

Custom xCode File Template example

Introducing

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 ☺️

Problem

Create simple custom xCode file template for iOS and MacOS

Solution

Explore native xCode’s templates

First of all, I recommend to explore native xCode’s templates. Open Finder window and press Cmd+Shift+G  (or GoGo To Folder option in MenuBar)

Go to the folder window

Then paste the way:

For iOS:
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/File Templates/

Native xCode’s templates for iOS

For macOS X:
/Applications/Xcode.app/Contents/Developer/Library/Xcode/Templates/File Templates/Source

Native xCode’s templates for macOS X

They have a similar structure, but about this in a next step

Template structure

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.

New file.. dialog 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 file dialog 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)
For example ‘Swift file’ template

Required fields in TemplateInfo.plist

  • Kind (type: string) (The name speaks for itself) For ‘File Template’ it’s Xcode.IDEKit.TextSubstitutionFileTemplateKind
  • 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 (com.apple.platform.iphoneos, com.apple.platform.macosx)
  • 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 checkbox, text, static, combo box, popup.
    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:

Created folder

Then, download template example from here and put template folder into ‘My templates’. I created folders for both platforms. You should get the next:

Custom file template hierarchy

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.

Content of ‘Extension’ template folder
Extension template in create new file dialog window

Next, open 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.

IOS template’s ‘TemplateInfo.plist’
macOS X template’s ‘TemplateInfo.plist’

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

Result / how to use

An image below illustrates “Choose options for new file” window.

Creating new Extension file window

This is how created file looks like:

Created file

Conclusion

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:


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