sheet-to-doc

Sheet-to-Doc Advanced Features: Usage Tips for Loop Placeholders

In Sheet-to-Doc, loop placeholders are a powerful advanced feature that allows you to process repeated data in Excel and generate complex document structures, such as tables, lists, nested content, etc. Today, I will delve into the usage techniques of loop placeholders to help you master this feature and create more complex and professional automated documents.

What are Loop Placeholders?

Loop placeholders are used to define a repeated structure in Word templates, and the Sheet-to-Doc tool will automatically generate multiple instances based on repeated items in Excel data. Loop placeholders are particularly suitable for processing data with parent-child relationships, such as orders and order details, products and product features, students and grades, etc.

Two Types of Loop Placeholders

Sheet-to-Doc supports two types of loop placeholders, which have different syntax and usage scenarios.

1. Loop Placeholder 1: Fixed Syntax, Only Supports Generation Mode 2

Syntax

1
{#data}...{/data}

Usage Instructions

  • Fixed syntax, cannot customize name
  • Only takes effect in generation mode 2 (single document)
  • Used to generate all data into one document
  • No special processing of Excel data required

2. Loop Placeholder 2: General Version, Supports Generation Modes 1 and 2

Syntax

1
{#loop name}...{/loop name}

Usage Instructions

  • Can customize loop name (cannot be data)
  • Supports generation modes 1 and 2
  • Requires special processing of Excel data (adding prefix)
  • Suitable for processing complex data structures

Usage Scenarios of Loop Placeholders

Scenario 1: Generate Product List (Using Loop Placeholder 1)

When you need to generate a product list from Excel data into one document, you can use Loop Placeholder 1.

Excel Data

Product ID Product Name Price Stock
P001 Product A 100 50
P002 Product B 200 30
P003 Product C 150 40

Word Template (Generation Mode 2)

1
2
3
4
5
Product Catalog

{#data}
- Product ID: {Product ID}, Product Name: {Product Name}, Price: {Price} Yuan, Stock: {Stock} Pieces
{/data}

Generated Document

1
2
3
4
5
Product Catalog

- Product ID: P001, Product Name: Product A, Price: 100 Yuan, Stock: 50 Pieces
- Product ID: P002, Product Name: Product B, Price: 200 Yuan, Stock: 30 Pieces
- Product ID: P003, Product Name: Product C, Price: 150 Yuan, Stock: 40 Pieces

Scenario 1.1: Generate Product List (Using Loop Placeholder 2)

When you need to use a custom loop name, you can use Loop Placeholder 2.

Excel Data (needs prefix)

product.Product ID product.Product Name product.Price product.Stock
P001 Product A 100 50
P002 Product B 200 30
P003 Product C 150 40

Word Template (Generation Mode 1)

1
2
3
4
5
Product Catalog

{#product}
- Product ID: {Product ID}, Product Name: {Product Name}, Price: {Price} Yuan, Stock: {Stock} Pieces
{/product}

Word Template (Generation Mode 2)

1
2
3
4
5
6
7
Product Catalog

{#data}
{#product}
- Product ID: {Product ID}, Product Name: {Product Name}, Price: {Price} Yuan, Stock: {Stock} Pieces
{/product}
{/data}

Scenario 2: Generate Tables (Using Loop Placeholder 1)

Loop placeholders are very suitable for generating tables. You can use loop placeholders in tables to generate multiple rows of data.

Excel Data

Name Department Position Salary
Zhang San Technical Department Engineer 8000
Li Si Marketing Department Manager 12000
Wang Wu Finance Department Accountant 9000

Word Template (Generation Mode 2)

1
2
3
4
5
6
7
Employee Information Table

| Name | Department | Position | Salary |
|------|------|------|------|
{#data}
| {Name} | {Department} | {Position} | {Salary} Yuan |
{/data}

Generated Document

1
2
3
4
5
6
7
Employee Information Table

| Name | Department | Position | Salary |
|------|------|------|------|
| Zhang San | Technical Department | Engineer | 8000 Yuan |
| Li Si | Marketing Department | Manager | 12000 Yuan |
| Wang Wu | Finance Department | Accountant | 9000 Yuan |

Scenario 3: Generate Nested Content

When Excel data has a nested structure, you can use nested loop placeholders to generate complex documents.

Excel Data

Order Number Customer Name Product Name Quantity Unit Price
OD001 Customer A Product A 2 100
OD001 Customer A Product B 1 200
OD002 Customer B Product C 3 150

Word Template (Using Loop Placeholder 1)

1
2
3
4
5
6
7
8
9
Order Details

{#data}
Order Number: {Order Number}
Customer Name: {Customer Name}

Product Details:
- Product Name: {Product Name}, Quantity: {Quantity}, Unit Price: {Unit Price} Yuan
{/data}

Generated Document

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Order Details

Order Number: OD001
Customer Name: Customer A

Product Details:
- Product Name: Product A, Quantity: 2, Unit Price: 100 Yuan

Order Number: OD001
Customer Name: Customer A

Product Details:
- Product Name: Product B, Quantity: 1, Unit Price: 200 Yuan

Order Number: OD002
Customer Name: Customer B

Product Details:
- Product Name: Product C, Quantity: 3, Unit Price: 150 Yuan

Advanced Techniques for Loop Placeholders

1. Use Conditional Placeholders within Loops

You can use conditional placeholders within loop placeholders to display different content based on conditions.

1
2
3
{#product_list}
- Product Name: {Product Name}, Quantity: {Quantity}, Unit Price: {Unit Price} Yuan
{/product_list}

2. Use Conditional Placeholders within Loops

You can use conditional placeholders within loop placeholders to display different content based on data conditions.

1
2
3
4
5
{#data}
- Product Name: {Product Name}, Stock: {Stock} Pieces
  {#Stock <= 10}[Stock Insufficient]{/}
  {#Stock > 10}[Stock Sufficient]{/}
{/data}

3. Use Image Placeholders within Loops

You can use image placeholders within loop placeholders to dynamically insert images based on data.

1
2
3
4
5
{#data}
Product Name: {Product Name}
Product Image:
{@Product Image | _inline_image}
{/data}

Best Practices for Using Loop Placeholders

1. Reasonably Organize Excel Data

Ensure that Excel data has a clear structure, making it easy for loop placeholders to process. For nested data, it is recommended to use the same primary key (such as order number) to associate data at different levels.

2. Use Clear Loop Names

Choose concise and clear loop names for easy understanding and maintenance.

3. Test Loop Structures

Before generating a large number of documents, test the loop structure with a small amount of data to ensure that loop placeholders can correctly process the data.

4. Avoid Excessive Nesting

Although loop placeholders can be used nested, excessive nesting can make templates complex and difficult to maintain. It is recommended to nest at most 2-3 layers of loops.

5. Combine with Other Placeholders

Flexibly combine loop placeholders, data placeholders, conditional placeholders, and image placeholders to create more powerful document templates.

6. Use Data Comparison Function

Before generating documents, use Sheet-to-Doc’s data comparison function to check whether loop placeholders are correct, avoiding the generation of incorrect documents.

Common Problems and Solutions for Loop Placeholders

Problem 1: Loop Content Not Repeating Correctly

Reason: The name of the loop placeholder does not match the column name in Excel data, or the Excel data structure is incorrect.

Solution:

  • Check whether the name of the loop placeholder is consistent with the column name in Excel data
  • Ensure that Excel data structure is correct with clear parent-child relationships
  • Use data comparison function to check whether placeholders are correct

Problem 2: Nested Loops Not Generating Correctly

Reason: The structure of nested loops is incorrect, or the association relationship in Excel data is not clear.

Solution:

  • Check whether the structure of nested loops is correct, ensuring that each loop has corresponding start and end markers
  • Ensure that the association relationship in Excel data is clear, using the same primary key to associate data at different levels
  • Simplify nested structures and reduce nesting levels

Summary

Loop placeholders are a powerful feature of Sheet-to-Doc that allows you to process complex Excel data structures and generate various types of documents. By mastering the usage techniques of loop placeholders, you can create more complex and professional document templates, realizing more efficient automated document generation.

In the following series of articles, we will delve into Sheet-to-Doc’s image processing functions, including how to insert dynamic images in Word, usage methods and best practices of image placeholders, etc. Stay tuned!

微信二维码
Share