From 255046b3f3484219bbfa6646c88bbc4bbc1b5256 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Fri, 16 Nov 2012 14:40:42 -0500 Subject: Templating updates: * Added "repo" variable to all template formats * Made variables available in Genshi and Cheetah template more similar * Improved docs --- doc/server/plugins/generators/cfg.txt | 85 +++++++++++++++---------- doc/server/plugins/structures/bundler/index.txt | 55 ++++++---------- 2 files changed, 69 insertions(+), 71 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 25986a413..7d0e0acff 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -106,26 +106,13 @@ Genshi templates allow you to use the `Genshi the deprecated :ref:`server-plugins-generators-tgenshi-index` plugin. Genshi templates should be named with a ``.genshi`` extension, e.g.:: - % ls Cfg/etc/motd + % ls Cfg/etc/motd info.xml motd.genshi See the genshi `documentation `_ for examples of Genshi syntax. -Inside Genshi Templates -~~~~~~~~~~~~~~~~~~~~~~~ - -Several variables are pre-defined inside templates: - -* **metadata** is the client's :ref:`metadata - ` -* **name** is the path name specified in Bcfg2 -* **path** is the path to the TGenshi template. It starts with a - leading slash, and is relative to the Bcfg2 specification root. - E.g., ``/Cfg/etc/foo.conf/foo.conf.genshi`` or - ``/TGenshi/etc/foo.conf/template.newtxt.H_foo.example.com`` - Troubleshooting ~~~~~~~~~~~~~~~ @@ -138,7 +125,8 @@ E.g.:: bcfg2-info buildfile /etc/foo.conf foo.example.com -To generate a file with an altsrc attribute, you can run:: +To generate a file with an :ref:`altsrc +` attribute, you can run:: bcfg2-info buildfile /etc/foo/foo.conf --altsrc=/etc/foo.conf \ foo.example.com @@ -149,13 +137,13 @@ debug``, and, once in the Python interpreter, run:: metadata = self.build_metadata("") path = "" - + ``path`` should be set to the path to the template file with a leading slash, relative to the Bcfg2 specification root. See `Inside Genshi Templates`_ for examples. Then, run:: - + import os, Bcfg2.Options from genshi.template import TemplateLoader, NewTextTemplate name = os.path.dirname(path[path.find('/', 1):]) @@ -230,19 +218,9 @@ Cheetah templates allow you to use the `cheetah templating system the deprecated :ref:`server-plugins-generators-tcheetah` plugin. Cheetah templates should be named with a ``.cheetah`` extension, e.g.:: - % ls Cfg/etc/motd + % ls Cfg/etc/motd info.xml motd.cheetah -Inside Cheetah Templates -~~~~~~~~~~~~~~~~~~~~~~~~ - -Several variables are pre-defined inside templates: - -* **self.metadata** is the client's :ref:`metadata - ` -* **self.path** is the path name specified in Bcfg2 -* **self.source_path** is the path to the Genshi template on the filesystem. - Examples ~~~~~~~~ @@ -265,12 +243,48 @@ comment to appear in the final config file.:: # This is a comment in my template which will be stripped when it's processed through Cheetah \# This comment will appear in the generated config file. +Inside Templates +---------------- + +Several variables are pre-defined inside templates: + ++-------------+--------------------------------------------------------+ +| Name | Description | ++=============+========================================================+ +| metadata | :ref:`Client metadata | +| | ` | ++-------------+--------------------------------------------------------+ +| name | The value of the ``name`` attribute as specified in | +| | the Path entry in Bcfg2. If an :ref:`altsrc | +| | ` attribute is used, | +| | then ``name`` will be the value of that attribute. | ++-------------+--------------------------------------------------------+ +| source_path | The path to the template file on the filesystem | ++-------------+--------------------------------------------------------+ +| repo | The path to the Bcfg2 repository on the filesystem | ++-------------+--------------------------------------------------------+ +| path | In Genshi templates, ``path`` is a synonym for | +| | ``source_path``. In Cheetah templates, it's a synonym | +| | for ``name``. For this reason, use of ``path`` is | +| | discouraged, and it may be deprecated in a future | +| | release. | ++-------------+--------------------------------------------------------+ + +To access these variables in a Genshi template, you can simply use the +name, e.g.:: + + Path to this file: ${name} + +In a Cheetah template, the variables are properties of ``self``, +e.g.:: + + Path to this file: $self.name Notes on Using Templates ------------------------ Templates can be host and group specific as well. Deltas will not be -processed for any genshi or cheetah base file. +processed for any Genshi or Cheetah base file. .. note:: @@ -278,19 +292,22 @@ processed for any genshi or cheetah base file. or group-specific files, you will need to ensure that the ``.genshi`` or ``.cheetah`` extension is at the **end** of the filename. Using the examples from above for *host.example.com* and group *server* you would - have the following (using genshi only):: + have the following:: Cfg/etc/fstab/fstab.H_host.example.com.genshi - Cfg/etc/fstab/fstab.G50_server.genshi + Cfg/etc/fstab/fstab.G50_server.cheetah Genshi templates take precence over cheetah templates. For example, if -two files exist named +two files exist named:: Cfg/etc/fstab/fstab.genshi Cfg/etc/fstab/fstab.cheetah -the cheetah template is ignored. But you can mix genshi and cheetah when -using different host-specific or group-specific files. For example: +The Cheetah template is ignored. Exploiting this fact is probably a +pretty bad idea in practice. + +You can mix Genshi and Cheetah when using different host-specific or +group-specific files. For example: Cfg/etc/fstab/fstab.H_host.example.com.genshi Cfg/etc/fstab/fstab.G50_server.cheetah diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 528df79db..1cc287ebd 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -113,40 +113,31 @@ demonstrates how group entries can be used in bundles) Genshi templates ================ -Genshi xml templates can be specified one of two ways: +Genshi XML templates allow you to use the `Genshi +`_ templating system to dynamically +generate a bundle. Genshi templates can be specified one of two ways: -1. Add an xml-style genshi template to the Bundler directory with a +1. Add an XML-style genshi template to the Bundler directory with a ``.genshi`` and the associated namespace attribute. -2. Simply add the appropriate namespace attribute to your existing xml +2. Simply add the appropriate namespace attribute to your existing XML bundle. -The namespace attribute in this case should look like the following:: +The top-level Bundle tag should look like the following:: - xmlns:py="http://genshi.edgewall.org/" + -Motivation ----------- +Several variables are pre-defined inside templates: -Static Bundles have served us relatively well, but have a relatively -weak set of interal per-client differentiation mechanisms. In static -Bundles, the group hierarchy (from the perspective of the current -client) is available for use via boolean constraints with negation. This -notion does not mesh well with the use of Probes, which can result in -freeform data. In the presence of probe results, clients can have a wide -array of data, and rendering down to a boolean logic may not always -be desirable. Moreover, while static Bundles allow entry inclusion or -exclusion based on group memberships, they do not allow programatic entry -rendering. Hence, Genshi templates not only provide more control options, -but it also provide the ability to perform new entry rendering operations. ++-------------+--------------------------------------------------------+ +| Name | Description | ++=============+========================================================+ +| metadata | :ref:`Client metadata | +| | ` | ++-------------+--------------------------------------------------------+ +| repo | The path to the Bcfg2 repository on the filesystem | ++-------------+--------------------------------------------------------+ -The `Genshi templating system`_ is used internally. - -.. _Genshi templating system: http://genshi.edgewall.org/ - -Use ---- - -.. warning:: +.. note:: ```` and ```` tags are allowed inside of Genshi templates as of Bcfg2 1.2. However, they do not behave the same @@ -154,7 +145,7 @@ Use - + The conditional is evaluated when the template is rendered, so code inside the conditional is not executed if the conditional fails. A ```` tag is evaluated *after* the template is @@ -163,16 +154,6 @@ Use groups, you *must* use a Genshi conditional, not a ```` tag. The same caveats apply to ```` tags. -Bcfg2 uses the Genshi API for templates, and performs a XML format -stream rendering of the template into an lxml entry, which is included -in the client configuration. :ref:`Client metadata ` -is available inside of the template using the 'metadata' name. Note that -only the markup Genshi template format can be used, as the target output -format is XML. - -A Genshi template looks much like a Bundler file, except the Bundle tag -has an additional `xmlns:py` attribute. See the examples. - Troubleshooting --------------- -- cgit v1.2.3-1-g7c22