Using HTML Procedures in an SQR Program
This section provides an overview of HTML procedures and discusses how to:
Use HTML procedures.
Position objects.
Display records in tables.
Create headings.
Highlight text.
Create links.
Include images.
Display text in lists.
Format paragraphs.
Incorporate your own HTML tags.
To enhance the appearance of HTML output, use HTML procedures in an SQR program.
An SQR program with these procedures generates output as described previously in “Using PRINTER:HT,” with these exceptions:
The <PRE> and </PRE> HTML tags are not used.
Text appears in a proportional font, such as Arial.
Positioning values that are specified in the SQR program are ignored.
Text, HTML tags, and other information are placed in the HTML output in the order in which they are generated by the SQR program.
White space, such as spaces between PRINT commands, is removed.
When using the HTML procedures, include the html.inc file. As before, you must run the SQR program with the -PRINTER:HT command-line flag.
The SQR program must also call the html_on procedure at the start of the program. The command that calls this procedure is:
do html_on
Additionally, the program must specify a large page length to prevent page breaks. SQR automatically inserts the page navigation links and an <HR> HTML tag at a page break. If a page break occurs in the middle of an HTML construct, such as a table, the output can appear incorrectly. Use the DECLARE-LAYOUT command with a large MAX-LINES setting to prevent page breaks from occurring.
When HTML procedures are activated:
HTML output is generated without the <PRE> and </PRE> tags.
All position qualifiers in the SQR program are ignored, and program output and HTML tags are placed in the output file in the order in which they are generated, regardless of their position qualifiers.
The text that is printed in a BEGIN-HEADING section does not appear at the top of a page.
Because no positioning is done, text in the heading appears at the bottom.
White space, such as spaces between PRINT commands, is removed.
Thus, you must use the HTML procedures to format the report.
The following code example does not use the HTML procedures to format the output:
print 'Report summary:' (1,1)
print 'Amount billed:' (3,1)
print #amount_amount (3,20)
print 'Total billed:' (4,1)
print #total_amount (4,20)
In this case, all of the text appears on the same line and with no spaces between the data.
With the HTML procedures for line breaks and a table, you can format the output properly.
The following code example uses the html_br procedure to separate the first two lines of text. The html_table, html_tr, html_td, and html_table_end procedures display the totals in a tabular format. An empty string is passed to each procedure as it is called. This empty string is required if no other argument is passed.
print 'Report summary:' (1,1)
do html_br(2,'')
do html_table('')
do html_tr('')
do html_td('WIDTH=300')
print 'Amount billed:' (3,1)
do html_td('')
print #amount_amount (3,20)
do html_tr('')
do html_td('WIDTH=300')
print 'Total billed:' (4,1)
do html_td('')
print #total_amount (4,20)
do html_table_end
When HTML procedures are activated, all positioning values in the SQR program are ignored. Thus, the position values cannot be used to display records in a tabular format. To display records in a tabular format, use the following procedures:
Description |
Beginning Procedure |
End Procedure |
---|---|---|
Create a table. |
html_table |
html_table_end |
Create a caption. The end is typically implied and html_caption_end is not required, but you can use it for completeness. |
html_caption |
html_caption_end |
Create rows. The end is typically implied and html_tr_end is not required, but you can use it for completeness. |
html_tr |
html_tr_end |
Create column headings. The end is typically implied and html_th_end is not required, but you can use it for completeness. |
html_th |
html_th_end |
Create columns. The end is typically implied and html_td_end is not required, but you can use it for completeness. |
html_td |
html_td_end |
The following sample program uses these table procedures to display information in a tabular format:
Program ex28a.sqr
#include 'html.inc'
begin-program
do main
end-program
! set a large page length to prevent page breaks
begin-setup
declare-layout default
max-lines=750
end-declare
end-setup
begin-procedure main
! turn on HTML procedures
do html_on
! start the table and display the column headings
do html_table('border')
do html_caption('')
print 'Customer Records' (1,1)
do html_tr('')
do html_th('')
print 'Cust No' (+1,1)
do html_th('')
print 'Name' (,10)
! display each record
begin-select
do html_tr('')
do html_td('')
cust_num (1,1,6) edit 099999
do html_td('')
name (1,10,25)
next-listing skiplines=1 need=1
from customers
end-select
! end the table
do html_table_end
end-procedure
The heading procedures display text by using heading levels like those in a book. The available heading levels range from 1 to 6; a first-level heading is the highest. To use the heading procedures, call the appropriate heading procedure before the text is generated. After the text is generated, call the corresponding end procedure.
The following code example displays text as a second-level heading:
do html_h2('')
print 'A Level 2 Heading' (1,1)
do html_h2_end
The highlighting procedures enable you to display text in the various HTML highlighting styles. Highlighting is also called logical markup.
To use the highlighting procedures, call the appropriate highlighting procedure before the text is generated. After the text is generated, call the corresponding end procedure.
The following highlighting procedures are available:
Type of Highlighting |
Beginning Procedure |
End Procedure |
---|---|---|
Blink |
html_blink |
html_blink_end |
Citation |
html_cite |
html_cite_end |
Code |
html_code |
html_code_end |
Keyboard |
html_kbd |
html_kbd_end |
Sample |
html_sample |
html_sample_end |
Strike |
html_strike |
html_strike_end |
Subscript |
html_sub |
html_sub_end |
Superscript |
html_sup |
html_sup_end |
The following code example displays text in the subscript style:
print 'Here is ' (1,1)
do html_sub('')
print 'subscript' ()
do html_sub_end
print ' text' ()
The link procedures enable you to create links and link anchors. When a user clicks a link, the web browser switches to the top of the specified HTML document, to a point within the specified document, or to a link anchor within the same document. A link can point to the home page of a website, for example.
To insert a link, use the html_a procedure to format the information that is to become the link, and use the html_a_end procedure to mark the end of the link. Two useful attributes for the html_a procedure are the HREF and NAME attributes:
Use the HREF attribute to specify the location to which the link points.
Use the NAME attribute to specify an anchor to which a link can point.
These attributes are passed as arguments to the html_a procedure.
The following code example creates an anchor and two links. The anchor is positioned at the top of the document. The first link points to the HTML home.html document. The second link points to the anchor named TOP in the current document. Note the # sign in the argument, which indicates that the named anchor is a point within a document. The third link points to an anchor named POINT1 in the mydoc.html document.
do html_a('HREF=home.html')
print 'Goto home page' ()
do html_a_end
do html_a('NAME=TOP')
do html_a_end
print 'At the top of document' ()
do html_br(40, '')
print 'At the bottom of document' ()
do html_p('')
do html_a('HREF=#TOP')
print 'Goto top of document' ()
do html_a_end
do html_a ('HREF=mydoc.html#POINT1')
print 'Goto point1 in mydoc.html' ()
do html_a_end
You can include an image in an HTML output with the PRINT-IMAGE command or the html_img procedure. Both of these produce the <IMG> HTML tag.
The PRINT-IMAGE command displays images for all printer types but enables you to specify only the image type and source. The html_img procedure displays images only for the HTML printer type, but it enables you to specify any of the attributes that are available for an <IMG> HTML tag.
For HTML output, you can use only Graphics Interchange Format (GIF) or JPEG files. With PRINT-IMAGE, use the TYPE=GIF-FILE or TYPE=JPEG-FILE argument, respectively.
The list procedures display lists. To use these procedures, call the appropriate procedure before the list is generated. After the list is generated, call the corresponding end procedure.
The following list procedures are available:
List Type |
Beginning Procedure |
End Procedure |
---|---|---|
Definition (terms and their definitions) |
html_dl |
html_dl_end |
Directory |
html_dir |
html_dir_end |
Menus |
html_menu |
html_menu_end |
Ordered (numbered or lettered) |
html_ol |
html_ol_end |
Unordered (bulleted) |
html_ul |
html_ul_end |
To display a list, except for the definition list, call the appropriate list procedure before starting the output. Call html_li to identify each item in the list; you can also call html_li_end for completeness. After specifying the output, call the corresponding end procedure.
The following code example displays an ordered list:
do html_ol('')
do html_li('')
print 'First item in list' (1,1)
do html_li_end
do html_li('')
print 'Second item in list' (+1,1)
do html_li_end
do html_li('')
print 'Last item in list' (+1,1)
do html_li_end
do html_ol_end
To display a definition list, call html_dl before starting the output. Call html_dt to identify a term and html_dd to identify a definition. After specifying the output, call html_dl_end. You can also call html_dd_end and html_dt_end for completeness.
The following code example displays a definition list:
do html_dl('')
do html_dt('')
print 'A daisy' (1,1)
do html_dt_end
do html_dd('')
print 'A sweet and innocent flower' (+1,1)
do html_dd_end
do html_dt('')
print 'A rose' (+1,1)
do html_dt_end
do html_dd('')
print 'A very passionate flower' (+1,1)
do html_dd_end
do html_ol_end
The HTML procedures provide various paragraph formatting capabilities. To use these procedures, call the appropriate paragraph procedure before the list is created.
The following procedures are available:
Formatting Type |
Beginning Procedure |
End Procedure |
---|---|---|
Paragraph break |
html_p |
html_p_end Many HTML constructs imply an end of paragraph; thus, the html_th_end procedure is not needed, but you can use it for completeness. |
Line break |
html_br |
NA |
Horizontal divider (usually a sculpted line) |
html_hr |
NA |
Prevent text wrapping |
html_nobr |
html_nobr_end |
The following code example uses the paragraph formatting procedures to format text into paragraphs:
print 'Here is some normal text' (1,1)
do html_p('ALIGN=RIGHT')
print 'Here is right aligned text' (+1,1)
do html_br(1,'')
print 'and a line break' (+1,1)
do html_p_end
do html_hr('')
do html_nobr('')
print 'A very long line of text that cannot be wrapped' (+1,1)
do html_nobr_end
You can incorporate your own HTML tags into the HTML output. To do so, use the PRINT command with the CODE-PRINTER=HT argument.
Text that is printed with this argument is placed only in the HTML output that is generated when the HTML printer type is specified. With all other printer types, the text is not placed in the output. In addition, the specified text is placed directly in the HTML output without any modifications, such as the mapping of reserved characters.
The following code example uses the <B> HTML tag to print bold text:
print '<B>' () code-printer=ht
print 'Bold text' ()
print '</B>' () code-printer=ht