brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From drigodwin <...@git.apache.org>
Subject [GitHub] brooklyn-docs pull request #178: Guide to template files
Date Wed, 10 May 2017 11:57:22 GMT
Github user drigodwin commented on a diff in the pull request:

    https://github.com/apache/brooklyn-docs/pull/178#discussion_r115720672
  
    --- Diff: guide/blueprints/config-files.md ---
    @@ -0,0 +1,104 @@
    +---
    +title: Uploading Script and Configuration Files
    +layout: website-normal
    +toc: ../guide_toc.json
    +categories: [use, guide, defining-applications]
    +---
    +
    +Blueprints often require that parameterized scripts and configuration files are available
to be copied to the
    +target VM. These must be URLs resolvable from the Brooklyn instance, or on the Brooklyn
classpath.
    +
    +There are two types of file that can be uploaded: plain files and templated files. A
plain
    +file is uploaded unmodified. A templated file is interpreted as a [FreeMarker](http://freemarker.org)
    +template. This supports a powerful set of substitutions. In brief, anything (unescaped)
of the form
    +`${name}` will be substituted, in this case looking up "name" for the value to use.
    +
    +
    +## Writing templates
    +
    +Templated files (be they configuration files or scripts) give a powerful way to inject
dependent
    +configuration when installing an entity (e.g. for customising the install, or for referencing
the
    +connection details of another entity). Available substitutions are:
    +
    +| Substitution              | Effect                                                
            |
    +|---------------------------|--------------------------------------------------------------------|
    +| `${config['key']}`        | Equivalent to `entity.config().get(key)`              
            |
    +| `${attribute['key']}`     | Equivalent to `entity.sensors().get(key)`             
            |
    +| `${mgmt['key']}`          | Loads the value for `key` from the management context's
properties |
    +| `${entity.foo}`           | FreeMarker calls `getFoo` on the entity               
            |
    +| `${driver.foo}`           | FreeMarker calls `getFoo` on the entity's [driver](http://brooklyn.apache.org/v/latest/java/entity.html#things-to-know)
|
    +| `${location.foo}`         | FreeMarker calls `getFoo` on the entity's location    
            |
    +| `${javaSysProps.foo.bar}` | Loads the system property named `foo.bar`             
            |
    +
    +Additional substitutions can be given per-entity by setting the `template.substitutions`
key. For example,
    +to include the address of an entity called db:
    +
    +    brooklyn.config
    +      template.substitutions:
    +        databaseAddress: $brooklyn:entity("db").attributeWhenReady("host.address")
    +
    +The value can be referenced in a template with `${databaseAddress}`.
    +
    +FreeMarker evaluates all expressions between `${}` which may be inappropriate in certain
kinds of files.
    +To include the literal `${value}` in a script you might:
    + * specify a [raw string literal](http://freemarker.org/docs/dgui_template_exp.html#dgui_template_exp_direct_string):
    +   `${r"${value}"}`
    + * use the [noparse](http://freemarker.org/docs/ref_directive_noparse.html) directive:
`<#noparse>${value}</#noparse>`
    + * use FreeMarker's [alternative syntax](http://freemarker.org/docs/dgui_misc_alternativesyntax.html).
    +
    +A common pattern for templating Bash files is to set environment variables at the top
of the script and to surround
    +the rest of its contents with `noparse`. For example:
    +
    +```
    --- End diff --
    
    The website uses kramdown not markdown, the three backticks doesn't display in the same
way. It's better to use four spaces before each line as in the example section.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message