Package org.netbeans.spi.project.ui.templates.support

Support for providing own templates visible in New File action.

See: Description

Class Summary

Class	Description
Templates	Default implementations of template UI.
Templates.SimpleTargetChooserBuilder	A builder for simple target choosers.

Package org.netbeans.spi.project.ui.templates.support Description

Support for providing own templates visible in New File action.

Project types may declare the templates for projects using TemplateRegistration with a path as a subfolder of Projects/. Registering project type templates is similar to registering file templates described below. The wizard for a project can return DataObjects or FileObjects corresponding to the project directories of created files and/or files to be selected in newly created projects.

Each project can also declare own file templates to be exposed it in New File... wizard. This permits users to create new files, which are of types supported by given project type. The project may also provide own iterator for project-specific customization of given file type.

File templates may be declared using TemplateRegistration, e.g.:

@TemplateRegistration(
    folder="JSP_Servlet",
    position=123,
    displayName="#JSP.template",
    iconBase="org/netbeans/modules/web/core/resources/jsp.png",
    description="JSP.html",
    category="web-types"
)
public class JSPIterator implements WizardDescriptor.InstantiatingIterator {
    // ...
}

The folder attribute specifies the folder in which this template will be present in the template chooser invoked from either New File... or New Project... wizard.

Note: a project type can declare own custom iterator with some project-specific customization, it's recommended to use the standardized target chooser exposed in Templates.buildSimpleTargetChooser(org.netbeans.api.project.Project, org.netbeans.api.project.SourceGroup[]), a similar target chooser offers JavaTemplates.createPackageChooser(...) for Java-oriented projects. The project type also can use a InstantiatingIterator published by other module, i.e. JavaTemplates.createJavaTemplateIterator() useful for Java-oriented templates in case of no needs to own customization. The last possibility is declaration no iterator, in this case will be used a generic iterator useful for simple file types without any specific needs, i.e. properties file.
For project templates the instantiate() method should return a Set of FileObjects. FileObjects representing project directories will automatically be opened in the project and files tab. Other FileObjects (e.g. Java classes created by the wizard) will be opened in the editor area. Path of corresponding nodes will be expanded in the project or files tab.
For file templates the instantiate() method should return Set of FileObjects which will then automatically opened in the editor. Path of corresponding nodes will be expanded in the project or files tab.

category files the template to some category. The template's categories helps to filter the templates according to type of project. You may specify multiple categories separated by commas, e.g.: some-type,some-other-type

There is currently no annotation to define template folders; they should be defined in the XML layer as subfolders of Templates with displayName and position attributes. Note that it is possible to set the attribute simple to (boolean) false in order to hide templates from the list shown in the standard wizards, while still making it possible to use TemplateRegistration and apply templates programmatically. To hide templates from the "new" wizards but show them in Template Manager, just set a category which is never used (such as invisible).

There are two important interfaces affecting the behavior of the templates. Implementation of these interfaces should reside in the project's lookup.

The first one is PrivilegedTemplates. It is used for the initial content of the popup menu of New File.... It simply should return names of file templates from system filesystem which should be contained in the popup menu. Example implementation follows:

private static final class PrivilegedTemplatesImpl implements PrivilegedTemplates {

    private static final String[] PRIVILEGED_NAMES = new String[] {
        "Templates/Classes/Class.java",
        "Templates/Classes/Package",
        "Templates/Classes/Interface.java",
        "Templates/GUIForms/JPanel.java",
        "Templates/GUIForms/JFrame.java",
    };

    public String[] getPrivilegedTemplates() {
        return PRIVILEGED_NAMES;
    }

}

The second interface is RecommendedTemplates, which influences the appearance of templates in the New File wizard according to project types. The implementation of the interface has to return array of Strings which corresponds to names of template categories listed in the templateCategory attribute of template files. All templates which list at least one recommended category in the templateCategory attribute will be listed for given project type.
Note: if no templateCategory is declared then this template will be visible for each project regardless its type.

Example implementation of RecommendedTemplates interface:

private static final class RecommendedTemplatesImpl implements RecommendedTemplates {
    
    // List of primarily supported templates categories
    private static final String[] TYPES = new String[] { 
        "java-classes",         
        "java-main-class",      
        "java-forms",           
        "gui-java-application", 
        "java-beans",           
        "oasis-XML-catalogs",   
        "XML",                  
        "ant-script",           
        "ant-task",             
        "junit",                
        "simple-files"          
    };

    public String[] getRecommendedTypes() {
        return TYPES;
    }

}