↓Skip to main content

Creating Custom Xcode 4 File Templates

·5 mins

This post contains the material on custom file templates I had prepared for the book. I decided not to put this material in the book because it wasn’t strong enough for me to support. But information on creating custom file templates in Xcode 4 isn’t easily available so I’m making it available here. I hope it helps you create your own file templates.

File Template Contents

At a minimum a file template has the following items:

  • A folder with extension .xctemplate
  • A property list file TemplateInfo.plist
  • The file itself, which usually has the name _\_FILEBASENAME__ (triple underscores)

File templates can also include additional files, such as xib files and icon files.

The .xctemplate extension defines the folder as a template folder. The name of the folder is the name that appears in the list of templates for the selected category in the New File Assistant. The name of the folder is the name of the template.

The extension for the _\_FILEBASENAME__ file depends on the language. If you create a C, C++, or Objective-C template, there may be a second file for the header file.

Apple’s File Templates #

The easiest way to create a custom file template is to copy one of Apple’s templates and modify it to suit your needs. Apple’s file templates also provide good examples that you can study to help you build your own templates. Apple’s iOS file templates are in the following location:

Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/File Templates

The rest of Apple’s file templates are in the following location:

Developer/Library/Xcode/Templates/File Templates

Developer is where you installed Xcode. For Xcode 4.3 and later you can find Apple’s file templates in the Xcode application bundle. Select the Xcode application in the Finder, right-click, and choose Show Package Contents to access the files in the application bundle.

Making Changes to Existing Templates #

After creating a copy of one of Apple’s templates, you must modify the files to customize them. Open the _\_FILEBASENAME__ file and the TemplateInfo.plist file in Xcode to make your changes. I’m going to cover the keys in the TemplateInfo.plist file later in this post.

Moving the Template Folder #

For Xcode to find your file template you must move the template folder to the user templates folder, which is in the following location:

/Users/Username/Library/Developer/Xcode/Templates/File Templates/GroupName

You may need to manually create some of the folders in the path to the user templates folder. GroupName is the name of the category on the left side of the New File Assistant. You can create your own group name or use one of the built-in names. Your file template will appear in the GroupName category.

TemplateInfo.plist Keys #

The TemplateInfo.plist file has the following keys (this may not be an exhaustive list) for file templates:

  • AllowedTypes
  • CounterpartTemplateFile
  • DefaultCompletionName
  • Description
  • Kind
  • MainTemplateFile
  • MacOSXVersionMin
  • Options
  • Platforms
  • SortOrder
  • Summary

Your template does not have to use all these keys. The data type for the keys is usually one of the following: Array, Boolean, Dictionary, or String.

AllowedTypes Key #

The AllowedTypes key is an array that contains allowed file types. Source code file templates use this key. The following are examples of common allowed types:

  • public.objective-c-source (Objective-C)
  • public.objective-c-plus-plus-source (Objective C++)
  • public.c-source (C)
  • public.c-plus-plus.source (C++)
  • public.c-header (header file for C, C++, Objective C)
  • public.ruby-script (Ruby)
  • public.python-script (Python)
  • com.sun.java-class (Java .class file)
  • com.sun.java-source (Java .java file)
  • public.xml (XML)
  • public.source-code (generic source code)

Use the public.source-code type for languages other than the ones I listed.

CounterpartTemplateFile Key #

Only languages that have header files use the CounterpartTemplateFile key. Supply the name of the header file.

DefaultCompletionName Key #

The DefaultCompletionName key contains the initial name for the file. When you save the file for the first time, this name appears as the file name in the Save panel.

Description Key #

The Description key describes the file template. The contents of the Description key appear at the bottom of the New File Assistant when you select the file template.

Kind Key #

Text files have the following Kind key value:

Xcode.IDEKit.TextSubstitutionFileTemplateKind

MainTemplateFile Key #

The value of MainTemplateFile should be the name of the file in the .xctemplate folder. It generally has the following value:

___FILEBASENAME___.Extension(triple underscores)

Where Extension depends on the type of file you’re creating. For C, C++, and Objective-C files, the main template file is the implementation file, not the header file. The extension for an Objective-C file is .m.

MacOSXVersionMin Key #

The MacOSXVersionMin key is the earliest version of Mac OS X that can use the template.

Options Key #

The Options key is an array that lets you add controls to the New File Assistant. You can see an example of a custom control if you add an Objective-C class to a project. When you add an Objective-C class, there is a combo box that lets you choose the subclass. The combo box is an example of a custom control.

Create a dictionary key for each control you want to add. Add keys to the dictionary key. The following are common keys for controls:

  • Type identifies the type of control. Pop-up menus should use a value of popup. Checkboxes should use a value of checkbox. Text fields should use a value of text. Combo boxes should use a value of combo.
  • Name is the label for the control.
  • Description contains tool tip text for the control.
  • Identifier is a string that uniquely identifies the control.
  • Default is a string that provides a default value for a control.
  • Values is an array that contains the entries for a combo box or pop-up menu.
  • Required is a Boolean key that says whether a condition has to be true for the control to be enabled.

Platforms Key #

The Platforms key is an array of strings that identifies the platforms the template works on. A Mac file template has the following value:

com.apple.platform.macosx

An iOS file template has the following value:

com.apple.platform.iphoneos

SortOrder Key #

I’m not exactly sure what the SortOrder key does. I haven’t seen a sort order value other than 1 in Apple’s templates.

Summary Key #

The Summary key summarizes what the file template does. The summary is a shorter form of the file template’s description.