fixing gh-pages

site/content/posts/xslt-parameters-and-multiple-inputs.md

@@ -0,0 +1,32 @@
+---
+title: "Designing XSLT transforms with parameters and multiple inputs"
+description: "How to structure stylesheets that consume several XML documents and stay maintainable."
+date: 2025-03-02T00:00:00Z
+---
+
+Many real-world transformations do not run on a single XML document. You often merge a primary payload with reference data, catalog lookups, or environment configuration. Done well, this results in a clean, predictable transform. Done poorly, it becomes a maze of `document()` calls and hidden dependencies. The difference is in how you model inputs and parameters from the start. As an integration engineer, I treat input selection and parameter design as first-class API design for the stylesheet.
+
+Start by naming every input. Instead of embedding `document('config.xml')` in multiple templates, load each external document once near the top of the stylesheet and bind it to a global variable. This makes dependencies explicit and keeps the rest of the code focused on mapping. It also helps with testing, because you can override the URI with a parameter. A clean pattern is to define `xsl:param` values for input URIs and then bind them to `xsl:variable` values that hold the parsed documents.
+
+The same clarity applies to parameters. Keep parameters primitive and predictable, and avoid passing in node sets unless you truly need them. A parameter should be an external knob: region, language, a feature flag, or an output format. If you have a complex decision tree, consider using a lookup XML or JSON input and then query it inside the stylesheet. This approach keeps the invocation interface stable while still letting you evolve business rules.
+
+A simple skeleton might look like this:
+
+```xml
+<xsl:param name="catalog-uri"/>
+<xsl:param name="region" select="'us'"/>
+
+<xsl:variable name="catalog" select="document($catalog-uri)"/>
+```
+
+From there, templates can reference `$catalog` without worrying about IO or base URIs. You can also define a named template that accepts a parameter for reuse across multiple modes. This is useful when the same output block is needed for several sections of the document but the selection context differs.
+
+When combining multiple inputs, always anchor your lookups to a clear key. If you can, define `xsl:key` on the external document so lookups are efficient and readable. In XSLT 2.0 or 3.0, `xsl:for-each-group` and the `map` types can reduce boilerplate, but the core idea remains: make your joins explicit and deterministic. If you rely on default order or on undocumented assumptions about uniqueness, you will eventually get a hard-to-reproduce bug.
+
+Another important integration pattern is separating parsing from formatting. For example, you might normalize all values from the various inputs into a canonical intermediate structure and then render that structure into the final output. This makes testing easier and supports future outputs such as CSV, JSON, or a secondary XML format. Even in XSLT 1.0, you can emulate this by creating result tree fragments, then processing them in a second pass if needed.
+
+Multiple inputs also raise questions about fallbacks. Decide how you want to behave when optional data is missing. I prefer to centralize defaults in a few named templates or functions and avoid sprinkling `xsl:choose` blocks everywhere. This keeps the stylesheet readable and makes it obvious how to override the defaults later. Document your fallbacks in the code with short, clear names so a future maintainer does not have to rediscover the rules by reading the entire stylesheet.
+
+Finally, create a small set of inputs that represent common scenarios and run them regularly. For example, have a baseline case, a case with missing reference data, and a case with unexpected elements. These are the cases that reveal poor assumptions about inputs. A fast way to iterate on these scenarios is to run the transform with a tool that lets you swap inputs and parameters quickly.
+
+If you want to try these patterns with real inputs and multiple documents, the online editor at [https://xsltplayground.com](https://xsltplayground.com) is built for that workflow. It lets you load multiple XML documents and parameters, see how they interact, and keep your integration logic transparent as it grows.