Documentation – How to Use Smart Marker Variables and Expressions

Net: Smartly Importing Master and Details Data into Excel With Smart Markers

Mon, 01 Jan 0001 00:00:00 +0000

Possible Usage Scenarios

Sometimes, you want to generate dynamic Excel reports; it includes a comprehensive main dashboard and multiple fine‑grained detailed worksheets. Among them, a single main table presents an overview, which may showcase various product variants, and each corresponding detailed worksheet provides specific and in‑depth data for a single variant. Aspose.Cells can perfectly meet your needs through master and details with smart markers.

Smart Marker Parameters for Master and Details

To import master and details data into Excel, you need to use the following smart marker parameters:

Parameter	Description	Acceptable Values (Syntax)	Restrictions	Optionality	Default Behavior	Excel Constraints
`DetailSheet`	Specify the name of the detail worksheet stored in the template file.	String value	Value must be null or the name of a worksheet. If null, this is a detail sheet. It should be a simple string value. Variable is not supported.	If omitted, it is not a master or detail sheet.	Normal worksheet, not a master or detail sheet.
`DetailTable`	Specify the table name of the detail worksheet in the template file.	String value		If omitted, the smart marker in the detail sheet should be similar to the master sheet; otherwise we cannot find the data source.	If omitted, the smart marker in the detail sheet should be similar to the master sheet; otherwise we cannot find the data source.
`DetailSheetNewName`	Specify the name of the newly created detail worksheet.	Excel formula‑like expression	It should be a valid Excel formula if we replace the variable ({a.bc}) with a simple value.	If omitted, new sheets will be Sheet1, Sheet2…	If omitted, new sheets will be Sheet1, Sheet2…	The name must be a valid worksheet name.
`DetailLink`	Indicate whether to add hyperlinks to the location of the imported data.			If omitted, hyperlinks are not added to the location of the imported data.	If omitted, hyperlinks are not added to the location of the imported data.

How to Use Master and Details When Master and Details Are in One Worksheet

Sometimes, you need to import master and details data to Excel in SmartMarkers. Aspose.Cells makes it possible to use master and details parameters in SmartMarkers. Please check the template file, the JSON file, and the screenshots of the output Excel file generated with the following code.

The first worksheet of the template.xlsx.

The first worksheet of the output Excel file.

The second worksheet of the output Excel file.

JSON data as follows:

{
	"node": {
		"Styles1": [
			{
				"StyleID": "1style001",
				"StyleName": "StyleName1",
				"Quantity": 6,
				"UnitPrice": 18.45,
				"MaterialType": "Cotton"
			}
		],
		"Styles2": [
			{
				"StyleID": "2style001",
				"StyleName": "Cotton StyleName2",
				"Quantity": 6,
				"UnitPrice": 18.45,
				"MaterialType": "Cotton"
			},
			{
				"StyleID": "2style002",
				"StyleName": "Denim StyleName2",
				"Quantity": 8,
				"UnitPrice": 58.8,
				"MaterialType": "Denim"
			}
		]
	}
}

The example that follows shows how this works.

How to Use Master and Details When Master and Details Are in Different Worksheets

The first master worksheet of the template.xlsx.

The second master worksheet of the template.xlsx.

The detail worksheet of the template.xlsx.

The first master worksheet of the output Excel file.

The second master worksheet of the output Excel file.

The detail worksheet of the first master worksheet in the output Excel file.

The first detail worksheet of the second master worksheet in the output Excel file.

The second detail worksheet of the second master worksheet in the output Excel file.

JSON data as follows:

{
	"node": {
		"Styles1": [
			{
				"StyleID": "1style001",
				"StyleName": "StyleName1",
				"Quantity": 6,
				"UnitPrice": 18.45,
				"MaterialType": "Cotton"
			}
		],
		"Styles2": [
			{
				"StyleID": "2style001",
				"StyleName": "Cotton StyleName2",
				"Quantity": 6,
				"UnitPrice": 18.45,
				"MaterialType": "Cotton"
			},
			{
				"StyleID": "2style002",
				"StyleName": "Denim StyleName2",
				"Quantity": 8,
				"UnitPrice": 58.8,
				"MaterialType": "Denim"
			}
		]
	}
}

The example that follows shows how this works.

Net: How to Use If Parameter and Variables in SmartMarkers

Mon, 01 Jan 0001 00:00:00 +0000

How to Use SmartMarker IF Variable Conditions to Filter Data

1. Feature Overview

SmartMarker supports dynamic data filtering through IF conditions to control whether row data is rendered in reports. This feature fully supports two standard IF condition methods: direct field expression writing and boolean variable writing defined in the variable worksheet. Users can reference boolean expression variables preset in the variable worksheet directly in IF judgments.

Users can either write filter expressions directly in cells or encapsulate complex range judgments, status checks, and multi-condition combination logic into global variables for reuse in templates, effectively organizing scattered conditional logic and simplifying the maintenance of complex report templates.

2. Feature Benefits

IF variable condition filtering optimizes the data filtering capability of SmartMarker, bringing the following core advantages:

Unified conditional logic management: All data filtering rules, boolean judgments and range checks are centrally configured in the variable worksheet, instead of being scattered in display cells.
Global reuse of filter rules: Defined boolean condition variables can be referenced repeatedly across the entire report template without rewriting complex expressions.
Lower maintenance costs: When business filter rules change, only the variable worksheet configuration needs to be updated, without modifying template markers in batches.
Support for complex combined conditions: Custom multi-field and multi-logic composite judgments are supported, and variables can be nested in AND / OR logical functions.
Cleaner template structure: Display cells only reference variable names without lengthy judgment expressions, making templates neat and readable.

3. Usage Guide

General workflow: Define boolean condition variables in the variable worksheet → Reference variables through IF conditions in template cells → Enable the variable worksheet and render with code.

3.1 Variable Worksheet Configuration Rules

In the independent variables worksheet, define all data filtering logic asexpression-type variables, supporting single-condition judgment and complex multi-field combined judgment.

Scope	Name	Variable Name	Variable Value	Type
Worksheet	Template	booksUpto100Check	{node.books.price} <= 100	Expression
Worksheet	Template	booksAbove200Check	{node.books.price} > 200	Expression
Worksheet	Template	bookAvailable	{node.books.isAvailable} = true	Expression

3.2 Template Marker Syntax

SmartMarker IF conditions support multiple standard syntaxes. You can use direct field expressions or reference pre-defined boolean variables and composite logic variables in the variable worksheet to adapt to different template development scenarios.

1. Field Expression Condition

Marker Syntax: \&=node\.books\.price\(if:\{node\.books\.price\} \<= 100\)

Marker Syntax: \&=bookPrice\(if:\{bookPrice\} \<= 100\)

Function: Write complete field judgment expressions directly in IF parameters to implement data filtering.

2. Boolean Variable Condition

Marker Syntax: \&=node\.books\.price\(if:\{booksUpto100Check\}\)

Function: Reference pre-defined boolean expression variables in the variable worksheet to reuse conditional logic and simplify template markers.

3. Direct Boolean Variable Output

Marker Syntax: \&=\{booksUpto100\}

Marker Syntax: \&=booksUpto100

Function: Directly render boolean variable results to display conditional judgment values.

4. Multi-Variable Combined Condition

Marker Syntax: \&=node\.books\.price\(if:AND\(\{bookAvailable\},\{booksAbove200Check\}\)\)

Function: Combine multiple boolean variables with AND/OR logical functions to implement complex multi-condition data filtering.

3.3 Core Implementation Code

Specify the variable worksheet name to enable variable parsing, allowing SmartMarker to recognize custom boolean variables in IF conditions correctly.

4. Important Notes

Exact Worksheet Name Matching: The name assigned to VariablesWorksheetName must strictly match the name of the custom variable worksheet. Otherwise, the engine cannot resolve custom boolean variables in IF conditions.
Valid Boolean Expression Definition: Variables used in IF conditions must return standard boolean results (true/false). Ensure the configured expression logic is complete and correct to avoid empty or incorrect filtering results.
Standard Logical Function Usage: When combining multiple variables with AND\(\) or OR\(\), all parameters inside the function must be valid boolean variables or boolean expressions to ensure normal parsing.
Correct Variable Reference Syntax: When referencing variables in IF parameters, use the standard format if:\{variableName\}. Missing braces or incorrect variable names will lead to parsing failure.
Unified Data Source Prefix: The field prefix defined in the variable expression must be consistent with the root data source name bound by SetDataSource, preventing field resolution errors caused by inconsistent data source paths.