Title

html -- Combine output in an html file

Contents

Sub-command Description

html page Create a page in memory

cmd, out(html p) Add data (tables)

html bits Add text, graphics, controls, stata log, page breaks

html write Write/display a page

html div Create or select a page division

html redirect Select a different page.

html query Display page styles

html clear Clear the html contents in memory

htm html See below

Overall Description

This suite of commands is for incorporating multiple elements into a single (html) document. The usual, simplest, sequence would be something like:

html page, title(New Stats) rev(today) des(of current interest)

tfreq a b c, out(html p)

tstats d e f, by(g) out(html p)

html write recent stats

o- Output from any command that uses the out option can be included.

o- Stata graphs in memory, or any external web-compatible image files can be included.

o- Table-of-Contents entries create a menu at the top of the page that can be used to skip down to any point.

o- Dynamic displays can be created by using controls to show/hide different bits.

html page

Syntax

html page [page-id] [, title(text) revision(text) description(text) styles(css|filepath) ]

Description

html page creates or replaces a page in memory, which becomes the destination for html content. An existing page-id will be replaced with a fresh empty one.
page-id can be omitted, in which case pg1 is used, but that detail can be safely ignored.

Options

title(text), revision(text), and description(text) each specify text for a pre-defined field that will display at the top of the page.
There are no formatting restrictions for text -- eg, revision can be a date or number or whatever you like. These three fields are also included as html meta-data in the written page.

styles(css|filepath) adds user-defined css styles, that can then be referenced by any elements on the page. css is explicit css style definitions; filepath points to a css file.

html bits

Syntax

html bits, options

where options is any sequence composed of the following:

toc(text)
paragraph(text)
text(text)
file(fileref)
image(details)
log(details)
break
cbox(details)
dropdown(details)
buttons(details)

Description

Each specified option is added in order. Sub-options and related details are described in their own section, below all the options.

Options

toc(text) adds text both in a menu at the top of the page, and as a section marker in the body of the page. Selecting the the menu item will jump to the section on the page.

paragraph(text) adds text, as a paragraph with class bitsp.

text(text) adds the text, exactly, on the page. It can/should include markup.

file(fileref) adds the contents of fileref, exactly, on the page. The contents can/should include markup.

image(stgraph|filepath [, tip(text) width(pixels)]) adds an image/graphic to the page. stgraph is the name of a Stata graph in memory.
If you didn't assign one yourself, Stata uses Graph, and the capitalization matters.
width() only has an effect when placing graphs from memory - images from disk files are not adjusted. The default width() is 800 pixels.

log(command [; command ...]) simply logs the results of all included commands, and then places the log contents on the page.

break adds a printer page break.

cbox(name, display(text) [tip(text) icheck]) adds a checkbox control. icheck specifies that the box is initially checked.

dropdown(name, [i]choice(text) [...]) adds a dropdown control. Only one of the choice() options can be ichoice(); that one will be initially selected.

buttons(name, [i]btn(button-def) [...] [colors]) adds push-button controls. Only one of the btn() options can be ibtn(); that one will be initially selected.
Each button-def is:

display(text) [tip(text)]

colors is the option:

colors(normal hover chosen)

where normal, hover, and chosen are each a valid CSS/html color to use for that purpose.

Sub-options

o- The text of display() or choice() is what will be visible on the page.

o- The text of tip() will show up as a tool-tip when the cursor is over the relevant element.

o- name is used to uniquely identify controls on the page.

o- Each name should, therefore, be distinct.

o- name cannot contain spaces.

o- The state of a control affects the display when its name is used in a showif() option. See html div

html write

Syntax

html write [filepath] [, page(page-id)]

Description

html write writes a page to disk, and displays it in a browser. page-id can be omitted when there is only one.

When no filepath is specified, the file _html.html is (over)written in the settings directory.

html div

Syntax

html div top

html div left

html div div-id [, showif(condition) parent(parent-id) ]

Description

In html, a <div> is an abstract container for other things. This command specifies that subsequent html bits and out(html p) options place their things in the specified div.

There are two main reasons to use this command:

1) to place things in a top- or left- 'navigation bar'

2) to create a page that responds to user choices

Navbar: To place things in a navbar, execute either html div top or html div left. All subsequent content will then go to the relevant navbar, until another div-id (or page!) is specified.

The page title(), rev(), des(), as well as the toc() menu are all placed in div top automatically. Anything you add will go below those.

The size of the navbars is determined by the size of the stuff you place there; if they get too big, they won't be much like navbars anymore.

You should be able to place all content on the main part of the page first, then switch to top and/or left, without the need to switch back to the main part of the page.
However, you can switch back by specifying any new html div div-id, without specifying parent().

Dynamic content: You can achieve a variety of dynamic effects, from the user's perspective, by using the showif(conditions) option.
For example, you can re-arrange or redefine table rows or columns, change colors or highlighting, expand or collapse things, etc.

You accomplish this by generating each arrangement you might like to see, sending versions to separate divs, and specifying alternating conditions in showif(),
so that when the control changes, one version is swapped for another. When done correctly, the control will appear to modify the display, not hide one thing and show another.

Or, of course, you can just specify different things to show.

Options

showif(condition) checks the values of controls (buttons, dropdowns, checkboxes) to determine when its div will be visible.
condition is any stata logical expression, using control names as variables.

In condition, a control is referred to as:

controls.name

Values are all strings:
For buttons and dropdown choices, the values are the exact option text; for checkboxes the values are either yes or no.

condition can be a complex expression referring to many controls, eg:

showif(controls.year<"2009" & contols.color=="yellow" | controls.override=="yes")

parent(parent-id) is used to create a div inside another div, instead of in the main body of the page. For examle, to show/hide a set of buttons in the navbar,
the buttons would need to go in a div with a showif() option, which in turn would need to be in the navbar:

html div top

html bits, checkbox(mastercheck, d(Choose your destiny) iyes)

html div forbuttons, showif(mastercheck=="yes") parent(top)

html bits, buttons(pickone, btn(d(A)) btn(d(B)) btn(d(C)))

html redirect

Syntax

html redirect page-id

Description

It is possible to compose several pages at the same time, in case some onerous bit of data processing is the basis for more than one report.
To switch the destination from one page to another, use this command.

html query

Syntax

html query [debug]

Description

With no parameter, this command will display most of the css styles defined for the page. You might use this information to re-define a style by using html page, styles(),
and specifying one of the defined selectors with your own choice of attributes.

With any main parameter, this command will display a summary of the html pages in memory, useful for debugging.

htm html

If you installed this from ssc, this command will actually be htm, not html, since the SSC repository already contained a command called html.
You can just read htm wherever you see a reference to html, or you can do htm html, which will overwrite any exising html command you have installed, and make it refer to this command.

If you installed from any other source, html and htm will work interchangeably.