Creating Custom Xcode 4 File Templates

November 17th, 2011

Filed under: Xcode | 8 comments

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.

Tags:


8 thoughts on “Creating Custom Xcode 4 File Templates

  1. Oleg Sv says:

    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.

  2. Mark Szymczyk says:

    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.

  3. Mark Vaughn says:

    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

  4. Mark Szymczyk says:

    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.

  5. Rob says:

    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.

  6. Janine Ohmer says:

    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?

  7. Mark Szymczyk says:

    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.

  8. Alex says:

    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

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

*