By: Dwayne Parkinson – Solution Architect
In Part 2 we covered some of the things that can go into a custom component to help you customize your content server. In this entry we’ll look at a Template and show how it can be used to customize the WebCenter Content interface.
Templates in Content Server allow custom pages to be created. A template is created inside of a component resource, so you must have a component before you can add a custom template to Content Server.
Create a Custom Component
The first step to creating a custom template is to create a component. If you’re not familiar with the concept of components, the best way to think of them is as a set of related resources used to customize the system. As a general rule you create a component to contain resources that are related to a common customization. For example, if you need to have some custom security processing you would generally have a single component for all of the custom security features. You would not create separate components for each security feature. In other words, your component name might be CustomSecurity rather than having separate components called ValidateID, UserLookUp, etc.
Creating a custom component is done by opening the Component Wizard and clicking the add button. While we won’t cover the details of the Component Wizard here, you can find Oracle documentation on-line that explains the process in more detail http://docs.oracle.com/cd/E29542_01/doc.1111/e26692/components.htm#WCCSA357.
Adding a new component will get us an empty container that we can use to begin adding resources.
The Template Resource
The template resource is a simple text file that defines the template pages within a component. The default extension for these resource text files is HDA. The Component Wizard helps manage the creation of the template resource. As shown below, you simply select a Template resource type and add the file. NOTE: It is highly recommended that all templates go into a “templates” folder as shown.
Adding a Template Resource
Behind the scenes the Component Wizard is busy creating some entries in the “glue file” which is a text file that defines all of the component resources. This glue file is named <componentName>.hda and is located in the following folder:
For example, if your custom component is called “test” (because we’re creative) the file will be called test.hda and it will be in a folder called ucm\cs\custom\test within the domain folder for the Content Server.
The resulting entries in the glue file are shown below. They exist to let the content server know that there is a custom resource definition out there that needs to be merged in with the rest of the system.
After creating the initial template definition, the next step is to further define the resource and identify what it should be merged to within the Content Server. The Component Wizard will manage these relationships in the glue file automatically as you add, update and remove resources.
Merging to Content Server’s Templates
In the example above, this template resource is going to be merged with the ‘IntradocTemplates’ which is used when creating any content server pages other than search result pages. For more information on the difference between IntradocTemplates and SearchResultTemplates refer to this bit of documentation
Once you’ve selected the Merge Table the Component Wizard again updates the glue file with some MergeRules that tell the Content Server how to merge our new template into the Content Server. The resulting entries in the file are shown below.
The Template Page
With our template resource files successfully created, a template page can now be defined within the resource. A template page is made up of HTML and iDoc Script (see below). The template can copy one of the Content Server’s pages or we could create a completely custom page. While we could create a completely custom page, it is often easiest to use an existing template so our page gets automatically filled in with the necessary iDoc includes (see below).
In this example, we’re going to create a template page called EXAMPLE_PAGE and copy from the doc_info page. Note the location of the template files. They will be in a similar location on your content server.
The Class field we’re going to purposely gloss over and simply say that most of the time it’s Document or DocManagement. For more information on the Class field, reference the Oracle documentation.
Notice that Form Type and File Name are the same as the name of the template. You will find that the “standard” within the WebCenter Content world is to use all capital letters for the template while Form Types and File Name are generally in camel case or lower case. NOTE: If you’re using the SearchTemplate only a Form Type of ResultsPage is currently supported.
Creating a Template Page
Once everything is filled in, the code for the resulting template page is generated by the Component Wizard.
<!– Template Contents –>
By copying from an existing page, all of the necessary includes are automatically generated.
Understanding iDoc Includes
The WebCenter Content server makes extensive use of iDoc “includes” throughout its architecture. Most developers are familiar with the concept of include files, however where WebCenter Content and iDoc Script depart a little from normal is that includes also reference sections of code within the same file, similar to a procedure call.
Rather than get derailed by the gory details of iDoc Script training, let’s look at our example from above and look at what each of those includes does. You can then review each of these separate include files to see how the iDoc Script is constructed and how the includes are being referenced.
WebCenter Content stores its core iDoc Script files in the following location:
These files should never be modified directly.
The std_page.idoc file contains the includes used in the sample page above and if you read through the code you can figure out exactly what’s going to happen. However to make life easier, the following table gives you a general idea of the purpose of each include.
Standard Template Page Includes
||Defines the page’s DTD definitions.
||Defines the body tag. This section can be modified to add additional parts to the body.
||Defines the beginning of the page resources. This section can be modified to add to the page before the header.
||Defines the header for the page. This section is the navigation and top bar of the page.
||Defines the page’s footer. This section can be modified to add a custom footer to a page.
By understanding each of these includes, figuring out what’s happening in any given section of the page can become easier. For example, the ‘std_header’ include from the template generates something like this:
The ‘std_header’ include
When thinking about a template page vs. an include, it is valuable to remember that includes are called on a template page. The includes are defined elsewhere like in the std_page.htm file. They are called on template pages or within other includes. You can think of the template page as a canvas and includes are one medium that can be used to paint on that canvas.
It’s important to notice that the Content Server, as if by magic, knows where to find the includes so you don’t have to specify any class paths or folder structures or anything like that. This is because we’re merging our custom component into the core Content Server. That process makes our component aware of the resources available on the Content Server.
It wouldn’t be a user interface if we didn’t generate a Hello World message right? Unfortunately we’ll have to wait for a couple more Blog entries to actually see our page, but for now we can at least add the requisite “Hello World” message under the Template Contents comment line in the HTML file shown above. Since this is an HTML file you can add any HTML compliant code you want, but for now we’ll keep it simple.
Customizing the interface for WebCenter Content is relatively simple once you know the steps and understand the architecture. In this part we created a simple template resource with a single page. In Part 4 we’ll leverage WebCenter Content’s service oriented structure to create a service that will render the page we created.
While it’s difficult to do justice to the full flexibility of WebCenter Content in a few blog entries, I hope this series will help more people dive in and attempt to customize the WebCenter Content server. Obviously we’re just skimming the surface, so if you would like more information on customizing WebCenter Content please contact TEAM Informatics and ask about our customized training options.