ru.vyarus.guicey.gsp

Class ServerPagesBundle.AppBuilder

java.lang.Object

ru.vyarus.guicey.gsp.ServerPagesBundle.AppBuilder

Enclosing class:

ServerPagesBundle

public static class ServerPagesBundle.AppBuilder
extends java.lang.Object

Server pages application bundle builder.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AppBuilder(boolean mainContext, java.lang.String name, java.lang.String path, java.lang.String uri, GlobalConfig config)

Method Summary

Modifier and Type	Method and Description
ServerPagesBundle.AppBuilder	attachWebjars() Shortcut for ServerPagesBundle.extendApp("name", "META-INF/resources/webjars/").
ServerPagesAppBundle	build() Note: if bundle is used inside guicey bundle then use register(GuiceyBootstrap) for bundle installation.
ServerPagesBundle.AppBuilder	errorPage(int code, java.lang.String path) Show special page instead of response with specified status code.
ServerPagesBundle.AppBuilder	errorPage(java.lang.String path) Default error page (shown in case of exceptions and for all error return codes (>=400)).
ServerPagesBundle.AppBuilder	filePattern(java.lang.String regex) Differentiation of template call from static resource is based on fact: static resources have extensions.
ServerPagesBundle.AppBuilder	indexPage(java.lang.String name) Declares index page (served for "/" calls).
void	register(ru.vyarus.dropwizard.guice.module.installer.bundle.GuiceyBootstrap bootstrap) Use when server pages bundle must be registered within guicey bundle (guicey bundle could register custom application, e.g. for administration or simply register customizations for existing application).
ServerPagesBundle.AppBuilder	requireRenderers(java.lang.String... names) Specifies required template types (view renderes) for application.
ServerPagesBundle.AppBuilder	spaRouting() Shortcut for spaRouting(String) with default regexp.
ServerPagesBundle.AppBuilder	spaRouting(java.lang.String noRedirectRegex) Enable single page application html5 routing support.
ServerPagesBundle.AppBuilder	viewsConfigurationModifier(java.lang.String name, ViewRendererConfigurationModifier modifier) Dropwizard views configuration modification.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AppBuilder

protected AppBuilder(boolean mainContext,
                     java.lang.String name,
                     java.lang.String path,
                     java.lang.String uri,
                     GlobalConfig config)

Method Detail

requireRenderers

public ServerPagesBundle.AppBuilder requireRenderers(java.lang.String... names)

Specifies required template types (view renderes) for application. This setting is optional and used only for immediate application startup failing when no required renderer is configured in global server pages bundle (ServerPagesBundle.builder()).

Without declaring required renderer, application will simply serve template files "as is" when no appropriate renderer found (because template file will not be recognized as template).

Renderer name is a renderer configuration key, defined in ViewRenderer.getConfigurationKey().

Parameters:

names - required renderer names

Returns:

builder instance for chained calls

spaRouting

public ServerPagesBundle.AppBuilder spaRouting()

Shortcut for spaRouting(String) with default regexp.

Returns:

builder instance for chained calls

spaRouting

public ServerPagesBundle.AppBuilder spaRouting(java.lang.String noRedirectRegex)

Enable single page application html5 routing support.

Parameters:

noRedirectRegex - regex to match all cases when redirection not needed

Returns:

builder instance for chained calls

See Also:

for more info how it works, for more info about regexp

indexPage

public ServerPagesBundle.AppBuilder indexPage(java.lang.String name)

Declares index page (served for "/" calls). Index page may also be a template. If index view is handled with a rest then simply leave as "" (default): resource on path "{restPath}/{appMapping}/" will be used as root page.

Pay attention that index is not set by default to "index.html" because most likely it would be some template handled with rest resource (and so it would be too often necessary to override default).

Parameters:

name - index file name (by default "")

Returns:

builder instance for chained calls

errorPage

public ServerPagesBundle.AppBuilder errorPage(java.lang.String path)

Default error page (shown in case of exceptions and for all error return codes (>=400)).

Parameters:

path - either path to static resource (inside registered classpath path) or resource url (without app name prefix)

Returns:

builder instance for chained calls

See Also:

for registereing error page on exact return code

errorPage

public ServerPagesBundle.AppBuilder errorPage(int code,
                                              java.lang.String path)

Show special page instead of response with specified status code. Errors are intercepted both for assets and template rendering. For templates, jersey request listener used to intercept actual exceptions (to be able to access actual exception inside error page). Default dropwizard exception mapper will log error (as for usual rest).

Error pages should use ErrorTemplateView as (base) model class in order to get access to context exception. It is not required, if error object itself not required during rendering.

NOTE that error page is returned only if original request accept html response and otherwise no error page will be shown. Intention here is to show human readable errors only for humans.

IMPORTANT: GSP errors mechanism override ExceptionMapper and dropwizard-view ErrorEntityWriter mechanisms because exception is detected before them and request is redirected to error page. Both ExceptionMapper and EntityWriter would be called, but their result will be ignored (still, ExceptionMapper is useful for errors logging). This was done to avoid influence of global ExceptionMapper's to be sure custom error page used. It is possible to ignore GSP error mechanism for exact rest methods by using ManualErrorHandling annotation.

Parameters:

code - error code to map page onto

path - either path to static resource (inside registered classpath path) or resource url (without app name prefix)

Returns:

builder instance for chained calls

See Also:

for global errors page

attachWebjars

public ServerPagesBundle.AppBuilder attachWebjars()

Shortcut for ServerPagesBundle.extendApp("name", "META-INF/resources/webjars/"). Useful if you want to use resources from webjars. All webjars package resources under the same path (e.g. META-INF/resources/webjars/jquery/3.4.1/dist/jquery.min.js), so after enabling webjars support you can reference any resource from webjar (in classpath) (e.g. as <script src="jquery/3.4.1/dist/jquery.min.js">).

Returns:

builder instance for chained calls

filePattern

public ServerPagesBundle.AppBuilder filePattern(java.lang.String regex)

Differentiation of template call from static resource is based on fact: static resources have extensions. So when "/something/some.ext" is requested and extension is not supported template extension then it's direct asset. In case when you have static files without extension, you can include them directly into detection regexp (using regex or (|) syntax).

Pattern must return detected file name as first matched group (so direct template could be detected). Pattern is searched (find) inside path, not matched (so simple patterns will also work).

Parameters:

regex - regex for file request detection and file name extraction

Returns:

builder instance for chained calls

See Also:

default pattern

viewsConfigurationModifier

public ServerPagesBundle.AppBuilder viewsConfigurationModifier(java.lang.String name,
                                                               ViewRendererConfigurationModifier modifier)

Dropwizard views configuration modification. Views configuration could be bound only in global server pages support bundle (ServerPagesBundle.ViewsBuilder.viewsConfiguration(ViewConfigurable)). But it's often required to "tune" template engine specifically for application. This method allows global views configuration modification for exact server pages application.

The main use case is configuration of the exact template engine. For example, in case of freemarker this could be used to apply auto includes:

  .viewsConfigurationModifier("freemarker", config -> config
                         // expose master template
                         .put("auto_include", "/com/my/app/ui/master.ftl"))

Note that configuration object is still global (becuase dropwizard views support is global) and so multiple server pages applications could modify configuration. For example, if multiple applications will declare auto includes (example above) then only one include will be actually used. Use ServerPagesBundle.ViewsBuilder.printViewsConfiguration() to see the final view configuration.

Parameters:

name - renderer name (e.g. freemarker, mustache, etc.)

modifier - modification callback

Returns:

builder instance for chained calls

build

public ServerPagesAppBundle build()

Note: if bundle is used inside guicey bundle then use register(GuiceyBootstrap) for bundle installation.

Returns:

configured dropwizard bundle instance

register

public void register(ru.vyarus.dropwizard.guice.module.installer.bundle.GuiceyBootstrap bootstrap)

Use when server pages bundle must be registered within guicey bundle (guicey bundle could register custom application, e.g. for administration or simply register customizations for existing application).

Parameters:

bootstrap - guicey bootstrap object