diff --git a/_includes/docs/use/toc.html b/_includes/docs/use/toc.html index f0a2cff..6115997 100644 --- a/_includes/docs/use/toc.html +++ b/_includes/docs/use/toc.html @@ -17,6 +17,7 @@
  • Writing Tests
  • Running Tests
  • Config Files
    • +
  • Using App Tokens
  • Custom Templates
  • Internationalizing your app
    • diff --git a/docs/use/app_tokens.md b/docs/use/app_tokens.md new file mode 100644 index 0000000..9375519 --- /dev/null +++ b/docs/use/app_tokens.md @@ -0,0 +1,63 @@ +--- +layout: docs +title: Using App Tokens +permalink: /docs/use/app_tokens/ +--- + +Apps can make use of tokens where the replacement can be configured depending on the scenario. Tokens in content take the format `@[A-Z\.]+@`, for example `@MY.TOKEN@`, and can be included in any file. There are two mechanisms that are used when find a token replacement. + +## Property Files + +BRJS will first attempt to locate a token replacement in an app properties file located in `/app-properties`. + +Token replacements will first be read from `/app-properties/default.properties` and can then be overridden in environment specific property files. To set the environment use the `-e` flag with either the `serve` or `build-app` commands. + +Properties files should have the format: + +``` +MY.TOKEN=my token replacement +``` + +For example `brjs build-app myapp -e production` will first read properties from ``/app-properties/default.properties` and then an optional overridding property from `/app-properties/production.properties`. + +Static file apps must provide a replacement for all properties used within an app. If a replacement is not provided an exception will be thrown. 'J2EE' apps, those that have a `WEB-INF` directory, can opt to provide some tokens via JNDI (see below). + +Note: To use different tokens for different environment a static app must be built several times using a different environment setting each time. + +## JNDI Replacement + +J2EE apps can use [JNDI](https://en.wikipedia.org/wiki/Java_Naming_and_Directory_Interface) to provide token replacements. This gives the advantage that a single artifact can be generated and a JNDI database configured for each environment to supply the replacements. + +To use JNDI tokens in development, configure `/WEB-INF/jetty-env.xml` to provide the replacements. For example: + +``` + + + + + + + + + + + + MY.JNDI.TOKEN + My JNDI token replacement + true + + + +``` + +In production, how JNDI is configured will depend on the JNDI service you are using. + + +## BRJS System Tokens + +Tokens begining `BRJS.` are BRJS system tokens and cannot be overdidden by property files or JNDI. Supported system tokens are listed below. + +- BRJS.APP.LOCALE: If used in an index page will be replaced with the page's locale, otherwise replaced with the app's default locale. +- BRJS.APP.NAME: The name of the app. +- BRJS.APP.VERSION: The app version. Either automatically generated or specified by using the `-v` flag. +- BRJS.BUNDLE.PATH: The relative path to bundle requests. This should be used if trying to reference bundles since the relative URL will change depending on the version used.