Creating Custom Xcode 4 File Templates
November 17th, 2011
Filed under: Xcode
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.
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.
Tags: xcode 4
I never saw MacOSXVersionMin yet, however I’d met its counterpart MacOSXVersionMax.
In the “Objective-C class legacy.xctemplate” (for Mac OS X) it is now set to 10.6.99.
Oleg,
Most of Apple’s templates do not use MacOSXVersionMin. The templates that replace the legacy templates you mentioned are the ones most likely to use MacOSXVersionMin.
Hello, I am making an SDL game for the Mac and I am trying to figure out how to hide my application without using objective-c code. Is this possible? Right now I have SDLmain.m set up to use a nib (just menu bar) and I make my own window. Is there a way to recode the SDLMain.m to tell it that I want to use a xib file that has both the menu and window? Even if I can do this will I be able to hide my application at anytime during gameplay?
Thanks,
Mark Vaughn
Mark,
Choosing AppName > Hide AppName hides the application for me, but it does not pause the game. If you’re using a xib, you would need to add a call to pause your game in the code that gets called when choosing the Hide menu.
I don’t know if it’s possible to tell SDL to use a xib file that contains both a menu and a window. I haven’t tried it.
In the future if you’re going to ask a question on SDL in a comment, I would appreciate it if you would ask it in a SDL post. Asking in a SDL post would make it more likely for someone else to answer your question. Your question is a valid question. It just doesn’t have anything to do with creating Xcode 4 file templates.
This a pretty random find I had, but if you want the save dialog to only ask WHERE to save the file and not WHAT and WHERE, you must name one of the fields productName. Hope this saves someone the hours it took me.
I’m trying to figure out if it’s possible to create an Xcode template that creates a group of files in an existing project, something like this:
GroupName
Classes
Class1.h
Class1.m
Class2.h
Class2.m
Resources
UTI.plist
So far I can’t see a way to make it work; it seems that file templates are limited to two files, and project templates can only create a whole project. Have you ever seen anything like this done, and/or do you have any suggestions?
Janine,
I don’t know of any way to create a template that adds a group of files to a project. I noticed you asked about this on Apple’s paid developer forums. The only other suggestion I could make is to ask on Apple’s Xcode mailing list.
You can create a group of files following below naming, this is an example.
___FILEBASENAME___Cell.m
___FILEBASENAME___Cell.h
___FILEBASENAME___CellController.h
___FILEBASENAME___CellController.m
___FILEBASENAME___Cell.xib
And you can do the same inside of files, Example:
//
// ___FILENAME___
// ___PROJECTNAME___
//
// Created by ___FULLUSERNAME___ on ___DATE___.
// Copyright (c) ___YEAR___ ___ORGANIZATIONNAME___. All rights reserved.
//
#import
@interface ___FILEBASENAMEASIDENTIFIER___Cell : UITableViewCell
@end