Skip Headers
Oracle® Fusion Middleware Managing Oracle WebCenter Content
11g Release 1 (11.1.1)

Part Number E26693-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

38 Implementation Considerations for Dynamic Converter

This chapter provides information about some of the more pragmatic concerns when dealing with Dynamic Converter.

This chapter covers the following topics.

38.1 Metadata Fields With Multi-Byte Characters

For Classic HTML Conversion templates, it is recommended that you do not use multi-byte characters in your content IDs, security groups, content types, and account names, even if Dynamic Converter is used in a multi-byte environment (Japanese, Korean, or other non-Roman alphabets). This content metadata information is included in the URL of a content item, and limitations in current web technology may prevent web servers and web browsers from handling multi-byte character URLs correctly. (Dynamic Converter, for example, will fail to locate content items if the links are broken.)

If you want to use multi-byte characters in content IDs, security groups, content types, or accounts, you need to make sure that the entire Oracle WebCenter Content Server environment (servers and clients) runs on operating systems that support multi-byte languages (for example, Japanese or Korean versions of Microsoft Windows).

Note:

The new Dynamic Converter HTML Template Editor will not support working with multi-byte content IDs for the templates or the content items being converted.

38.2 Conversion of PDF Files in UNIX

Conversion of PDF files under UNIX may be slow and may time out after three minutes (the default timeout value for the conversion process).

To increase the conversion timeout, complete the following tasks:

  1. Open the Dynamic Converter Admin page.

  2. Click Configuration Settings.

  3. On the Dynamic Converter Configuration page, enter a new value in the Time Out field (increasing it from 3 minutes, which is the default).

  4. Click Update to enable your changes.

The changed setting takes effect immediately, so you do not need to restart the Content Server.

38.3 Embedded Graphics on UNIX

Some source documents contain embedded OLE objects. Embedded OLE objects are usually accompanied by a graphic "snapshot" in the form of a Windows metafile. On both Windows and UNIX, Dynamic Converter can use the metafile snapshot to convert the OLE object. When the metafile is not available, Dynamic Converter reverts to OLE technologies for the conversion. In that event, the conversion will still succeed on Windows, but it will fail on UNIX.

38.4 Use of Vector Versus Raster Graphics Formats

If you are converting vector graphics, Dynamic Converter requires access to a running X-Server. This is because Dynamic Converter depends on the X-Server system to draw the pixels.

Vector graphics formats describe lines and fills. Common formats are WMF, EMF, CorelDRAW, Adobe Illustrator, Excel charts, Word autoshapes, and PowerPoint presentations. Raster graphics, on the other hand, contain pixel information of an image. Common file formats are BMP, JPEG, and GIF.

One way to tell the difference between a vector and a raster graphic is to try to stretch the image. Since vector graphics describe lines, they will re-compute the placement of the lines and the image should still look nice. Raster graphics, however, will become pixelated when you resize.

For instructions on how to set up rendering of graphics and fonts in UNIX, see Oracle WebCenter Content Installation Guide.

38.5 Converting Vector Graphics and Spreadsheet Text in UNIX

Dynamic Converter requires access to a running X-Server in UNIX in order to convert vector graphics and to properly measure text that spans multiple columns in spreadsheets.

For instructions on how to set up rendering of graphics and fonts in UNIX, see Oracle WebCenter Content Installation Guide.

38.6 URL Rewriting

Dynamic Converter wraps the dcUrl('url', reserved_type) Idoc Script extension function around all hyperlinks and image source links (src). The default implementation of this script function is to do a simply pass-through, but external integration technologies (such as CIS) can modify this behavior by defining a filter plug-in for "dcUrlFilter."

Dynamic Converter evaluates the link URL, applies the "dcUrlFilter" filter if it exists, and then returns the URL value. If the dcUrlFilter filter is not defined, then the original URL is unchanged. Links to internal bookmarks always remain unchanged.

Reserved Types

The reserved_type function argument is a number 1001, 1002, and so forth, which indicates where in the Dynamic Converter core engine the URL is being written. This value can be used to distinguish the type of URL. For example, gallery graphic, inter-document link. The reserved type values and their meanings are as follows:

Value Description

1001

Link (different split)

1002

Previous element (different split)

1003

Previous page (TOC frame)

1004

Previous page

1005

Next page (TOC frame)

1006

Next page

1007

Next element (different split)

1008

Previous page (TOC frame)

1009

Previous page

1010

Next page (TOC frame)

1011

Next page

1018

Image link

1019

Image link

1020

Image link

1021

Image link

1022

Background graphic (not from source)

1023

Background graphic (from source)


38.7 Relative URLs in Templates and Layout Files

Consider the following image tag: <IMG SRC="image.gif">. In most implementations of Dynamic Converter, it is likely that the output files will end up in a different location than the template files. If the developer uses the template above in this scenario, the output files produced will have a reference to image.gif, which the browser will assume has the same path as the output files. The problem is that image.gif is likely to be back in the directory where the template file is located. This is a problem for anything referenced in the template using a relative URL. There are several possible solutions to this problem.

Solution 1: Ensure That the References Are Good

If the developer knows exactly which files all of the templates reference, the correct files (such as image.gif) can be moved to or located in the output directory or directories. This solution requires the developer to have exact knowledge of the contents of the templates, and may propagate the same set of files into many output locations.

Solution 2: Use Absolute URLs

The developer can design templates to contain absolute URLs to any referenced files. The template in the example would then look something like this.

<HTML>
<BODY>
<P><IMG SRC="http://www.company.com/templates/image.gif"></P>
{## INSERT ELEMENT=Sections.1.Body}
</BODY>
</HTML>

If <$HTTPWEBROOT$> is used instead, you eliminate the problem of output files tied to a specific domain.

Solution 3: Make Path Statements in a Separate File

The developer can create a separate Idoc Script file that states the path, for example:

<@dynamichtml Image_Dir@><$HttpWebRoot$>groups/public/documents/graphic/<@end@>

The developer can then load the Idoc resource and reference the path statement from the included Idoc Script file as follows:

<img src="<$include Image_Dir$>logo.gif">

All long as the graphics (or related files) are checked in with the security group and document type to match the stated path (in this example, a security group "Public" and a document type "Graphic"), then the paths will resolve, and the page will display properly.

38.8 Browser Caching

In the process of building and debugging templates, you are likely to run the same source file through Dynamic Converter repeatedly with slightly different templates. Depending on how you are naming the output files, this may have a tendency to produce the same set of file names repeatedly. In this scenario, especially if the output is being read directly from a file system and not through a web server, browsers will have the tendency to show the old cached results and not the new ones.

If it looks like bad output, click Refresh on every frame before deciding that it is a problem with the template or the software.

Tip:

You may find it simpler to empty and turn off caching in your browser while creating and testing your templates.

38.9 Image Sizing Rules

There are a large number of factors that affect the size of the final exported image. The precedence of rules for how those factors work is as follows:

  1. Any images that the template specifies with the {## graphic} macro are subtracted from the space available for graphics on that particular deck. In general, you should be wary of templates that require images on every deck as they will eat into the overall amount of room available for document graphics.

  2. The SCCOPT_EX_GRAPHICBUFFERSIZE option, which is only used to reduce image size if necessary. It preserves the image aspect ratio.

  3. The SCCOPT_GRAPHIC_SIZELIMIT option, which is only used to reduce image size if necessary. It preserves the image aspect ratio.

  4. The SCCOPT_GRAPHIC_WIDTHLIMIT and SCCOPT_GRAPHIC_HEIGHTLIMIT options. These are only used to reduce image size if necessary. They preserve the image aspect ratio, even if both are specified.

  5. 'Width=' and 'height=' parameters in the {## INSERT} statement of the template. This reduces or enlarges the image to match the specified dimension(s). The image aspect ratio is changed if both are specified. The aspect ratio does not change if only one or none of these parameters is specified.

  6. Original image dimensions based on the information in the source file and the DPI setting, if applicable.

38.10 CSS Considerations

The styles discussed in this section relate only to script templates (see Chapter 35, "Script Templates"). Styles in Classic HTML Conversion templates (see Chapter 33, "HTML Conversion Templates") are handled differently.

One of the most powerful features of cascading style sheets (CSS) is the ability to override the styles suggested in various ways. Dynamic Converter has designed its CSS support to permit users to override the style sheets that it produces. This, in turn, enables the user to help blend documents from many authors into a collection that has a more unified look. In order to make this override work, one first needs to understand style names.

In addition, it should be remembered that the output from Dynamic Converter might be placed into many HTML files. Special attention must be paid to ensure that <LINK REL=STYLESHEET HREF="{## INSERT ELEMENT=Pragma.cssFile}"> statements are placed in the appropriate locations.

38.11 Style Names Used by Dynamic Converter

Style names are taken from the original style names in the source document. There is an inherent limitation in the style names the CSS standard permits. The standard only permits the characters a-z, A-Z, 0-9, and dash (-) . Source document style names do not necessarily have this restriction. In fact, they may even contain Unicode characters at times. For this reason, the original style names may need to be modified to conform to this standard. To avoid illegal style names, Dynamic Converter performs the following substitutions on all source style names:

An example of one of the most common examples of this substitution is that spaces in style names are replaced with "-0020." For a more complete example of this character substitution in style names, consider the source style name "My Special H1-Style!" (with a space and an exclamation mark in its name). This would be transformed to "My-0020Special-0020H1--Style-0021."

While admittedly this system lacks a certain aesthetic, it avoids the problem of how the document looks when the browser gets duplicate or invalid style names. Developers should also appreciate the simplicity of the code needed to parse or create these style names.

In addition, Dynamic Converter creates special list versions of styles. These have the same name as the style they are based on with "--List" appended to the end. These styles differ from their original counterparts in that they contain no block-level CSS.

38.12 Overriding Dynamic Converter Styles

Once style names are understood, it is easy to override the CSS file produced by Dynamic Converter. Follow the CSS file link in the template with another link to the CSS override file. For more information on the link to Dynamic Converter's CSS file, see Section 38.13. This override file should then contain styles with the same names as the ones used by Dynamic Converter's CSS file.

Remember that many file formats allow styles to be based on other previously defined styles. Dynamic Converter supports this by nesting styles. In this way each nested style inherits and may override items defined in the styles that surround it.

38.13 Pragma.CSSFile and {## LINK}

One {## INSERT Element=Pragma.CSSFile} statement should appear at the top of each HTML file produced when a CSS flavor of HTML is used. It should therefore be remembered that the ## LINK statement may be used to trigger the creation of additional HTML files. As a result, each ## Linked template will typically contain a <Link> tag to the CSS file generated.

Using a ## LINK statement, it is possible, though, to link to a template that does not have any {##} statements that would need to reference the CSS file. In that case, the <Link> to the CSS file may safely be omitted. Consider, for example, a template that has only two ## statements, both of which are ## links (perhaps to put the results into two separate frames). This template file would not need a <Link> to the CSS file.

Regardless of how many HTML files are produced by Dynamic Converter, only one CSS file is generated. It is also worth repeating here that the <Link> to the CSS file must occur in the <HEAD> section of the document and each resulting HTML file may have only one <HEAD> section.

38.14 Well-Formed HTML

The output of Dynamic Converter has been tested to ensure that it is well-formed. This is meaningless, however, unless the template used by Dynamic Converter is also well-formed. To assist with creating well-formed templates, here is a list of common problems that may cause documents to not be well formed:

38.15 Positional Frames Support

Dynamic Converter 7.7 and higher uses DHTML to position objects. However, only two types of object positioning are supported: paragraph anchored objects and page anchored objects. Here are some important notes about this initial support for positional frames:

38.16 Template Writing Tips

Given the limited amount of space in each deck, it is important to maximize the amount of usable data in each deck produced by Dynamic Converter. Some ways to reduce the amount of space wasted in each deck include the following: