XML Usage

Overview

The XmlHandler within the Cookiecutter configuration enables targeted and automated replacements within XML files, facilitating an organized and scalable way to handle placeholder-based mappings. This configuration is particularly useful for managing variables in XML files like pom.xml and other custom XML files in your project.

Configuration Example

In this example, we configure replacements for XML files, specifying the paths and placeholder details. Here’s a breakdown of the configuration structure and its elements:

YAML Configuration

steps:
  - kind: XmlHandler
    apiVersion: v1
    spec:
      - files:
          - pom.xml
        placeholders:
          - match: /project/groupId
            replace: cookiecutter.param.groupId
          - match: /project/artifactId
            replace: Cookiecutter.test.replace.map.artifactId
          - match: /project/dependencies/dependency/scope[text()='test']
            replace: cookiecutter.replace.map.scopes
      - files:
          - xmls/generic_1.xml
        placeholders:
          - match: /note/heading
            replace: New Reminder
      - files:
          - xmls/complex/generic_2.xml
        placeholders:
          - match: /bookstore/book/author[text()='Kurt Cagle']
            replace: cookiecutter.kurtCagle
          - match: /bookstore/book/year[text()='2005']
            replace: cookiecutter.NewYear

Explanation of Key Sections

1. kind: XmlHandler

This defines the handler type as XmlHandler, specifying that the operations pertain to XML files.

2. apiVersion: v1

Indicates the version of the API for handling XML configurations. Ensure compatibility by matching the correct API version.

3. spec Section

The spec section provides detailed instructions for each XML file, including which files to target and how placeholders are mapped within them.

Each spec item contains:

• files: Specifies the XML files in which replacements will occur. The paths are relative to the root of the project.
• placeholders: Defines the placeholder operations within each file, where:
  • match: Represents the XPath expression targeting the element or text to be replaced.
  • replace: Specifies the placeholder value that will substitute the matched content. This value can reference an item in the cookiecutter configuration, providing flexibility to customize the output.

Detailing the Yaml example

pom.xml Replacements

In the pom.xml file, the placeholders automate configuration updates:

• /project/groupId: Replaces the project’s groupId with the value specified in cookiecutter.param.groupId.
• /project/artifactId: Substitutes the artifactId with Cookiecutter.test.replace.map.artifactId.
• /project/dependencies/dependency/scope[text()='test']: Replaces the test scope with cookiecutter.replace.map.scopes.

Custom XML Files

1. xmls/generic_1.xml:

   • /note/heading: Updates the heading element within a <note> tag to "New Reminder".

2. xmls/complex/generic_2.xml:

   • /bookstore/book/author[text()='Kurt Cagle']: Replaces occurrences of "Kurt Cagle" in the author tag with the value from cookiecutter.kurtCagle.
   • /bookstore/book/year[text()='2005']: Changes the year from "2005" to the new value in cookiecutter.NewYear.

Summary

This XML configuration enables flexible replacement for various fields within multiple XML files, streamlining project customization through centrally managed placeholders. This setup allows teams to efficiently handle repetitive configurations across different XML files.