QScript HtmlBuilder

From Q
Jump to navigation Jump to search

HtmlBuilder

HTML builder which creates a HTML fragment, which is used as input when writing to text items. The HTML fragment is constructed by appending elements such as paragraphs, bulleted lists and tables to it.

append(item)

Appends a text fragment to the end of the HTML fragment, without any spacing afterwards. Text fragments are created using createText() or concatenateText() and allow for complex formatting within a paragraph.
itemA HTML fragment created with createText() or concatenateText() containing formatted text.
Example:
var html = Q.htmlBuilder();
var bold_text = html.createText('Important: ', { bold: true });
var normal_text = html.createText('This is regular text');
var combined = html.concatenateText(bold_text, normal_text);
html.append(combined);

appendBulletted(items, style)

Appends a bulleted list.
itemsAn array of strings. Plain text.
styleAn optional style dictionary (see setStyle()) to override formatting for this list.
Example:
var html = Q.htmlBuilder();
html.appendBulletted(['Coke tastes great', 'Diet drinks becoming more popular']);

appendBullettedItem(item, style)

Appends a single text fragment to a bulleted list that was started with startBullettedList(). This allows you to add complex formatted text fragments created with createText() and concatenateText() as bulleted items.
itemA HTML fragment created with createText() or concatenateText() containing the formatted text for the bulleted item.
styleAn optional style dictionary (see setStyle()) to override formatting for this item.
Example:
var html = Q.htmlBuilder();
html.startBullettedList();
var bold_text = html.createText('Important: ', { bold: true });
var regular_text = html.createText('This is a regular item');
var combined_item = html.concatenateText(bold_text, regular_text);
html.appendBullettedItem(combined_item);
html.endBullettedList();

appendHyperlink(text, url, new_tab, style)

Appends a hyperlink with the provided url to the end of the HTML fragment, without any spacing afterwards.
textThe text to be displayed.
urlThe url for this hyperlink. This can be a relative link, e.g., #page={page_guid} can be used to link to another page within the document.
new_tabWhether the url should be opened in a new tab or not.
styleAn optional style dictionary (see setStyle()) to override formatting for this hyperlink.

appendParagraph(paragraph_text, style)

Appends a paragraph containing text to the end of the HTML fragment. The difference between append() and appendParagraph() is that this will leave a blank line after the text.

You may call this without any text to append a new blank line. For example, html.appendParagraph()

paragraph_textPlain text. HTML tags not supported.
styleAn optional style dictionary (see setStyle()) to override formatting for this text.
Example:
var html = Q.htmlBuilder();
html.appendParagraph('Most interesting results in the survey:');

appendParagraphWithSpan(paragraph_text, style)

Appends a paragraph containing text to the end of the HTML fragment. The difference between append() and appendParagraph() is that this will leave a blank line after the text.

You may call this without any text to append a new blank line. For example, html.appendParagraph()

paragraph_textPlain text. HTML tags not supported.
styleAn optional style dictionary (see setStyle()) to override formatting for this text.
Example:
var html = Q.htmlBuilder();
html.appendParagraph(html.createText('hi', { color: red });

appendTable(table, column_widths, row_separator, style)

Appends a table of text, whose columns will be aligned using spaces. The text will be formatted in a monospace font.
tableThe 2D array of text to show on the table.
column_widthsAn optional array of numbers. Each number represents the size of each column (in characters), after which the text will wrap onto a new line.
row_separatorAn optional string which can be used to separate rows in the table. If not null, this text will be repeated on a new line between each row.
styleAn optional style dictionary (see setStyle()) to override formatting for this table.
Example:
var html = Q.htmlBuilder();
html.appendTable([
    ['Brand', 'NPS score'],
    ['Coke', '30'],
    ['Diet Coke', '40']
]);
html.appendTable([
    ['Brand', 'NPS score'],
    ['Coke', '30'],
    ['Diet Coke', '40'],
    ['This drink gives you wings', '10']
], [15, 10], '-', { size: 8 });

concatenateText(items)

Combines multiple text fragments created with createText() into a single HTML fragment that can be appended to the HTML builder. This allows for complex formatting within a single text element where different parts have different styles.
itemsAn array of HTML fragments created with createText().
Returns:An HTMLFragment that can be appended to the HTML builder.
Example:
var html = Q.htmlBuilder();
var brand_label = html.createText('Brand: ', { bold: true });
var brand_name = html.createText('Coca-Cola', { color: 'red', italic: true });
var score_label = html.createText(' (Score: ', { size: 10 });
var score_value = html.createText('85', { size: 10, bold: true });
var closing = html.createText(')', { size: 10 });
var combined = html.concatenateText([brand_label, brand_name, score_label, score_value, closing]);
html.appendParagraphWithSpan(combined);

createHyperlink(text, url, new_tab, style)

Creates a hyperlink text fragment with the specified text, URL, and styling that can be used with concatenateText() to build more complex text elements or appended directly to the HTML builder.
textThe text to be displayed for the hyperlink.
urlThe URL for this hyperlink. This can be a relative link, e.g., #page={page_guid} can be used to link to another page within the document.
new_tabWhether the URL should be opened in a new tab or not.
styleAn optional style dictionary (see setStyle()) to apply formatting to this hyperlink.
Returns:A HTML fragment that can be passed to concatenateText() or append().
Example:
var html = Q.htmlBuilder();
var link = html.createHyperlink('Click here', 'https://example.com', true, { color: 'blue', underline: true });
var text = html.createText('Visit our website: ');
var combined = html.concatenateText(text, link);
html.append(combined);

createText(content, style)

Creates a text fragment with the specified content and styling that can be used with concatenateText() to build more complex text elements.
contentPlain text content for the text fragment. HTML tags not supported.
styleAn optional style dictionary (see setStyle()) to apply formatting to this text fragment.
Returns:A HTML fragment that can be passed to concatenateText().
Example:
var html = Q.htmlBuilder();
var bold_text = html.createText('Important:', { bold: true });
var normal_text = html.createText(' This is regular text');
var red_text = html.createText(' This is red text', { color: 'red' });
var combined = html.concatenateText(bold_text, normal_text, red_text);
html.append(combined);

endBullettedList()

Ends a bulleted list that was started with startBullettedList(). You must call this method to properly close the list after adding all items.
Example:
var html = Q.htmlBuilder();
html.startBullettedList();
html.appendBullettedItem('Item 1');
html.appendBullettedItem('Item 2');
html.endBullettedList();

equals(obj)

Whether two objects are the same.
objThe object to compare against.
Returns:true or false
Example:
data_file.getQuestionByName('Q2').equals(data_file.questions()[0])

htmlFragment

A read-only property containing the HTML fragment string, which is used as input when setting the content of text items (see QScript Text).

setStyle(style)

Set the style for all subsequent appended content.
style

A dictionary of formatting properties and their values:

font: string, name of a font. The font must be installed on your system to appear in exports (print, PDF, PowerPoint, etc.). Only the following fonts are safe to use if this text item is to appear on a web dashboard: Andale Mono, Arial, Arial Black, Century Gothic, Comic Sans MS, Courier New, Georgia, Impact, Times New Roman, Trebuchet MS, Verdana.

size: number, font size in points.

color: See JavaScript Color Table.

bold: true or false. Whether text should be bold.

italic: true or false. Whether text should be italicized.

underline: true or false. Whether text should be underlined.

Example:
var html = Q.htmlBuilder();
html.setStyle({ font: 'Times New Roman', size: 10, color: 'blue' });
html.appendParagraph('Small blue text.');
html.appendParagraph('More blue text.');
// leaving color out will make it reset to default (black)
html.setStyle({ font: 'Arial', size: 14, bold: true });
html.appendParagraph('Larger black bold text.');

startBullettedList(style)

Starts a bulleted list that can have items added individually. Use this method when you want to build a bulleted list item by item, rather than providing all items at once with appendBulletted().
styleAn optional style dictionary (see setStyle()) to override formatting for this list.
Example:
var html = Q.htmlBuilder();
html.startBullettedList({ size: 12 });
html.appendBullettedItem('First item');
html.appendBullettedItem('Second item', { color: 'red' });
html.endBullettedList();

type

Returns "HtmlBuilder".

See also