3.3 Development Recommendations

This section provides some guidelines to assist you in developing custom components. It covers these topics:

See the Oracle Fusion Middleware System Administrator's Guide for Content Server or online help for detailed instructions on creating or modifying components.

3.3.1 Creating a Component

To create and enable a custom component, follow this basic procedure:

  1. Create a definition file.

  2. Add a reference to the definition file in the idcshort-product-id_components.hda file to enable the component.

  3. Restart the Content Server to apply the component.

  4. Create resources and other files to define your customization. A good approach is to copy, rename, and modify standard Content Server files to create your custom resource files.

  5. Test and revise your customization as necessary. You may need to restart the Content Server to apply your changes.

  6. If you want to package the component for later use or for deployment on other Content Servers, build the component and create a component zip file.

3.3.2 Working with Component Files

There are two ways to work with component files:

  • Component Wizard: The Component Wizard is a Content Server utility that helps you create and edit component files. You can also use the Component Wizard to package, unpackage, enable, and disable components. For more information on using this utility, see the Oracle Fusion Middleware System Administrator's Guide for Content Server..

  • Text editor: Because most component files are plain text files, you can create and edit the files in your favorite text editor.

You should use the Component Wizard as much as possible when working with custom components.

The Component Wizard does several tasks for you and minimizes the amount of work you need to do in a text editor. Using the Component Wizard helps you follow the recommended file structure and naming conventions. The Component Wizard automatically adds a readme text file when you build a component, thus helping you to document your customization. You should also include comments within your component files.

For instructions on using the Component Wizard to create components, see the Oracle Fusion Middleware System Administrator's Guide for Content Server.

3.3.3 Using a Development Instance

Whenever you are customizing the Content Server, you should isolate your development efforts from your production system. Remember to include the same custom metadata fields on your development instance as you have defined for your production instance.

When you have successfully tested your modifications on a development instance, use the Component Wizard to build a component zip file and then unpackage the component on your production system.

Remember to restart the Content Server after enabling or disabling a component.

If you are having problems with your Content Server after you have installed a custom component, disable the component and restart the Content Server. If this fixes the problem, you probably need to troubleshoot your component. If the problem is not fixed, you may need to remove the component completely using the Component Wizard to see if there is a problem with the component or with the Content Server.

3.3.4 Component File Organization

To keep your custom components organized, follow these file structure guidelines. See "Typical Directory Structure" for more information.


If you use the Component Wizard, it creates component directories for you and places the component files in the correct directories.

Place each custom component in its own directory within a directory called DomainHome/ucm/short-product-id/custom/. If your custom component includes resource- or template-type resources, or both, the component directory should have subdirectories that follow the structure of the IdcHomeDir/data/resources/core directory:

  • resources/ to hold HTML include and table resource files

  • resources/lang/ to hold string resource files

  • templates/ to hold template files

  • reports/ to hold report files

Keep the following points in mind when considering files and their organization:

  • Place the definition file for each custom component at the top level of the component's directory.

  • When referring to other files within a component, use relative path names instead of absolute path names. Using relative path names enables you to move the component to a different location without having to edit all of the files in the component.

  • The Content Server is a Java-based application, so forward slashes must be used in all path names.

  • Custom components do not have to be stored on the same computer as the Content Server, but all component files must be accessible to the Content Server.

  • Images and other objects that are referenced by Content Server Web pages must reside somewhere in the DomainHome/ucm/short-product-id/weblayout/ directory (so they can be accessed by the Web server).

3.3.5 Naming Conventions

To keep your component files organized and ensure that the files work properly in the Content Server, follow these naming conventions for directories, individual files, and file contents.

  • You should give all of your component directories and files unique and meaningful names. Keep in mind that as each component is loaded in the Content Server, it overrides any resources with the same file names, so you should use duplicate file names only if you want certain components to take precedence.

  • If you are copying a standard Content Server file, a common practice is to place the prefix custom_ in front of the original file name. This ensures that you do not overwrite any default templates, and your customization is easy to identify.

  • HTM file types should have a .htm extension, and HDA file types should have a .hda extension.

  • If you are creating a new component file with a text editor like WordPad, place the file name within quotation marks in the Save dialog box so the proper file extension is assigned to it (for example, myfile.hda). Failure to use quotation marks to define the file name may result in a file name such as myfile.hda.txt.

  • The Content Server is case sensitive even if your file system is not. For example, when a file is named My_Template, the Content Server does not recognize case variations such as my_template or MY_TEMPLATE.

  • For localized string resources, you must follow the standard file naming conventions for the Content Server to recognize the strings. You should also use the standard two-character prefix (cs, sy, ap, or ww) when naming your custom strings. See "Resolving Localized Strings".