Sharing New Custom File Templates for a Specific Vocabulary

Read time: 7 minute(s)

The support Oxygen provides for editing DITA topics comes with quite an extensive set of new file templates used to create new DITA topic types. If you have a team of writers, you may want to filter out certain new file templates or add your custom new file templates, then share these custom templates with your team members.

This blog post will attempt to give you some clear steps for sharing a custom set of new file templates with your team.

All the original DITA new topic templates are located in the folder: OXYGEN_INSTALL_DIR\frameworks\dita\templates.

Instead of making changes directly to that folder, copying the entire DITA framework configuration folder (like OXYGEN_INSTALL_DIR\frameworks\dita), modifying and distributing it you can choose to extend the DITA framework and distribute the extension. In this way, you will benefit of new functionality added to the base framework by newer Oxygen versions and still use your customizations.

The steps below describe how an extension of the DITA framework which adds a custom set of new file templates can be constructed and shared:

Create somewhere on your disk, in a place where you have full write access a folder structure like: custom_frameworks/dita-extension.
In that new folder structure create another folder custom_frameworks/dita-extension/templates which will contain all your custom new topic templates.
In the Document Type Association / Locations preferences page add in your Additional frameworks directories list the path to your custom_frameworks folder. Click OK or Apply in the Preferences dialog to save your changes.
In the Document Type Association preferences page select the DITA document type configuration and use the Extend button to create an extension for it.
Give a custom name to the extension, for example DITA - Custom and then change its Storage to external, then save it to a path like: path/to/.../custom_frameworks/dita-extension/dita-extension.framework.
Make changes to the extension, go to the Templates tab, remove all previous entries from it and add a new entry pointing to your custom templates folder: ${frameworkDir}/templates.
Click OK to close the dialog and then either OK or Apply to save the preferences changes.

After you perform the steps above you will have in the dita-extension folder a fully functioning framework extension which can be shared with others.

The framework can then be shared with others in several ways:

Copy it to their [OXYGEN_DIR]/frameworks directory.
Create somewhere on disk a custom_frameworks folder, copy the framework there and then from the Document Type Association / Locations preferences page add in your Additional frameworks directories list the path to the custom_frameworks folder.
Distribute the framework along with a project.
Follow these steps:
1. On your local drive, create a directory with full write access, containing the project files and a custom_frameworks folder containing your dita-extension framework.
2. Start the application, go to the Project view and create a project. Save it in the newly created directory.
3. In the Document Type Association / Locations preferences page, select Project Options at the bottom of the page.
4. Add in the additional framework directories list an entry like ${pd}/custom_frameworks.
5. Add other resources to your project, for example you can have all your DITA content located inside the project folder.
6. You can then share the new project directory with other users. For example you can commit it to your version control system and have they update their working copy. When they open the customized project file in the Project view, the new document type becomes available in the list of Document Types.
Deploy the framework/document type configuration as an add-on.

After your team members install the framework they can check in Document Type Association preferences page in the list of Document Types to see if the framework is present and if it appears before the bundled DITA framework (meaning that it has higher priority).

You can use the framework extension mechanism to customize lots of aspects of the DITA functionality in Oxygen. For example you can remove various elements from the content completion list: Document Type Extension Sharing.