Skip to content

Dropwizard/Soabase bundle for serving multi-language web apps using Handlebars

Notifications You must be signed in to change notification settings

soabase/soabase-web

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Build Status Maven Central

soabase-web

Soabase Web is a Dropwizard extension that enables easy serving of multi-language web apps using the Java version of Handlebars with the following features:

  • Can serve from a directory or a ZIP/JAR file
    • Serving from a directory makes development simpler
    • Serving from a ZIP/JAR makes production deployment/management easier
  • Can serve a main application and, optionally, a separate admin application
  • Two modes:
    • Development - application assets are reloaded on each request for real-time development
    • Production - application assets are cached using Dropwizard's standard CachedAsset
  • Supports multi-language subsitutions using Handlebars templates
  • Optional Root filter that redirects from "/" to the configured main page
  • Optional Language filter for managing page language via a cookie

Example

See the Example for an annotated example of using Soabase Web.

Usage

Soabase Web is available from Maven Central:

  • GroupId - io.soabase
  • ArtifactId - soabase-web

Soabase Web is a Dropwizard bundle. Add the WebBundle to your Dropwizard application's bootstrap. WebBundle takes two arguments: ContextFactory and ConfigAccessor.

ConfigAccessor

You must pass an instance to a ConfigAccessor implementation to the WebBundle constructor. Soabase Web uses this instance to access its configuration information. ConfigAccessor has two methods:

  • getAppConfiguration()
  • getAdminConfiguration()

Both return a WebConfiguration instance containing configuration info for Soabase Web. See below for the configuration details. getAdminConfiguration() returns an Optional. Return an Optional.empty() if you don't want a Soabase Web admin implementation.

ContextFactory

The ContextFactory returns a Handlebars model object for the given request and language. You can return an empty HashMap or any type of object you'd like to use. Note: Soabase web (unless configured not to) will cache the model object for the request URL and language.

WebConfiguration

Field Default Description
debug false If true no files or models are cached
defaultFile "/index.html" The path to use when none is specified in the URL
uriPath "/web" The base URI path. This portion of the URI is ignored when searching for the file to return
templateExtensions "js", "html", "htm", "css", "template" Extensions for files that should be passed through the Handlebars template processor
textDir "text" The directory relative path that contains language files (see below)
assetsFile null Path to the directory or zip file with the website assets
addRootFilter true If true, adds a servlet filter that routes "root" requests (i.e. "/") to the default file
requestLanguage DefaultRequestLanguageFactory the langauge handler (see below)
modelCache DefaultModelCacheFactory The model cache factory (see below)

Language Files

Soabase Web can enhance your Handlebars models with language specific text. This makes it much easier to translate your web application. A language file is a simple text file. The name of the file is LANG.txt where LANG is the language code (e.g. en.txt). The file format is also simple: each line starts with a key for the text followed by a whitespace (or an '=' sign) and then the text. The key is added to the Handlebars model on each request with the appropriate value for the request language. E.g.

en.txt

nameStr   Enter your name

es.txt

nameStr   Introduzca su nombre

index.html

...
<div>{{nameStr}}</div>
...

RequestLanguage and RequestLanguageFactory

RequestLanguageFactory and RequestLanguage is used to determine the language code for each request. You can add custom RequestLanguageFactory instances using the standard Dropwizard method (see Polymorphic configuration). The default implementation, DefaultRequestLanguageFactory, uses cookies and query params to store/change the language. It has the following available configuration:

Field Default Description
cookieName "soabase_web_langauge" The name of the cookie that stores the language code
queryParameterName "lang" The name of the query parameter used to change the language
defaultLanguageCode "en" The default language code if none is set
validLanguageCodes empty Used to limit which language codes are accepted

The DefaultRequestLanguageFactory adds a servlet filter that looks for the configured queryParameterName on every request. If found, the language cookie is set.

The RequestLanguage interface is used to return the language code for a request. The DefaultRequestLanguageFactory returns the value of the cookie or the default.

ModelCache and ModelCacheFactory

In most cases, it doesn't make sense to recreate a Handlebars model on each request. Therefore, Soabase Web supports caching the model. You can add custom ModelCacheFactory instances using the standard Dropwizard method (see Polymorphic configuration). The default factory, DefaultModelCacheFactory caches the model for each unique host name and language.

The ModelCache instance is used to return either a cached model or to use the given method to create a new model, cache it, and return it.

Handlebars Extensions

  • The Handlebars StringHelper is automatically added by Soabase Web
  • Language Files (see above)
  • ConcatHelper - makes it easy to concat files together at runtime. Usage: {{{concat "base-dir" "file-1" ... "file-2"}}}. All the specified files from the given relative directory are concatenated as if they were a single file

About

Dropwizard/Soabase bundle for serving multi-language web apps using Handlebars

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages