Skip to main content
PDF4me APIIntegrationsKnowledge BaseExtensionsAPI TesterBlog

Lists in Templates - Bullets & Numbered

Lists are fundamental structures for organizing and presenting information in documents. PDF4me's template engine supports both bulleted and numbered list generation, enabling you to create well-structured, readable documents with dynamic content from your data sources.

Bullet Lists​

Generate bulleted lists by placing foreach loops within bullet-formatted paragraphs in your Word template.

Basic Bullet List Syntax​

Create a bulleted paragraph in Word, then add the foreach loop:

<<foreach [bullet in EmployeeNames]>><<[bullet.listFirstName]>> <<[bullet.listLastName]>> 
<</foreach>>

Key Steps:

  1. In Word, create a bullet point (use bullet formatting)
  2. Add the foreach loop and merge fields
  3. The loop will repeat the bullet point for each item

Example: Employee Name List​

Template Design:

Employee Directory:
• <<foreach [bullet in EmployeeNames]>><<[bullet.listFirstName]>> <<[bullet.listLastName]>> 
<</foreach>>

Data Source:

{
  "companyName": "PDF4me",  
  "EmployeeNames": [
    {
      "listFirstName": "Thomas",
      "listLastName": "Baskin"
    },
    {
      "listFirstName": "Jacob",
      "listLastName": "Gregory"
    },
    {
      "listFirstName": "John",
      "listLastName": "Doe"
    }
  ]
}

Generated Output:

Employee Directory:
• Thomas Baskin
• Jacob Gregory
• John Doe

Numbered Lists​

Generate numbered lists using the same foreach approach, but with numbered paragraph formatting in Word.

Numbered List Syntax​

Numbered List - Instead of bullets, if you apply the syntax in a numbered paragraph format in Word, the list will be generated as a numbered list with automatic numbering.

Example: Task List​

Template:

Project Tasks:
1. <<foreach [task in tasks]>><<[task.name]>> - <<[task.status]>>
<</foreach>>

Data:

{
  "tasks": [
    { "name": "Design mockups", "status": "Complete" },
    { "name": "Develop features", "status": "In Progress" },
    { "name": "Testing phase", "status": "Pending" }
  ]
}

Output:

Project Tasks:
1. Design mockups - Complete
2. Develop features - In Progress
3. Testing phase - Pending

Multi-Level Lists​

Create hierarchical list structures with parent-child relationships using nested foreach loops.

Two-Level Hierarchy Example​

Template Design:

<<foreach [manager in employees]>>Manager: <<[manager.listFirstName]>> <<[manager.listLastName]>>
    <<foreach [associate in manager.associates]>>Associate: <<[associate.name]>>
<</foreach>><</foreach>>

Important: The second-level list items should be indented in your Word template to create proper hierarchical formatting.

Example: Organizational Structure​

Data Structure:

{
  "companyName": "PDF4me",
  "employees": [
    {
      "listFirstName": "Christopher",
      "listLastName": "Nolan",
      "associates": [
        { "name": "Will Smith" },
        { "name": "Barry Allen" },
        { "name": "Oliver Queen" }
      ]
    },
    {
      "listFirstName": "Sarah",
      "listLastName": "Parker",
      "associates": []
    },
    {
      "listFirstName": "Justin",
      "listLastName": "Langer",
      "associates": [
        { "name": "Brad Pitt" },
        { "name": "John Smith" }
      ]
    }
  ]
}

Generated Output:

• Manager: Christopher Nolan
    ○ Associate: Will Smith
    ○ Associate: Barry Allen
    ○ Associate: Oliver Queen
• Manager: Sarah Parker
• Manager: Justin Langer
    ○ Associate: Brad Pitt
    ○ Associate: John Smith

Handling Empty Sub-Lists​

Use conditional checks to handle cases where sub-lists might be empty.

Conditional Sub-List​

Template:

<<foreach [manager in employees]>>Manager: <<[manager.listFirstName]>> <<[manager.listLastName]>>
    <<if [manager.associates.Any()]>>
    <<foreach [associate in manager.associates]>>Associate: <<[associate.name]>>
    <</foreach>>
    <<else>>
    No associates assigned
    <</if>>
<</foreach>>

Formatted List Items​

Apply formatting to list item content for enhanced presentation.

Example: Formatted Names and Dates​

Template:

• <<foreach [employee in employees]>><<[employee.name]:caps>> - Joined: <<[employee.joinDate]:"MMMM yyyy"]>>
<</foreach>>

Data:

{
  "employees": [
    { "name": "john smith", "joinDate": "2020/03/15" },
    { "name": "jane doe", "joinDate": "2021/07/22" }
  ]
}

Output:

• John Smith - Joined: March 2020
• Jane Doe - Joined: July 2021

Sorted Lists​

Generate lists in specific orders using enumeration methods.

Alphabetically Sorted List​

Template:

• <<foreach [person in people.OrderBy(p => p.lastName)]>><<[person.lastName]>>, <<[person.firstName]>>
<</foreach>>

Sorted by Multiple Properties​

Template:

• <<foreach [emp in employees.OrderBy(e => e.department).ThenBy(e => e.name)]>><<[emp.name]>> - <<[emp.department]>>
<</foreach>>

Filtered Lists​

Display only items that meet specific criteria.

Conditional Filtering​

Template:

Active Employees:
• <<foreach [emp in employees.Where(e => e.status == "Active")]>><<[emp.name]>>
<</foreach>>

Age-Based Filtering​

Template:

Senior Team Members:
• <<foreach [person in team.Where(p => p.age > 50)]>><<[person.name]>> (Age: <<[person.age]>>)
<</foreach>>

Mixed List Types​

Combine different list styles within the same document.

Example: Project Overview​

Template:

Project Phases (Numbered):
1. <<foreach [phase in phases]>><<[phase.name]>>
<</foreach>>

Team Members (Bulleted):
• <<foreach [member in team]>><<[member.name]>> - <<[member.role]>>
<</foreach>>

Complex Multi-Level Examples​

Three-Level Hierarchy​

Template:

<<foreach [dept in departments]>>Department: <<[dept.name]>>
    <<foreach [team in dept.teams]>>Team: <<[team.name]>>
        <<foreach [member in team.members]>><<[member.name]>> - <<[member.position]>>
        <</foreach>>
    <</foreach>>
<</foreach>>

This creates:

  • Level 1: Department (bullet style 1)
    • Level 2: Team (bullet style 2)
      • Level 3: Member (bullet style 3)

List Design in Word Template​

Setting Up List Formatting​

  1. Create list structure - Use Word's built-in list formatting tools
  2. Choose bullet style - Select appropriate bullet or numbering style
  3. Set indentation - Configure indent levels for multi-level lists
  4. Add merge fields - Insert foreach loops and merge field syntax
  5. Maintain formatting - Ensure list formatting is applied to template text

Indentation Levels​

For multi-level lists:

  • Level 1: No indentation or first level indent
  • Level 2: One tab or indent increase
  • Level 3: Two tabs or second level indent

Word automatically handles bullet/number styling based on indentation level.

Practical Applications​

Use Case 1: Meeting Agenda​

Template:

Meeting Agenda - <<[meetingDate]:"MMMM dd, yyyy">>

1. <<foreach [item in agendaItems]>><<[item.title]>> (<<[item.duration]>> min)
<</foreach>>

Attendees:
• <<foreach [attendee in attendees]>><<[attendee.name]>> - <<[attendee.department]>>
<</foreach>>

Use Case 2: Product Features​

Template:

<<[productName]>> Features:

• <<foreach [feature in features]>><<[feature.name]>> - <<[feature.description]>>
<</foreach>>

Technical Specifications:
1. <<foreach [spec in specifications]>><<[spec.parameter]>>: <<[spec.value]>>
<</foreach>>

Use Case 3: Invoice Items​

Template:

Order Items:
<<foreach [item in orderItems]>>
<<[$index + 1]>>. <<[item.name]>> - Quantity: <<[item.qty]>> - Price: $<<[item.price]>>
<</foreach>>

Total Items: <<[orderItems.Count()]>>
Total Amount: $<<[orderItems.Sum(i => i.qty * i.price)]>>

Best Practices​

List Design​

  1. Consistent formatting - Use the same list style for similar content types
  2. Appropriate depth - Limit nesting to 3-4 levels for readability
  3. Logical grouping - Group related items together
  4. Clear hierarchy - Use different bullet styles for different levels

Data Structure​

  1. Clean collections - Ensure collections contain valid, complete data
  2. Consistent properties - Use consistent property names across items
  3. Handle nulls - Check for empty collections with Any()
  4. Sort appropriately - Pre-sort data or use OrderBy in templates

Performance​

  1. Limit list size - Consider pagination for very long lists
  2. Filter efficiently - Apply filters at data source when possible
  3. Avoid complex nesting - Deep nesting can impact processing speed
List Formatting

Apply list formatting (bullets, numbers, indentation) directly in your Word template before adding foreach loops. The template engine preserves the formatting you set in Word.