The hwriter package

hwriter is an easy-to-use package able to format and output R (from the R-project) objects in HTML format. It supports advanced formatting, tables, CSS styling, images, Javascript and provides a convenient mapping between R tables and HTML tables.
This is hwriter version 1.3, written by Gregoire Pau. Download hwriter_1.3.tar.gz here or on CRAN.

This page (generated by hwriter) shows examples of the package abilities and illustrates in detail the behavior of the optional arguments used by the function hwrite(). All the examples on this page are using the current CSS stylesheet.

1. Simple examples

Description

Example

Result

Writes a string.

hwrite('Hello world !', 'test.html')

Hello world !

Appends HTML elements in a page.
Writes a string with an hyperlink.

p=openPage('test.html')

hwrite('Hello', p, link='http://hello.com')
     hwrite(' world !', p)

     closePage(p)

Hello world !

Writes a vector.

hwrite(1:5, 'test.html')

Writes a matrix.

hwrite(iris[1:2,1:2],  'test.html', row.bgcolor='#ffdc98')

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

Appends HTML elements in a page. Inserts an image.

p=openPage('test.html')
     hwrite('This is an iris flower:', p, br=TRUE)
     hwriteImage('iris1.jpg', p, br=TRUE)
     hwrite('',p, br=TRUE)
     hwrite(c('Plantae','Monocots','Iris'), p)
     closePage(p)

This is an iris flower:

Plantae

Monocots

Iris

Outputs HTML code part.

hwrite('Monocots', link='http://mc.org')

<a href="http://mc.org">Monocots</a>

Combines HTML code parts.

hwrite(c('Plantae', hwrite('Monocots', link='http://mc.org'), 'Iris'), 'test.html')

Plantae

Monocots

Iris

Combines HTML code parts using nested calls.

img=hwriteImage('iris3.jpg', center=TRUE)
      cap=hwrite(c('Plantae', hwrite('Monocots', link='http://mc.org'), 'Iris'))
      hwrite(c(img, cap), 'test.html', dim=c(2,1), center=TRUE)

Plantae

Monocots

Iris

2. Advanced examples

Description

Example

Result

CSS styling.

p=openPage('test.html')

      hwrite(paste('The fox jumps ',hwrite('over',
link='http://over.com'), ' the ', hwrite('red', style='color:#cc3355'), '
 wall.', collapse=''), p, br=TRUE)
      hwrite(paste('The function', hwrite( 'hwrite()', style='font-family:monospace'), 'is cool !'), p)
      closePage(p)

The fox jumps over the red wall.
The function hwrite() is cool !

Banner of multisized images, with CSS tiled background and hyperlink.

     hwriteImage('iris1.jpg', 'test.html', width=c(50,75,100,125),
link=c('http://www.ab1.com', 'http://www.ab2.com', 'http://www.ab3.com',
 'http://www.ab4.com'), table.style='  background-image:
url(motif.png);background-repeat: repeat')

Named anchors and customized CSS hyperlinks using classes in the current CSS stylesheet and margins.

      p=openPage('test.html', link.css='hwriter.css')
      hwrite('Please select an item:', p, br=TRUE)
      items=c('Gene', 'mRNA', 'Polypeptide', 'Protein')
      links=paste('http://en.wikipedia.org/wiki/', items, sep='')
      hwrite(hwrite(items, class='example', link=links, table=FALSE), p, border=0)
      sections=c('Simple examples', 'Advanced examples', 'Details')
      nanchors=c('#se', '#ae', '#de')

      hwrite(hwrite(sections, class='example2', link=nanchors,
table=FALSE), p, dim=c(3,1), style='margin:0px ; padding:8px',
table.style='margin-top:20px', border=0)
      closePage(p)

Please select an item:

Pointing columns and rows. Changing background color, alignments, hyperlinks and CSS style.

     colors=c('#ffaaff','#ddaaff','#bbaaff','#99aaff','#55aaff')

     hwrite(iris[1:7,1:4], 'test.html', center=TRUE,
row.bgcolor=list('#aaffaa', '3'='#ffffaa', '5'=colors),
col.style=list(Sepal.Length='font-style:italic',Petal.Length='text-align:center'),
 row.style=list('font-weight:bold'),
col.link=list(Sepal.Width=iris$Sepal.Width[1:7]))

	Sepal.Length	Sepal.Width	Petal.Length	Petal.Width
1	5.1	3.5	1.4	0.2
2	4.9	3	1.4	0.2
3	4.7	3.2	1.3	0.2
4	4.6	3.1	1.5	0.2
5	5	3.6	1.4	0.2
6	5.4	3.9	1.7	0.4
7	4.6	3.4	1.4	0.3

Color scale bar.

     scale=round(seq(0, 1, len=8), 2)
     colors=rgb(colorRamp(c('#ff0000', '#ffff00', '#ffffff'))(scale), max=255)
     band=hwrite(scale, 'test.html', bgcolor=colors, style='color: black', col.width=rep(20, 8))
    

0.14

0.29

0.43

0.57

0.71

0.86

Complex layout using borderless tables.

img=hwriteImage('iris1.jpg', center=TRUE)
      cap=hwrite(c('Plantae', hwrite('Monocots', link='http://mc.org'), 'Iris'))
      iris=hwrite(c(img, cap), dim=c(2,1), center=TRUE, border=0)
      colors=rgb(colorRamp(c('#7f007f', '#aaaaaa'))(seq(0, 1, len=5)), max=255)
      band=hwrite(c('+', rep('&nbsp;',3), '0'), bgcolor=colors, dim=c(5,1), border=0, style='color: white')
      hwrite(c(iris,band), 'test.html', border=0)

Plantae

Monocots

Iris

Combining matrix of images and hyperlinking.

     himg=hwriteImage(c('iris1.jpg','iris2.jpg','iris3.jpg'),
link=c('http://en.wikipedia.org/wiki/Iris_virginica',
'http://en.wikipedia.org/wiki/Iris_versicolor',
'http://en.wikipedia.org/wiki/Iris_virginica'), table=FALSE)
     mat=rbind(himg, c('Setosa','Versicolor','Virginica'))
     rownames(mat)=c('Image', 'Species')

     hwrite(mat, 'test.html', br=TRUE, center=TRUE,
row.bgcolor=list(Species=c('#ffaacc', '#ff88aa', '#ff6688')),
col.bgcolor='#ffffaa', row.style=list(Species='text-align:center'))
     

Image
Species	Setosa	Versicolor	Virginica

Fancy patchwork. Advanced text formatting.

     cells=matrix('', nr=6, nc=5)
     hotcolors=rgb(colorRamp(c('#ff0000', '#ffff00', '#ffffff'))(runif(length(cells))), max=255)
     bgcolor=array(hotcolors, dim=dim(cells))
     rownames(cells)=1:nrow(cells)
     patchwork=hwrite(cells, bgcolor=bgcolor, col.width=rep('16px', nrow(cells)))

     text='La volupt&eacute; de la chair est une chose de la vie des
 sens au meme titre que le regard pur, que la pure saveur d\'un beau
fruit sur notre langue...'
     text=paste(hwrite(text, br=TRUE), hwrite('Rainer Maria Rilke', style='font-style:italic'))

     hwrite(c(patchwork,text), 'test.html', br=TRUE, center=TRUE,
col.width=c(NA,'200px'), style='text-align:justify', border=0,
cellspacing=10)
     

1
2
3
4
5
6

La volupté de la chair est une chose de la vie des sens au meme titre que le regard pur, que la pure saveur d'un beau fruit sur notre langue...
Rainer Maria Rilke

Sections (divisions) and CSS styling.

     p=openPage('test.html')

     codestyle='margin: 10px; padding: 10px; background-color: #aaffaa;
border: solid 1px black; font-family: monospace ; text-align: left'
     hwrite('Please type the following commands:', p)

     hwrite(paste(hwrite(c('> library(rgl)', '> example(rgl)'),
br=TRUE, table=FALSE), collapse=''), p, style=codestyle, div=TRUE)
     hwrite('to see nice examples of the package rgl.', p)
     closePage(p)

Please type the following commands:

> library(rgl)
> example(rgl)

to see nice examples of the package rgl.

Styling sections using CSS classes defined in the current CSS stylesheet.

     p=openPage('test.html', link.css='hwriter.css')

     text=paste(hwrite('And the king said to her:', class='narrator'),
hwrite('What is the matter with you ?', class='king', div=TRUE),
hwrite('And she answered:', class='narrator'), hwrite('Give me your son
that we may eat...', class='king', div=TRUE), sep='')
     hwrite(text, p, div=TRUE, class='textbox')
     closePage(p)

And the king said to her:

What is the matter with you ?

And she answered:

Give me your son that we may eat...

Use of Javascript through 'onmouseover' and 'onmouseout' attributes.

     p=openPage('test.html')
     hwrite('Pass the mouse over:', p)

     hwrite(array('&nbsp;',dim=c(6,6)), p,
onmouseover="this.bgColor='#ffaaaa'", onmouseout="this.bgColor='white'",
 bgcolor='white', col.width=rep(18,6), style='padding:0px; margin:0px')
     closePage(p)

Pass the mouse over:

Build HTML tags using 'hmakeTag' to render additonal HTML objects.

     p=openPage('test.html')
     hwrite('This is an itemized bullet list:', p)
     li=paste(hmakeTag('li', c('Abstract', 'Methods', 'Results')), collapse='')
     hwrite(hmakeTag('ul', li, style='font-weight:bold; text-align:left'), p) 
     closePage(p)

This is an itemized bullet list:

Abstract
Methods
Results

3.1. General arguments

Argument

Description

Example

Result

Inserts a carriage return (line break, newline) at the end of the HTML element.

p=openPage('test.html')
     hwrite('The fox ', p)
     hwrite('jumps', p, br=TRUE)
     hwrite('over the...', p, br=TRUE)
     closePage(p)

The fox jumps
over the...

table

Controls if the object should be written as an HTML table. Default is "TRUE" for vectors and matrices, and "FALSE" otherwise. If set to "FALSE", the object is written as a vector (or a matrix) of HTML elements.

p=openPage('test.html')
    hwrite(1:6, p, br=TRUE)
    hwrite(1:6, p, table=FALSE)
    closePage(p)

1 2 3 4 5 6

name

Names the HTML element for further reference using hyperlinks.

p=openPage('test.html')
     hwrite(hwrite('Section 1.', name='s1'), p, heading=3)
     hwrite(c('Go to this ', hwrite('section', link='#s1'), ' or this ', hwrite('one', link='#s2'), '.'), p, table=FALSE)
     hwrite(hwrite('Section 2.', name='s2'), p, heading=3)
     hwrite('Another section...', p)
    closePage(p)

Section 1.

Go to this section or this one .

Section 2.

Another section...

link

Adds hyperlink(s) (anchor, hypertext) to the HTML element.

hwrite('The fox', 'test.html', link='http://www.fox.com')

The fox

div

Places the HTML element into a div HTML section, using the <div> HTML tag. This is helpful for styling a section.

p=openPage('test.html', link.css='hwriter.css')
    hwrite('In Greek mythology, a cyclops is a member of...', p, div=TRUE, class='king')
    closePage(p)

In Greek mythology, a cyclops is a member of...

center

Centers the HTML element. This element may interfere with the current CSS style. Please consider the CSS style attribute "text-align" instead.

p=openPage('test.html')
     hwrite('The fox', p, center=TRUE)
     hwrite('jumps over the...', p, center=TRUE)
     closePage(p)

The foxjumps over the...

...

Additional arguments are added to the HTML element as HTML attributes. For HTML tables, attributes are distributed on table cells using R recycling rules. For text elements, a <span> HTML tag (or <div> if 'div' is 'TRUE') is used to accommodate the attributes.

 hwrite(1:3, k=1:2)

3.2. Text element specific arguments

Argument

Description

Example

Result

heading

Changes the heading level of the HTML element. Heading styles can be modified in the current CSS stylesheet.

p=openPage('test.html')
    hwrite('Heading 1', p, heading=1)
    hwrite('Heading 2', p, heading=2)
    hwrite('Heading 3', p, heading=3)
    closePage(p)

Heading 1

Heading 2

Heading 3

style
class

Uses an CSS style (inline) or a CSS class (defined in the current stylesheet) to render the HTML element.
CSS styles are versatile and allow to change the current typeface, color, margins, font, boldness, italic, padding, alignement... See the W3C reference or this wizard to generate new styles.
By default, the style is changed on the fragment of a sentence, using the <span> HTML tag. Use the combination with the div argument to change the style of a whole section.

p=openPage('test.html', link.css='hwriter.css')

     hwrite('The fox ', p, style='font-weight: bold')
     hwrite('jumps over ', p, style='font-family: monospace;color: #ff2233')
     hwrite('the wall.', p, style='text-align: right; font-style: italic')

     hwrite('hwriter', p, div=TRUE, style='margin:16px; font-size:150%; text-align:right')

     hwrite('Socrates was a Classical Greek philosopher.', p, class='king', div=TRUE)

     closePage(p)

The fox jumps over the wall.

hwriter

Socrates was a Classical Greek philosopher.

3.3. Vector specific arguments

Argument

Description

Example

Result

dim

Sets the dimension of the output HTML table.

hwrite(1:6, 'test.html', dim=c(2,3))

1	3	5
2	4	6

byrow

Controls if the output HTML table should be filled by rows first. If set to "FALSE", the table is filled by columns first. Default is "FALSE".

hwrite(1:6, 'test.html', dim=c(2,3), byrow=TRUE)

1	2	3
4	5	6

names

Controls if the names of a named vector should be shown. Default is "TRUE".

p=openPage('test.html')
     z=c(red=0.5, green=0.6, blue=0.7)
     hwrite(z, p, br=TRUE)
     hwrite(z, p, names=FALSE)
     closePage(p)

red	green	blue
0.5	0.6	0.7

0.5

0.6

0.7

3.4. Matrix/table and vector specific arguments

Argument

Description

Example

Result

border

Specifies the table border width. A value of 0 implies that no borders will be drawn. This argument may interfere with the 'border' CSS style attribute.

hwrite(iris[1:4,1:2], 'test.html', border=0)

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3
3	4.7	3.2
4	4.6	3.1

row.names
col.names

Specifies if the row (resp. column) names should be displayed.

p=openPage('test.html')

     hwrite(iris[1:2,1:2], p, br=TRUE, row.names=FALSE)

     hwrite(iris[1:2,1:2], p, br=TRUE, row.names=FALSE, col.names=FALSE)

     closePage(p)

Sepal.Length	Sepal.Width
5.1	3.5
4.9	3

5.1	3.5
4.9	3

cellspacing
cellpadding

Defines the padding and spacing space in pixels between cells. These arguments may interfere with the 'border' and 'padding' CSS style attributes.

hwrite(iris[1:2,1:2], 'test.html', center=TRUE, br=TRUE, row.bgcolor='#ffaaaa', cellspacing=10, table.class='raw')
    

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

width
col.width

Defines global table width and column widths in HTML units (pixels or %).
'width' specifies the table global width.
'col.width' contains either a vector of widths (of size equals to the number of columns) which may contain NAs or a named vector of widths which point to some column names.

p=openPage('test.html')

     hwrite(iris[1:2,1:2], p, br=TRUE, width='150px', row.names=FALSE, col.names=FALSE)

     hwrite(iris[1:2,1:2], p, br=TRUE, col.width=c(Sepal.Length='150px'))

     closePage(p)

5.1	3.5
4.9	3

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

style
class
bgcolor
link
...

Distributes an attribute on table cells, using R recycling rules.
'style' and 'class' distributes the HTML CSS styling attributes, 'bgcolor' distributes the background color HTML attribute but any valid HTML attribute can be used.
Value of the attribute could be either a character vector or a matrix and may contain NAs to omit cells. Matrices may contain one extra row and/or column to target heading cells.

p=openPage('test.html')

     hwrite(iris[1:2,1:2], p, br=TRUE, style=matrix(c(NA,
'color:#ff0000', 'color:#0000ff; font-style:italic; text-align:right',
NA),nr=2,nc=2))

     hwrite(iris[1:2,1:2], p, br=TRUE, bgcolor=matrix(c('#aaffaa', NA, '#ffffaa', '#ffffff','#aaaaff', NA),nr=3,nc=2))

     hwrite(1:4, p, br=TRUE, bgcolor=c('#66ffff', '#99ffee', '#ccffdd', '#ffffcc'), link=1:4)

     hwrite(array(1:20, dim=c(4,5)), p, br=TRUE, bgcolor=c('#ffffff',
'#ffbbaa', '#ff9977', '#ffbbaa', '#ff5500'), link=matrix(1:4, nr=2,
nc=2))

     closePage(p)

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

1	5	9	13	17
2	6	10	14	18
3	7	11	15	19
4	8	12	16	20

row.style
col.style
row.bgcolor
col.bgcolor
row.link
col.link
row.*
col.*

Distributes an attribute on table cells, according to row/columns.
The argument may contain a list of vectors of values or a vector of values. Named lists (or vectors) point the corresponding rows/columns, according to their names. Unnamed lists (or vectors) point the rows/columns in the numeric order and NAs can be used to omit rows/columns. If sizes don't match, values are recycled using R rules.

p=openPage('test.html')

     hwrite(iris[1:2,1:2], p, br=TRUE, row.bgcolor='#ffffaa')


     hwrite(iris[1:2,1:2], p, br=TRUE,
row.style=list('font-weight:bold'),  col.style=list(Sepal.Length =
'text-align:left; color:#aa0000'))

     hwrite(iris[1:3,1:2], p,
br=TRUE, col.bgcolor=list(Sepal.Width=c('#66ffff', '#99ffee', '#ccffdd',
 '#ffffcc')), row.link=list(NA, c('a', 'b'), NA))

     closePage(p)

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3
3	4.7	3.2

table.style
table.class
table.*

Uses a global table attribute to render the HTML table.
The attribute is added to the main <table> tag and should contain a single value. Some uses include setting of the CSS 'border' and 'margin' attributes that cannot be distributed on cells.

p=openPage('test.html')


    hwrite(iris[1:2,1:2], p, br=TRUE, table.style='font-family:
monospace ; border-spacing: 5px; border-collapse: collapse;
background-color: white')

    hwrite(iris[1:2,1:2], p, br=TRUE, table.frame='void')

    closePage(p)

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

	Sepal.Length	Sepal.Width
1	5.1	3.5
2	4.9	3

(Page generated on Fri Nov 22 17:38:48 2013 by hwriter 1.3)

The hwriter package

1. Simple examples

2. Advanced examples

3. Detailed description of hwrite() arguments

3.1. General arguments

Section 1.

Section 2.

3.2. Text element specific arguments

Heading 1

Heading 2

Heading 3

3.3. Vector specific arguments

3.4. Matrix/table and vector specific arguments