Differences

This shows you the differences between two versions of the page.

--- esmith:template [2015/05/22 08:12]
stephdl [$DB]
+++ esmith:template [2019/06/05 19:48]
@@ Line 1: / Line 1: @@
-===== esmith::template =====
- esmith::template - Utilities for e-smith server and gateway development<br />
-In a root terminal you can do the command below if you want to display the up-to-date content
- perldoc esmith::templates
-===== VERSION =====
-This file documents "esmith::template" version 1.7.0
-===== SYNOPSIS =====
-           use esmith::template;
-           processTemplate(...);
-===== DESCRIPTION =====
-This is the interface to the E-Smith templating system.  For an overview of how the system works, see section [[SME_Server:Documentation:Developers_Manual#Configuration_file_templates| Templated Configuration System]] of the Dev Guide.
-esmith::template exports a single function, processTemplate, which, as you might guess, processes sets of templates into a single output file.
-===== Template Variables =====
-The following variables are available to all templates.
-==== $confref ====
-DEPRECATED.  Contains a reference to the hash passed in via CONFREF.  If none was given it defaults to a tied esmith::config hash.
-==== $DB ====
-Contains a reference to an esmith::ConfigDB object pointing at the default configurations.  This is to be used to call methods like "$DB-"services> and *not* for alterting the database.
-In addition, each record in the default esmith configuration database (configuration) is available as a hash if it has multiple properties(where each key/value is a property of the record) or if it has a single property (type) then it given as a scalar.
-So you can say:
-           { $DomainName }     # $configdb->get(’DomainName’)->value;
-           { $sshd{status} }   # $configdb->get(’sshd’)->prop(’status’)
-Finally, variables from additional databases are usually gotten via the esmith::DB->as_hash feature.
-           {  require esmith::HostsDB;
-              my %Hosts = esmith::HostsDB->as_hash;
-              ...
-           }
-===== Functions =====
-       processTemplate
-             processTemplate({ CONFREF       => \%config,
-                               TEMPLATE_PATH => $output_file
-                            });
-             $filled_in_template = processTemplate({ CONFREF       => \%config,
-                                                     TEMPLATE_PATH => $output_file
-                                                     OUTPUT_TYPE   => ’string’
-                                                   });
-processTemplate() expands a set of templates based on the keys/values in %config.
-           The options to processTemplate are as follows...
-==== MORE_DATA ====
-A hash ref containing additional variables you’d like to put into the template.  Key is the name of the variable, value is it’s value.
-                   # $Foo = ’bar’
-                   MORE_DATA => { Foo => "bar" }
-Any keys in MORE_DATA will override those from the default
-               esmith::ConfigDB.
-This replaces CONFREF.
-==== CONFREF ====
-DEPRECATED.  A reference to the hash which will become the variables in the template.  So $config{Foo} becomes $Foo.  In addition, there is the $confref variable which contains a reference back to the original CONFREF.
-This is usually a tied esmith::config hash.
-This has been replaced by MORE_DATA and cannot be used in conjunction.
-==== TEMPLATE_PATH ====
-Full path to the file which fill result from this template.
-For example, ’/etc/hosts’.
-==== TEMPLATE_EXPAND_QUEUE ====
-List of directories to scan for templates.  If not specified it
-defaults to:
-                   /etc/e-smith/templates-custom
-                   /etc/e-smith/templates
-it then appends the TEMPLATE_PATH to this, so the resulting search might be:
-                   /etc/e-smith/templates-custom/etc/host
-                   /etc/e-smith/templates/etc/host
-All templates found are combined in ASCIIbetical order to produce the final file.  The exception to this is template-begin, which always comes first, and template-end, which always comes last.
-If no template-begin is found the one in /etc/e-smith/templates-default/ will be used.
-If two directories contain the same template those eariler in the queue will override those later.  So /etc/e-smith/templates-custom/foo will be used instead of /etc/e-smith/templates/foo.
-==== OUTPUT_PREFIX ====
-Directory which contains the OUTPUT_FILENAME.
-==== OUTPUT_FILENAME ====
-The file which results from this template.
-Defaults to the TEMPLATE_PATH.
-==== FILTER ====
-A code ref through which each line of the resulting text is fed, for example:
-                   FILTER => sub { "# $_[0]" }
-would put a # in front of each line of the template.
-                   FILTER => sub { $_[0] =~ /^\s*$/ ? ’’ : $_[0] }
-will remove all lines that contain only whitespace.
-           UID
-           GID The user and group ID by which the resulting file should be
-               owned.  This obviously means you have to run procTemplate as
-               root.
-Defaults to UID 0 and GID 0.
-==== PERMS ====
-File permissions which the resulting file should be set to have.
-               Defaults to 0644.
-==== OUTPUT_TYPE ====
-Determines if the filled in template should go straight to a file or be returned by processTemplate().  The values can be:
-                   string     return the filled in template
-                   file       write it to disk
-Defaults to ’file’
-For example we have a template /etc/e-smith/templates/etc/hosts that we want to expand to /etc/hosts using the normal configuration.
-               # Records from esmith::ConfigDB->open will be available by default
-               processTemplate({
-                   TEMPLATE_PATH => ’/etc/hosts’,
-               });
-Example 2: we have a template /etc/e-smith/templates-user/qmail that we want to expand to /home/e-smith/files/users/$username/.qmail
-Solution:
-               processTemplate({
-                   TEMPLATE_PATH => ’/qmail’,
-                   TEMPLATE_EXPAND_QUEUE => [
-                       ’/etc/e-smith/templates-user-custom’,
-                       ’/etc/e-smith/templates-user’,
-                   ],
-                   OUTPUT_PREFIX => ’/home/e-smith/files/users/$username’,
-                   OUTPUT_FILENAME => ’.qmail’,
-                   FILTER => sub { $_[0] =~ /^\s*$/ ? ’’ : $_[0] },
-                   UID => $username,
-                   GID => $username,
-                   PERMS => 0644,
-               });
-Example 3: we have a template fragment /etc/e-smith/templates/etc/httpd/conf/httpd.conf/80VirtualHosts that needs to iterate through the given list of VirtualHosts, process each template and return the results in a string until all the VirtualHosts have been completed.  The results will be expanded into the /etc/httpd/conf/httpd.conf file.
-Solution: In the 80VirtualHosts fragment, we use the OUTPUT_TYPE=’string’ option to return the output of processTemplate for each VirtualHost as a string, and then we add the results to the $OUT variable for inclusion in the httpd.conf template expansion.  We store the VirtualHosts template in /etc/httpd/conf/httpd.conf/VirtualHosts for clarity and namespace separation.
-               foreach my $ipAddress (keys %ipAddresses)
-               {
-                   # the $OUT variable stores the output of this template fragment
-                   use esmith::templates;
-                   $OUT .= processTemplate (
-                       {
-                           MORE_DATA => { ipAddress => $ipAddress, port => $port,
-                                          virtualHosts => \@virtualHosts,
-                                          virtualHostContent => \%virtualHostContent },
-                           TEMPLATE_PATH => "/etc/httpd/conf/httpd.conf/VirtualHosts",
-                           OUTPUT_TYPE => ’string’,
-                       });
-               }
-==== Filters ====
-Filters are an experimental feature which allow you to filter the output of a template in various ways.
-Filtering functions take a single line at a time and return the filtered version.
-==== removeBlankLines ====
-Removes empty lines or those containing only whitespace from a template.
-===== SEE ALSO =====
-http://docs.nethserver.org/projects/nethserver-devel/en/latest/templates.html
-[http://wiki.contribs.org/Text::Template Text::Template]
-===== AUTHOR =====
-Mitel Networks Corporation
-For more information, see http://www.e-smith.org/
-{{tag> neth-development sme-development }}
-[[Category:SME Server Development Framework]]
-[[Category:Development Tools]]

Stephdl Repository

User Tools

Site Tools

Differences

Page Tools