Welcome to Mobipocket Developer Center

Home | Show TOC |

Download Sample |

Add to Favorites

updated: 2005-01-21

Support of Frames in Mobipocket Reader

Framesets in Mobipocket reader are bound to a given HTML location: the frameset is automatically activated whe the user jumps to that location in the content. Think of them as page headers, footers, "lefters" and "righters" rather than traditional HTML framesets.

Content

<mbp:frameset> tag
<mbp:slave-frame> tag
Slave frame positionning (display attribute)
Cross-platform support (device attribute)
Using frames in the index search screen
Using frames in ASP pages
Remarks and Tips

Mobipocket introduces two custom tags for handling frames and framesets

<mbp:frameset> : defines a new frameset, which contains slave frames and the main content flow
<mbp:slave-frame> :defines a new slave frame

<mbp:frameset> tag

By default a new HTML page defines a default frameset, which means that if only one frameset has to be defined in the HTML page, the <mbp:frameset> tag is optional and can be ommitted.
However, if mutiple framesets need to be defined in the HTML page, use the <mbp:frameset> ... </mbp:frameset> to define a new frameset. Each frameset has to contain one or more <mbp:slave-frame> tags.
Framesets can be nested, in this case newly declared frames (within the nested frameset) are added to the existing outer frameset. When the nested frameset closes, outer frameset is reactivated, removing frames declared inside the nested frameset. You can choose to have a non-additive nested frameset using the additive="no" attribute, in this case frameset is reset. By default, frameset are additive.

A <mbp:pagebreak/> is automatically inserted by prcgen before an opening <mbp:frameset> tag (and also an opening <mbp:section> tag). You should therefore not add a <mbp:pagebreak/> tag explicitly between framesets, as this will add a second page break, and the frame will not appear on the first page. I.e. do not use : <mbp:frameset>...</mbp:frameset><mbp:pagebreak/><mbp:frameset>...</mbp:frameset>

<mbp:framset> attributes reference

Name	Optional/Mandatory	Values
*crossable*	Optional ; default=yes	yes: user can cross the limits implied by the frameset no: user cannot cross the limits implied by the frameset
*additive*	Optional ; default=yes	yes: frames declared inside the frameset are added to outer frameset (if any) no: no frames are inherited from outer frameset (it 'resets' the frameset locally), usefull to get a local footer.
id or name	Optional	Sets an anchor for this frameset. If an anchor is set, it is automatically an external anchor, which can be accessed using the Mobipocket Javascript DOM (window.document.location.hash = 'anchor_name' or window.open('test.prc#anchor_name')). This anchor, if set, needs to be unique among an entire publication. The name of the framset is also used to call a specific frameset when endering an index search screen or an ASP page.

<mbp:slave-frame> tag

The <mbp:slave-frame> tag can be placed anywhere after the <body> tag in the HTML page of the main frame, if there is only one frameset in the HTML page or inside a <mbp:frameset> tag.

The frame will display in the Reader as soon as the X-HTML flow containing the <mbp:slave-frame> tag is being parsed.

There are two syntaxes :

1 Frame source in separate HTML file

The <mbp:slave-frame> tag must be self-closing and contain an src attribute pointing to the HTML file. If you use this approach, you will have to set margins in the <BODY> tag of the HTML file which defines the frame.

Example :

<mbp:slave-frame device="all" display="bottom" breadth= "auto" src="nav.htm"/>

2 Inline HTML source of frame content:

Example :

<mbp:slave-frame device="all" display="bottom" breadth= "auto"> <p>Hello</p> </mbp:slave-frame>

Important: the definition of the frame should not contain a <body> tag.

3 <mbp:slave-frame> attributes reference

Name	Optional/Mandatory	Values
*device*	Optional ; default=PC only	pda : frame displays only in the Mobipocket Reader on PDA devices pc : frame displays only in the Mobipocket Reader for PC all : frame displays both on PC and PDA devices
*display*	Mandatory	top, bottom, left, right. Defines the position of the frame on screen
*breadth*	Mandatory if display="left" or "right" Optional if display="top" or "bottom" in this case, the default value is "auto"	width of the frame in case of display="left" or display="right" height of the frame in case of display="top" or display="bottom" units : px (pixels), em (1em = height of one character in the current font), pt If display="top" or display="bottom", you can set breadth="auto" to let the Reader automatically compute the optimal height at runtime (automatic breadth requires Reader 4.6).
*src*	Optional ; used when frame source is not defined inline	relative path of HTML file containing the frame source. Path is relative to the main frame HTML file
*topmargin*	Optional	Set the top margin for this slave frame. used only when the src attribute is not set.
*bottommargin*	Optional	Set the bottom margin for this slave frame. used only when the src attribute is not set.
*leftmargin*	Optional	Set the left margin for this slave frame. used only when the src attribute is not set.
*rightmargin*	Optional	Set the right margin for this slave frame. used only when the src attribute is not set.
*user-selection*	Optional (default: no)	if yes, user can select content of frame; this is useful for frame with real content; navigation frames behaves better with default setting.

Slave frame positionning (display attribute)

Each slave frame is placed in the order of appearance of the <mbp:slave-frame> in the main frame HTML, and occupies the remaining space in the screen.

Example:

<mbp:slave-frame display="top" breadth= "auto" src="nav_top.htm"/> <mbp:slave-frame display="left" breadth= "auto" src="nav_left.htm"/>

will display the following screen :

nav_top.htm

nav_left.htm

whereas,

<mbp:slave-frame display="left" breadth= "auto" src="nav_left.htm"/> <mbp:slave-frame display="top" breadth= "auto" src="nav_top.htm"/>

will display the following screen :

nav_left.htm	nav_top.htm

Cross-platform support (device attribute)

It is possible to specify several <mbp:slave-frame> tags in the same position in one HTML file with different target devices. This allows to optimize the use of frames of different platforms, i.e. display a different frame on a PC and on a PDA.

Example :

<mbp:slave-frame device="pda" display="bottom" breadth="50 px" src="nav_pda.htm"/> <mbp:slave-frame device="pc" display="bottom" breadth="90 px" src="nav_pc.htm"/>

Remarks and Tips

1 Slave Frame margins attribute

If the frame content is in an external HTML file, you can use margin attributes in the <BODY> tag of the slave frame file.
If the slave frame content is embedded inside the <mbp:slave-frame> tag, use the topmargin, leftmargin, rightmargin, bottommargin attributes directly in the <mbp:slave-frame> tag. DO NOT add a <BODY> tag in the case you put the HTML content inside the <mpb:slave-frame> tag.

Example :

<mbp:slave-frame device="pda" display="top" breadth="auto" topmargin="0" leftmargin="0" rightmargin="0" bottommargin="0">Some slave content </mbp:slave-frame>

2 No scrolling in frames

There is no scroll bar in a frame. The breadth must therefore be chosen carefully to display the full content of the frame. Use of the em unit, proportional to the current font size can come in handy, the "auto" value can be helpful when the size is not predictable (available for "top"/"bottom" frames only).

3 Use of <mbp:pagebreak/> with framesets

Using frames in the index search screen

All the functions that display the index search screeen (index_search, cond_index_search, filtered_index_search, sql_search, sql_bullet_search) have an extra parameter where the name of a frameset can be specified. The index search will then be displayed within that frameset.

If the FrameSet parameter is not specified or if it is an empty string, the current framset remains active when the index search screen is displayed. If you want to make sure that no frameset is displayed when in the index search screen, pass the name of a frameset that does not exist in your publication, for example "no_frames".

Using frames in ASP pages

In an ASP script, the Mobipocket specific Frameset object can be used to specify the frameset to be displayed around the page generated by the ASP script.

Example:

Frameset.Use ('my_frameset')