From 249387d37e19c438dcb51707fd5573bd770503ff Mon Sep 17 00:00:00 2001
From: Tim Schnell <tim.schnell@rackspace.com>
Date: Wed, 11 Dec 2013 22:56:51 +0000
Subject: [PATCH] Adds parameter_groups to HOT specification.

The ability to group and order parameters in the template is
currently missing. This patch allows for a new section of the
template, parameter_groups, to be added by the template author
to explicitly define the expected behavior.

Change-Id: I6d8dc4e6490fbfe9cc45f6ca9cb1ac2826e13273
Implements: blueprint parameter-grouping-ordering
---
 doc/source/template_guide/hot_spec.rst | 51 +++++++++++++++++++++++++-
 heat/engine/hot.py                     |  6 +--
 2 files changed, 53 insertions(+), 4 deletions(-)

diff --git a/doc/source/template_guide/hot_spec.rst b/doc/source/template_guide/hot_spec.rst
index e6a560f77a..bd11d465c1 100644
--- a/doc/source/template_guide/hot_spec.rst
+++ b/doc/source/template_guide/hot_spec.rst
@@ -42,7 +42,11 @@ HOT templates are defined in YAML and follow the structure outlined below.
 
   heat_template_version: 2013-05-23
 
-  description: # a description of the template
+  description: 
+    # a description of the template
+
+  parameter_groups:
+    # a declaration of input parameter groups and order
 
   parameters:
     # declaration of input parameters
@@ -61,6 +65,11 @@ description
     This *optional* key allows for giving a description of the template, or the
     workload that can be deployed using the template.
 
+parameter_groups
+    This section allows for specifying how the input parameters should be
+    grouped and the order to provide the parameters in. This section is
+    *optional* and can be omitted when necessary.
+
 parameters
     This section allows for specifying input parameters that have to be provided
     when instantiating the template. The section is *optional* and can be
@@ -77,6 +86,46 @@ outputs
     omitted when no output values are required.
 
 
+.. _hot_spec_parameter_groups:
+
+------------------------
+Parameter Groups Section
+------------------------
+
+The *parameter_groups* section allows for specifying how the input parameters
+should be grouped and the order to provide the parameters in. These groups are
+typically used to describe expected behavior for downstream user interfaces.
+
+These groups are specified in a list with each group containing a list of
+associated parameters. The lists are used to denote the expected order of the
+parameters. Each parameter should be associated to a specific group only once
+using the parameter name to bind it to a defined parameter in the parameters
+section.
+
+::
+
+  parameter_groups:
+  - label: <human-readable label of parameter group>
+    description: <description of the parameter group>
+    parameters:
+    - <param name>
+    - <param name>
+
+label
+    A human-readable label that defines the associated group of parameters.
+
+description
+    This attribute allows for giving a human-readable description of the
+    parameter group.
+
+parameters
+    A list of parameters associated with this parameter group.
+
+param name
+    The name of the parameter that is defined in the associated parameters
+    section.
+
+
 .. _hot_spec_parameters:
 
 ------------------
diff --git a/heat/engine/hot.py b/heat/engine/hot.py
index ff6a8c328d..440b50512d 100644
--- a/heat/engine/hot.py
+++ b/heat/engine/hot.py
@@ -21,10 +21,10 @@ from heat.openstack.common import log as logging
 
 logger = logging.getLogger(__name__)
 
-SECTIONS = (VERSION, DESCRIPTION, PARAMETERS,
+SECTIONS = (VERSION, DESCRIPTION, PARAMETER_GROUPS, PARAMETERS,
             RESOURCES, OUTPUTS, UNDEFINED) = \
-           ('heat_template_version', 'description', 'parameters',
-            'resources', 'outputs', '__undefined__')
+           ('heat_template_version', 'description', 'parameter_groups',
+            'parameters', 'resources', 'outputs', '__undefined__')
 
 PARAM_CONSTRAINTS = (CONSTRAINTS, DESCRIPTION, LENGTH, RANGE,
                      MIN, MAX, ALLOWED_VALUES, ALLOWED_PATTERN) = \