### 22.13 Using framesets

To use framesets, you must create the HTML that defines the frames yourself, possibly using another HTML tool. You can make the resulting HTML code into a DITA2Go macro (see §37. Working with macros), as follows:

1. Give the macro a name.
2. Copy the name and HTML code into your project configuration file or into a macro library file (d2h_macro.ini, or another macro library file you have created).
3. Include an entry for the macro in the [Inserts] section.

The generated frameset file is more a starting point than a finished product. The result might look like the following, using an example from the W3C reference on framesets:

http://www.w3.org/TR/1999/REC-html401-19991224/present/frames.html

The following example produces a simple three-frame layout:

    [Inserts]
    Frames=<$MyFrameset>
    End=</noframes></frameset>
    . . .
    [MyFrameset]
    <frameset cols="20%, 80%">
      <frameset rows="100, 200">
         <frame name="frame1" src="contents_of_frame1.html">
         <frame name="frame2" src="contents_of_frame2.gif">
      </frameset>
      <frame name="frame3" src="contents_of_frame3.html">
      <noframes>

If the browser is too old to display frames, or is set not to display frames, the page contents are shown instead, as the noframes section.

The frameset document itself must use the frameset header:

    [HTMLOptions]
    ; UseFrameSet = No (default) or Yes (if included frameset tags)
    UseFrameSet=Yes
    ; HTMLDocType, required at start of HTML documents
    ;  for v4 frameset is: "-//W3C//DTD HTML 4.01 Frameset//EN"
    ; HTMLDTD, default for v4 frameset is:
    ;  "http://www.w3.org/TR/1999/REC-html401-19991224/frameset.dtd"

The frames defined in the frameset get their initial content as specified in the src attribute of the frame element. After that, they are reloaded by making jumps for which the target attribute is set to the frame name, such as:

    <p><a href="http://www.omsys.com" target="frame3">Click here.</a></p>

You can set the target attribute for a jump by applying, to the hotspot and PI marker, a paragraph or character format that you list in the configuration file with a frame target name. For example:

    [Targets]
    ; doc format = name of frame to use for jumps from within this format
    ; For OmniHelp ALink and KLink jumps, targets make no sense
    ;  and are ignored.
    Top Left=frame1

If the format in effect at the jump is not listed, DITA2Go checks to see if all jumps to that file, or to that URL destination, are intended for a particular frame. For example:

    [TargetFiles]
    ; filename (no ext) or URL destination = target frame to be used
    ; a URL destination is the last element in the URL (no extension)
    procedures=frame2

You can also set a default target to be used by all jumps in the file that are not otherwise set; for example:

    [HTMLOptions]
    ; DefaultTarget = target to use for all jumps not otherwise set
    DefaultTarget=frame3

To have a jump to a target open another window, you can use an HTML reserved name for the target; one such name is _blank, which causes opening in a new browser window. Or, you can specify the opening method in the target file, with an onload attribute in the <body> tag.

In HTML, you can force a new window with <a href="..." target="_top">, or better yet with an href to a JavaScript function that sets document.location. In any case, you get a new new window every time.

See also §28.4 Creating jumps to particular windows for HTML.

Note: You cannot use framesets in compiled HTML Help (.chm file); you can use them in uncompiled HTML Help only, which is of questionable value. Using framesets for HTML Help makes sense only if the result will be viewed on UNIX systems.

Previous Topic: 22.12 Specifying a starting topic for HTML or XHTML

Next Topic: 22.14 Passing W3C validation tests

Parent Topic: 22. Converting to HTML/XHTML

Sibling Topics:

22.1 Deciding which type of output to produce

22.2 Setting up an HTML project

22.3 Including starting code and entity references

22.4 Supplying values for the <head> element

22.5 Specifying HTML <body> attributes

22.6 Specifying document-wide properties for HTML

22.7 Defining text colors for HTML

22.8 Importing HTML files as insets

22.9 Providing hover text for links in HTML

22.10 Generating XHTML for Confluence 4.x

22.11 Exporting content for database input

22.12 Specifying a starting topic for HTML or XHTML

22.14 Passing W3C validation tests