rtLib — Notes Rich Text Management Library Documentation of rtLib — Notes Rich Text Management Library Download rtLib — Notes Rich Text Management Library FAQ of rtLib — Notes Rich Text Management Library Purchase rtLib — Notes Rich Text Management Library Feedback about rtLib — Notes Rich Text Management Library

Building and managing rich text

HTML generation

Start search Mail feedback Back to Description


The version 1.5 or rtLib provides an improved rendering of Lotus Notes rich text as HTML. Thr rendering largely deviates from Domino standard HTML that attempts to accommodate legacy browsers and concentrates on CSS compatible ones.

There are still a few potential issues caused by incompatibility of rich text formatting used by Notes and that of HTML markups and CSS, but I have tried to minimize their impact as discussed below.

At first a few caveats: rtLib do not generate HTML of "Notes document" in a sense of Notes document displayed by the Notes client. Notes client uses a particular form to display the document, rtLib converts only a particular rich text item (or part of it). In this way you can build your web page from these HTML fragments.

If you want to render the whole document the best chance is to use RenderWithForm method to store the rich text presentation of the document displayed with a particular form in an item and then use rtLib to retrieve HTML rendering of this item.

On the other hand rtLib can also render an HTML of any part of rich text item: content of a section, a single table, etc. How does it work?

Let us assume we retrieve rich text from Notes document:

Dim rtct as new rtContainer

Const ITEM_BODY = {Body}

rtct.getRichTextItem (doc, ITEM_BODY)

in order to obtain HTML presentation of this item it is enough to use HTML property of container:

sHtml = rtct.HTML

We could also obtain an HTML presentation of the content of first section in item or any other rich text object.

Dim obj

Set obj = rtct.getFirstElement (RT_OBJ_SECTION)

If Not obj is Nothing then

sHTML = obj.Content.HTML

End if

Matching Notes and browser, CSS_DEFAULT

There are a number of small differences between how Notes and CSS describe formatting and how Notes and browsers interpret default elements. Two important differences are in paragraph spacing and margins. Notes display unmarked paragraphs with no space between them while browsers add a space before and after.

In order to solve this discrepancy, starting from version 1.5 rtLibSession object has a new property CSS_DEFAULT that returns a piece of CSS that makes browser render paragraph margins in the same way as in Notes. As building a Web page may take conversion of several rich text items or item fragments, hence you should add this CSS only once per page. For example:

rtct.getRichTextItem (doc, ITEM_BODY)

rtct1.getRichTextItem (doc, ITEM_HISTORY)

sHtml = rtLibSession.CSS_DEFAULT + rtct.HTML + {<p>History:</p>} + rtct1.HTML

It may well be the case that the simple HTML generation produces an acceptable result. If not -- read on, there are a number of issues that you may still want to eliminate and there are parameters you can change in order to obtain a different rendering.


There is an issue with margins that I mentioned above; it relates to two discrepancies. One is that the default let margin in Notes is expected to be one inch from the page edge, while in browser it is usually few pixels from the left edge of screen. At the same time both display it in the same way on screen. The other mismatch is linked to the different definition of the right margin. In browser it is set as a distance, absolute or relative, from the right edge of the screen, while in Notes it is set as a distance from the left margin. As a result any setting of the right margin (anything else than "no-margin") will result in different rendering dependent on the size of page or screen.

rtLib implements a "default" way to solve this problem by interpreting that:

paragraph with no left margin set has the left margin equal one inch and

any paragraph that has one inch or less left margin should be placed at zero left margin in browser and

default page size when interpreting right margins is the width of A4 page (21 cm).

At the same time in order to allow the developer to fine-tune the solution of these and other eventual discrepancies rtlibSession allows set a number of parameters: PageLeftMargin and PageWidth both set in twips. The first defines the margin that (and any margin less that that) should be rendered as zero in HTML, the other is used to calculate the right margin. As mentioned above, the default values of these parameters are 1 inch for PageLeftMargin and 21 cm for PageWidth.

Besides setting the values for these parameters you may choose to disable these rules. The named properties set via HTMLConversion are interpreted either by their value or presence/absence. To set the parameter use:

rtLibSession.HTMLConversion ("parmname") = "parmvalue"

to remove it (or set it to be False) use

rtLibSession.HTMLConversion ("parmname") = ""

Thus the setting:


disables an attempt to interpret the default left margin to be one inch (default margin will be 0) and


removes the parameter that requires to render as zero any margin less than the value of PageLeftMargin. As a result any left margin that you have entered in Notes will be rendered in browser.

Font mapping

Notes documents usually contain fonts defined by Notes client, for example "Default sens serif". These may mapped in OS to different real font names, but there is no good rule to render them always in the same way in browser. On the other hand we may want to use different fonts in browser and in Notes client, for example, we may want to display in Verdana all text in displayed as Arial in Notes client

Hence starting with a version 1.5 rtLibSession has a new named property FontSubstitution that allows define font mapping. There are four "reserved" font names "FONT_COURIER" (used to map Default Monospace), "FONT_HELV" (Default Sans Serif), "FONT_UNICODE" (Default Multilingual) and "FONT_ROMAN" (Default Serif).

For example, in order to display "Default Sans Serif" as Swiss Condensed, use a line:

rtLibSession.HTMLFontMapping("FONT_HELV") = {Swiss Condensed}

Any other font names are substituted literally. So in order to replace all Arial with Verdana in HTML rendering and to display Arial only if there is no Verdana present on client machine, use a line:

rtLibSession.HTMLFontMapping("Arial") = {Verdana, Arial}


In addition the code will probably run in a background or web agent thread, but you may need to obtain the HTML presentation with a particular and different set of hide-when conditions, for example to hide paragraphs from web even if the conversion code executes in background agent.

For example

rtLibSession.HideWhenStatus = RT_HIDE_WEB

will not render any paragraph marked to be hidden from web. As an argument you can use any values available for rtParagraphstyle.HideWhen

On the other hand any hide-when formula requires a context to get properly evaluated. Frequently hide-when formula use username or document fields. If a hide-when formula contains @Username and agent runs under other person's or server identity you will not be able to hide/show paragraph for a specific person. It may be a case that the value of hide-when formula depends on fields in particular document; by default the context for formula evaluation is the last document the particular rtContainer object has accessed – either by using getRichTextItem method or by using AppendItemValue or ReplaceItemValue methods. However you can force which document to use by setting:

Set rtLibSession.documentContext = doc

where doc is the NotesDocument in whose context you want to the formula to be evaluated. Note that this same document will also be used in order to evaluate any other formulas.


rtLib converts lists using CSS. In most cases the produced result is adequate. However you may want to override certain bullet types with custom images. In this case use HTMLListMarkerURL property of rtlibSession.

It defines URL of bullet image depending on list style. Value can be set for any of bullet styles available in Notes:











For example:

rtLibSession.HTMLListMarkerURL (RT_PSTYLE_SQUARELIST) = "/icons/my_square_bullet.gif"

rtLibSession.HTMLListMarkerURL (RT_PSTYLE_BULLET) = "/icons/my_round_bullet.gif"

By default rtLib approximates the most appropriate list style; HTMLListMarkerURL should be used only in case you wish to override the default style.

HTMLListMarkerType works similarly to HTMLListMarkerURL in that it allows to modify the bullet displayed. However it allows only to substitute one marker type used by CSS with another.

Thus normally list RT_STYLE_BULLET gets displayed as a full circle (CSS clause = list-style-type:disc;) and RT_STYLE_CIRCLELISTgets displayed as an empty circle (CSS clause = list-style-type:circle;). In case we define:

rtLibSession.HTMLListMarkerType (RT_PSTYLE_BULLET) = {circle}

we force both list types -- RT_STYLE_CIRCLELIST and RT_STYLE_BULLET to be displayed as empty circles.

Overriding default rendering

rtLib provides a flexible way to adjust the resulting HTML. Each rich text element has read/write HTML property. If you set this property to a particular string, this string will appear in the resulting HTML of object's parent. Thus you may modify a url of doclink so that it uses a particular view.

Dim repid As String, obj

Dim nl As rtNotelink

Dim doclinks As rtEnumeration

Dim ctx As rtContainer

Set doc = s.DocumentContext

Set ctx = New rtContainer

If ctx.getRichTextItem (doc, ITEM_BODY) Then

Set docLinks = ctx.Doclinks(True)

If Not docLinks Is Nothing Then

If Not docLinks.Collection Is Nothing Then

Do While doclinks.hasmoreElements

Set obj = doclinks.nextElement

If obj Isa RT_OBJ_HOTLINK Then

Set nl = obj.NoteLink

repID = nl.DBReplicaID

obj.HTML = {<a href="/__} + repid + {.nsf/$all/} + nl.docUNID + {">} + obj.getText + {</a>}

End If


End If

End If

End If