Reporting

SkyCiv Quick Design has an input library called ReportHelpers designed to help you format and write reports easily.

Basic Reporting

Blocks

Blocks are the lowest level of reporting and can be used to customize your reporting however you need it. We have a number of wrapper functions (shown in later functions) but this is the most direct way you can report. The variable REPORT is a global veriable that is accessible within your module.

REPORT.block.new('K-Factor Calculations', 4);

REPORT.block.addCalculation("AISC 360-10"); //will print on the left column

REPORT.block.addCalculation('[math]K = \\frac{180° \\cdot BA}{\\pi \\cdot \\theta \\cdot T} - \\frac{R_i}{T}[math]', 'K-Factor Formula');

REPORT.block.addCalculation('[math]\\text{Where:}\\ \\theta = \\text{Bend Angle, } T = \\text{Material Thickness, } BA = \\text{Bend Allowance, } R_i = \\text{Inner Radius}[math]');

REPORT.block.addCalculation('[math]\\text{Given values:}\\ T = ' + T + '\\text{ mm, } R_i = ' + Ri + '\\text{ mm, } \\theta = ' + theta + '\\text{ degrees, } BA = ' + BA + '\\text{ mm}[math]');

REPORT.block.addCalculation('[math]K = \\frac{180° \\cdot ' + BA + '}{\\pi \\cdot ' + theta + ' \\cdot ' + T + '} - \\frac{' + Ri + '}{' + T + '} = ' + K.toFixed(3) + '[math]', 'Calculated K-Factor');

REPORT.block.addResult('K = ' + K.toFixed(3));

REPORT.block.finish();

Text and Formatting Functions

ReportHelpers.heading()

This will print a heading at the top of a new block.

let font_size = 3;

ReportHelpers.heading("My Heading", font_size, "reference (optional)");

ReportHelpers.print()

This will print a clean formatted text in the left column of the report. Bold and italic options are available like markdown.

ReportHelpers.print("", "My text to print", "");

ReportHelpers.print("", "This is **BOLD** text", "");

ReportHelpers.print("", "This is *italic* text", "");

ReportHelpers.print("", "[math] a^2 + b^2 = c [math]", "");

ReportHelpers.subBreak()

Add a sub break between sections. This is just to provide separation between different sections in the same block.

ReportHelpers.subBreak();

ReportHelpers.lineResult()

This will create a nice easy and lightweight reporting option. Rather than showing full equations, you might just want to print intermediate results:

Note: You will need to open a REPORT block for this to be visible:

REPORT.block.new()

ReportHelpers.lineResult("Max Shear force in Member", "V_{y}", 22.43 + " kN")

ReportHelpers.lineResult("Displacement Max", "\\gamma_y", max_def + " mm")

ReportHelpers.lineResult("Design Load", "\\omega_x", 77.43 + " kNm")

ReportHelpers.lineResult("Section Capacity", "\\gamma_{y2}", 123.43 + " kNm")

ReportHelpers.lineResult("Remaining Capacity in Section", "\\gamma_{y3}", 46 + " kNm")

ReportHelpers.lineResult("Design Load", "\\omega_x", 77.43 + " kNm")

ReportHelpers.lineResult("Section Capacity", "\\gamma_{y2}", 123.43 + " kNm")

ReportHelpers.lineResult("Remaining Capacity in Section", "\\gamma_{y3}", 46 + " kNm")

REPORT.block.finish()

ReportHelpers.messageBox()

Creates a nice looking message box for displaying error messages or warnings to the user.

ReportHelpers.messageBox("Message Body", "Message Title");

ReportHelpers.messageBox("Some warning", "Warning", "warning"); // With style option

ReportHelpers.messageBox("Some warning", "Warning", "default", "Some Reference", "Some Result"); // With reference and result.

Options

Parameter	Description
Message Body	The main content or message to display in the message box.
Message Title	The title of the message box.
Style (optional)	The style of the message box, such as "warning" for a warning message.
Reference (optional)	Additional information or reference related to the message, displayed in the message box.
Result (optional)	Information or result related to the message, also displayed in the message box along with the reference, if provided.

ReportHelpers.customFormat()

Shortcut to format output in certain ways

ReportHelpers.printStatus("1111.98", "price_euro); => "1.111,98"

ReportHelpers.printStatus("1111.01", "euro); => "1.111,00"

ReportHelpers.list()

Puts a list into the report. The options parameter and all its supported options are optional.

let my_list = ["mince", "onions", "garlic", "tomatoes"];

let my_list_opts = {

"heading": "My Shopping List",

"heading_size": 2,

"reference": "Something",

"list_type": "ordered"

}

ReportHelpers.list(my_list, my_list_opts);

Options

Option	Description	Type
heading	Specifies the heading for the shopping list	String
heading_size	Sets the size of the heading (1-5)	Number (1-5)
reference	Provides a reference or additional information	String
list_type	Specifies the type of list (ordered/unordered)	"ordered" or "unordered"

Tables, Graphs and Images

ReportHelpers.drawGraph()

Will draw a nice BMD/SFD diagram with a simple array:

ReportHelpers.drawGraph({

loads_array: [0.3, 0.3, 0.3, [0.3, -0.3], -0.3, -0.3],

member_length: 12.23,

loads_unit: "kN",

result_label_: "Shear Force Diagram",

result_label_x: "Column Length", // Optional

graph_title: "SFD",

color: "red",

flip_axis: false // Optional to reverse the axis

});

---

ReportHelpers.image()

Will print an image in the report

ReportHelpers.image({

new_block: true, //if you already have a block open, set this to false

src: "https://skyciv.com/wp-content/uploads/2023/03/reference-1-qf.png"

});

tip

Images can be hosted/served directly from the calc pack by including an images folder. Reference all images included in the image directory as /image_name.png.

---

ReportHelpers.quickTable()

Create and display data in a table format.

// QUICK TABLES

let table_data = [

["Heading 1", "Heading 2", "Heading 3"],

["Some Result", "1223", "kN"],

["Some Other Result", "0.234", "MPa"],

["<h3>Add some Subheading with just one input</h3>"],

["Some Result", "1223", "kN"],

["Some Other Result", "0.234", "MPa"],

["Some Other Result", "0.234", "MPa"],

];

let options = {

heading: "Simplified Table Method",

widths: ["50%", "25%", "25%"],

text_aligns: ["left", "right", "center"], //or just "center"

reference: "Clause 1.2.3 AISC"

};

ReportHelpers.quickTable(table_data, options);

---

Advanced Options

• Cell Coloring options.cell_backgrounds
  • Takes an array of arrays in the format [row_idx, column_idx, hex_code]

Maths, Formulas and Status

ReportHelpers.round()

Will round any number to 2 decimal places, or if you provide a second argument it will round to that figure. It will work with strings and handle NaNs without crashing.

This will return a number back, that way you can continue to use this as a number (not a string)

ReportHelpers.round(0.432731); // 0.43

ReportHelpers.round(0.432731, 4); // 0.4327

ReportHelpers.round("1.736242"); // 1.74

ReportHelpers.round(6, -1); // 10

ReportHelpers.round(64, -1); // 60

ReportHelpers.round(65, -1); // 70

ReportHelpers.round(650, -2); // 600

---

ReportHelpers.convert()

Converts units

ReportHelpers.convert(10, "in", "mm"); //254

ReportHelpers.convert(10, "kN", "kip"); //2.2480894244319

ReportHelpers.convert(2352, "mm", "m"); //2.352

tip

For a list of supported units see Quick Design Units

---

ReportHelpers.formula()

Will automatically evaluate and print an equation to represent the result. Note: .formula() does not support {} characters. For this you will need to use lower level REPORT functions. Please do not include mathjax [math][math] tags as this will stop the formula from evaluating correctly.

var moi = ReportHelpers.formula({

"formula": "I_y = b * Math.pow(h, 3) / 12",

"variables": {

"b": b,

"h": {

value: h,

unit: "mm", // OPTIONAL: To add unit systems to formula

dec_places: 4 // OPTIONAL: To locally round a variables separate to the global formula rounding

},

},

"units": "mm^4",

"dec_places": 2,

"intermediate_result": true,

"reference": "Clause 1.2.3 AISC",

"print_result_as_utility": true,

"heading": "Formula Heading" // OPTIONAL

}); // will return the value of moi

Max and Min Functions

You can use 'Math.min' and 'Math.max' functions with ReportHelpers.formula(). Normal MAthJax formatting is not available with this option. An example is below:

ReportHelpers.formula({

"formula": "max_value = Math.max(A, B)",

"variables": {

"A": 1,

"B": 2

},

"dec_places": 2,

"compact": true,

"intermediate_result": true,

"print_result_as_utility": true

});

Parameters

Field	Description
formula	The formula to use for the equation in MathJax.
variables	The set of variables with their values to sub into the equation. Values can be a number or can also be a object with keys { value: value, unit: unit }.
units	Unit for final results.
dec_places	Number of decimal places to round final results too.
compact	OPTIONAL: Force all of the equation and result onto one line.
intermediate_result	Include a intermediate step where values are subbed into the original equation.
new_line_intermediate	OPTIONAL: Put intermediate step on a new line.
reference	Prints the reference of the equation in the left column.
print_result_as_utility	OPTIONAL: Prints the result as a utility ratio on the right column of report.
exclude_result	OPTIONAL: Don't print the result line.
expected_result	OPTIONAL: Check that the formula evaluates to an expected result, throws an error if the results don't match.

Output

tip

You can include Greek Alphabet Characters in the formula by copying the character from this link.. This will work better thing including them with MathJax.

danger

The ^ symbol in Javascript works as a XOR operator and will break your equations. Please insure you use Math.pow() instead.

ReportHelpers.printStatus()

This will automatically format a clean color-based result on the right side of the table. It will automatically read a value, and if it is > 1 it will show a red FAIL. If it is < 1, it will show a green PASS:

REPORT.block.new();

ReportHelpers.printStatus(0.128, true);

REPORT.block.finish();

//OR - if you want to create a new block

ReportHelpers.printStatus(0.888, false);

ReportHelpers.getStatusBlock()

This will automatically return the html of the clean color-based result from ReportHelpers.printStatus()

let status_block_html = ReportHelpers.getStatusBlock(0.128);

ReportHelpers.printCustomStatus()

This will automatically format a clean color-based result on the right side of the table. If you pass in pass, fail or warn then colors will be automatically assigned otherwise you can specify custom colors with the last parameter

// Parameters

// ReportHelpers.printCustomStatus(text, use_existing_block, background_color)

REPORT.block.new();

ReportHelpers.printStatus('Pass', true, '#2185d0'); // Blue Pass Utility Status

REPORT.block.finish();

//OR - if you want to create a new block

ReportHelpers.printStatus('Pass', false); // Green Pass Utility Status

ReportHelpers.getStatusBlock()

This will automatically return the html of the clean color-based result from ReportHelpers.getCustomStatusBlock()

// Parameters

// ReportHelpers.getCustomStatusBlock(text, background_color)

let status_block_html = ReportHelpers.getCustomStatusBlock('Pass''#2185d0'); // Blue Pass Utility Status

let status_block_html = ReportHelpers.getCustomStatusBlock('Pass'); // Green Pass Utility Status

Tips

tip

MathJax in the QD Framework replaces / with //. This will differ from equations you might find in the MathJax Documentation

tip

To add a space in pure MathJax, such as a space in the symbol key used in config.js you can use \\ ;

Full Width Blocks

To include a full width block without a REFERENCES or RESULTS column you can use the ReportHelpers.customFullBlock(obj); function. This function takes the following options:

Parameter	Description
title	Title that is automatically added to the full width block.
content	The HTML content to add to the full width block. This must be all the content to be included you cannot add more content later.
font_size	Font size of the heading in the block (default 3 i.e <h3> tags).
margin_left	Margin left of the title in pixels or %. Default 10%.

As this block takes html you can use some lower level functions to return the HTML of some of the above functions. These include:

High Level Function	Low Level Function
ReportHelpers.quickTable()	ReportHelpers.quickTableHTML()
ReportHelpers.image()	ReportHelpers.imageHTML()
ReportHelpers.lineResult()	ReportHelpers.lineResultHTML()

Summary Reporting

The summary report is a simple one page report that list the key input, outputs, intermediate results and relevant graphics.

Summary Report Methods

ReportHelpers.addKeyImage(key_image);

This method takes either a image url, base64 string or pure svg html. In the case of svg html it converts the image to base64 for the report. By default this is done on a 400 wide by 380 tall canvas, however for better scaling you can specify the rendering width in the summary report settings.

ReportHelpers.addSecondaryKeyImage(key_image);

Adds a secondary image, so long as "key_image_own_line" is set to true;

ReportHelpers.addIntermediateResults(name, value);

Adds an intermediate result to the report.

Summary Report Settings

You can specify summary report settings by including the summary_report_settings object in the calculate.js output.

Example

"summary_report_settings": {

"key_image_own_line": true,

"key_image_width": key_image_width,

"key_image_height": key_image_height

}

Supported Settings

Setting	Default	Description
key_image_own_line	false	Add the key image on its own line.
key_image_width	400	The canvas width (px) to render svg key images on.
key_image_height	380	The canvas height (px) to render svg key images on.
secondary_key_image_width	400	The canvas width (px) to render svg key images on.
secondary_key_image_height	380	The canvas height (px) to render svg key images on.
intermediate_results_columns	2	The number of columns to show in intermediate results.