From a54e623dc79d1ac3b9b38148e012735cedc8b3ba Mon Sep 17 00:00:00 2001
From: Darragh Bailey <daragh.bailey@gmail.com>
Date: Sat, 20 Feb 2016 18:11:58 +0000
Subject: [PATCH] Document template variable default values

Document the ability to define default values for template variables
within the template definition thus removing the need to always having
to set such values in job definitions.

Change-Id: If4d8bfd898066b8e6350ed22f0c97eb939ae4348
---
 doc/source/definition.rst                     | 20 +++++++++
 .../fixtures/template_default_variables.xml   | 44 +++++++++++++++++++
 .../fixtures/template_default_variables.yaml  | 25 +++++++++++
 3 files changed, 89 insertions(+)
 create mode 100644 tests/yamlparser/fixtures/template_default_variables.xml
 create mode 100644 tests/yamlparser/fixtures/template_default_variables.yaml

diff --git a/doc/source/definition.rst b/doc/source/definition.rst
index 51b190c71..ee5f16b0e 100644
--- a/doc/source/definition.rst
+++ b/doc/source/definition.rst
@@ -74,6 +74,26 @@ Sometimes it is useful to have the same job name format used even
 where the template contents may vary. `Ids` provide a mechanism to
 support such use cases.
 
+
+Default Values for Template Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To facilitate reuse of templates with many variables that can be
+substituted, but where in most cases the same or no value is needed,
+it is possible to specify defaults for the variables within the
+templates themselves.
+
+This can be used to provide common settings for particular templates.
+For example:
+
+.. literalinclude::
+    /../..tests/yamlparser/fixtures/template_default_variables.yaml
+   :language: yaml
+
+To use a default value for a variable used in the name would be
+uncommon unless it was in addition to another variable. However you
+can use `Ids`_ simplify such use cases.
+
 .. _project:
 
 Project
diff --git a/tests/yamlparser/fixtures/template_default_variables.xml b/tests/yamlparser/fixtures/template_default_variables.xml
new file mode 100644
index 000000000..52b3cf492
--- /dev/null
+++ b/tests/yamlparser/fixtures/template_default_variables.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <actions/>
+  <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
+  <keepDependencies>false</keepDependencies>
+  <disabled>true</disabled>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+  <concurrentBuild>false</concurrentBuild>
+  <canRoam>true</canRoam>
+  <properties/>
+  <scm class="hudson.scm.NullSCM"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>echo &quot;Job Name: template-variable-defaults-1-periodic&quot;
+echo &quot;Variable: Hello World&quot;
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>
+
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <actions/>
+  <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
+  <keepDependencies>false</keepDependencies>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+  <concurrentBuild>false</concurrentBuild>
+  <canRoam>true</canRoam>
+  <properties/>
+  <scm class="hudson.scm.NullSCM"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>echo &quot;Job Name: template-variable-defaults-2-periodic&quot;
+echo &quot;Variable: Goodbye World&quot;
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>
diff --git a/tests/yamlparser/fixtures/template_default_variables.yaml b/tests/yamlparser/fixtures/template_default_variables.yaml
new file mode 100644
index 000000000..5b0e2ffc4
--- /dev/null
+++ b/tests/yamlparser/fixtures/template_default_variables.yaml
@@ -0,0 +1,25 @@
+- project:
+    name: template_variable_defaults
+    jobs:
+        - 'template-variable-defaults-{num}':
+            num: 1
+            disabled_var: true
+        - 'template-variable-defaults-{num}':
+            test_var: Goodbye World
+            num: 2
+
+- job-template:
+    # template specific defaults
+    # empty value causes disabled_var to be ignored internally
+    disabled_var:
+    test_var: Hello World
+    type: periodic
+
+    # template settings
+    name: 'template-variable-defaults-{num}-{type}'
+    id: 'template-variable-defaults-{num}'
+    disabled: '{obj:disabled_var}'
+    builders:
+      - shell: |
+         echo "Job Name: template-variable-defaults-{num}-{type}"
+         echo "Variable: {test_var}"