{"id":26121567,"url":"https://github.com/fizzed/ninja-rocker","last_synced_at":"2025-04-13T12:51:16.435Z","repository":{"id":28920419,"uuid":"32445517","full_name":"fizzed/ninja-rocker","owner":"fizzed","description":"Rocker templates + Ninja framework integration","archived":false,"fork":false,"pushed_at":"2021-06-07T16:32:26.000Z","size":1662,"stargazers_count":15,"open_issues_count":2,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-27T03:51:21.970Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fizzed.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-18T08:00:43.000Z","updated_at":"2024-04-22T16:56:17.000Z","dependencies_parsed_at":"2022-08-02T12:14:02.486Z","dependency_job_id":null,"html_url":"https://github.com/fizzed/ninja-rocker","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fizzed%2Fninja-rocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fizzed%2Fninja-rocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fizzed%2Fninja-rocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fizzed%2Fninja-rocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fizzed","download_url":"https://codeload.github.com/fizzed/ninja-rocker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248717252,"owners_count":21150388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-10T14:23:53.583Z","updated_at":"2025-04-13T12:51:16.416Z","avatar_url":"https://github.com/fizzed.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Ninja Framework + Rocker Templates by Fizzed\n============================================\n\n[![Build Status](https://travis-ci.org/fizzed/ninja-rocker.svg?branch=master)](https://travis-ci.org/fizzed/ninja-rocker)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.fizzed/ninja-rocker/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.fizzed/ninja-rocker)\n\n[Fizzed, Inc.](http://fizzed.com) (Follow on Twitter: [@fizzed_inc](http://twitter.com/fizzed_inc))\n\n## Overview\n\nIntegration of [Rocker templates](https://github.com/fizzed/rocker) with the\n[Ninja Framework](https://github.com/ninjaframework/ninja). Rocker is a Java 8\noptimized, near zero-copy rendering, speedy template engine that produces\nstatically typed, plain java object templates that are compiled along with the\nrest of your project.\n\nThis project makes Rocker templates a first-class citizen to Ninja. All\nNinja-specific functionality is provided by way of the `N` variable that is\navailable to all templates. Here is a quick sample of what a `index.rocker.html`\ntemplate would look like using a few of the most common Ninja features.\n\n```html\n@import controllers.Application\n\n@args (String title)\n\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003ctitle\u003e@title\u003c/title\u003e\n    \u003clink rel='stylesheet' href='@N.webJarsAt(\"bootstrap/3.3.2-1/css/bootstrap.min.css\")'\u003e\n    \u003clink rel='stylesheet' href='@N.assetsAt(\"css/app.css\")'\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    Hi!\n    \u003ca href='@N.reverseRoute(Application.class, \"index\")'/\u003eHome\u003c/a\u003e\n\u003c/body\u003e\n\u003cscript type=\"text/javascript\"\u003e\n@if (N.isProd()) {\n    /* production-only code (e.g. google analytics) */\n}\n\u003c/script\u003e\n\u003c/html\u003e\n```\n\nOnce compiled into your project, you can call this template from your Ninja\ncontroller.  Fully type safe and compile-time checked.\n\n```java\npublic class Application {\n    \n    public Result index() {\n        return Results.ok().render(\n            views.index.template(\"Home\")\n        );\n    }\n\n}\n```\n\n## Demo \n\nThere is a Ninja app in the `demo` folder that demonstrates all the functionality\nthis module provides and it's a simple way to see how it works.  This project \nuses [Blaze](https://github.com/fizzed/blaze) to help script tasks. Run the\nfollowing in your shell (from the root project directory, not in `demo`):\n\n    java -jar blaze.jar demo\n\nOnce running, point your browser to http://localhost:8080/\n\n## Ninja 5 (or lower) support?\n\nPlease use `ninja-rocker` v0.15.0 or below if you need to target an older version\nof Ninja.\n\n## Setup\n\n### Add dependency\n\nAdd the ninja-rocker-module dependency to your Maven pom.xml\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.fizzed\u003c/groupId\u003e\n    \u003cartifactId\u003eninja-rocker-module\u003c/artifactId\u003e\n    \u003cversion\u003e0.16.0\u003c/version\u003e\n\u003c/dependency\u003e\n\n\u003c!-- for hot-reloading support only during development --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.fizzed\u003c/groupId\u003e\n    \u003cartifactId\u003erocker-compiler\u003c/artifactId\u003e\n    \u003cversion\u003e0.15.0\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n\n```\n\n### Add module to conf/Module.java\n\nAdd the module to your conf/Module.java file. Once installed, Rocker will\nreplace the default FreeMarker template engine for all content with the type\nof \"text/html\".\n\n```java\npackage conf;\n\nimport com.fizzed.ninja.rocker.NinjaRockerModule;\nimport com.google.inject.AbstractModule;\n\npublic class Module extends AbstractModule {\n\n    @Override\n    protected void configure() {\n        install(new NinjaRockerModule());\n    }\n\n}\n```\n\n### Add maven plugin\n\nRocker ties into Maven with a plugin to parse templates and generate the Java\nsource during the \u003ccode\u003egenerate-sources\u003c/code\u003e phase.  In order to access\nthe `N` variable and access Ninja features in your templates, it's critical\nyou configure the `extendsClass` variable as below.\n\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003ecom.fizzed\u003c/groupId\u003e\n            \u003cartifactId\u003erocker-maven-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e0.15.0\u003c/version\u003e\n            \u003cexecutions\u003e\n                \u003cexecution\u003e\n                    \u003cid\u003egenerate-rocker-templates\u003c/id\u003e\n                    \u003cgoals\u003e\n                        \u003cgoal\u003egenerate\u003c/goal\u003e\n                    \u003c/goals\u003e\n                    \u003cconfiguration\u003e\n                        \u003cextendsClass\u003ecom.fizzed.ninja.rocker.NinjaRockerTemplate\u003c/extendsClass\u003e\n                    \u003c/configuration\u003e\n                \u003c/execution\u003e\n            \u003c/executions\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\nFor more detailed information on Rocker and its maven plugin, please visit the\n[Rocker project](https://github.com/fizzed/rocker) site.\n\n### Exclude rocker templates as a resource\n\nNinja recommends including everything except .java files from \u003ccode\u003esrc/main/java\u003c/code\u003e\nby default.  Since Rocker's templates are compiled, this isn't necessary and you\ncan safely exclude Rocker templates from your final build.\n\n```xml\n\u003cbuild\u003e\n    \u003cresources\u003e\n        \u003cresource\u003e\n            \u003cdirectory\u003esrc/main/java\u003c/directory\u003e\n            \u003cincludes\u003e\n                \u003cinclude\u003e**/*\u003c/include\u003e\n            \u003c/includes\u003e\n            \u003c!-- add rocker template exclude below --\u003e\n            \u003cexcludes\u003e\n                \u003cexclude\u003e**/*.java\u003c/exclude\u003e\n                \u003cexclude\u003e**/*.rocker.html\u003c/exclude\u003e\n            \u003c/excludes\u003e\n        \u003c/resource\u003e\n        \u003cresource\u003e\n            \u003cdirectory\u003esrc/main/resources\u003c/directory\u003e\n            \u003cincludes\u003e\n                \u003cinclude\u003e**/*\u003c/include\u003e\n            \u003c/includes\u003e\n        \u003c/resource\u003e\n    \u003c/resources\u003e\n\u003c/build\u003e\n```\n\n### Exclude rocker compiled templates from triggering Ninja SuperDevMode restart\n\nBy default, Ninja's SuperDevMode watches all .class files in your \u003ccode\u003etarget/classes\u003c/code\u003e\ndirectory.  Any modification to the contents of that directory will trigger the\nNinja HTTP server to restart.  Rocker's templates are compiled and with hot\nreload enabled, Rocker will recompile and reload your templates without requiring\na JVM restart.  Unfortunately, Ninja's defaults will still trigger a restart\nsince Rocker will recompile and change the contents of \u003ccode\u003etarget/classes\u003c/code\u003e.\nAs long as you stick to the convention that any class in the \u003ccode\u003eviews\u003c/code\u003e\npackage is a rocker template, you can exclude these classes:\n\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003eorg.ninjaframework\u003c/groupId\u003e\n            \u003cartifactId\u003eninja-maven-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e6.0.0-beta2\u003c/version\u003e\n            \u003cconfiguration\u003e\n                \u003cuseDefaultExcludes\u003etrue\u003c/useDefaultExcludes\u003e\n                \u003cexcludes\u003e\n                    \u003cexclude\u003e(.*)rocker.html$\u003c/exclude\u003e\n                    \u003cexclude\u003e(.*)views/(.*).class$\u003c/exclude\u003e\n                \u003c/excludes\u003e\n            \u003c/configuration\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n### Write templates\n\nIt's best to place your templates in the `views` folder of your application\nwith a suffix of `.rocker.html`.\n\n## Ninja variable\n\nEasiest way to discover all the properties and methods available in the `N`\nvariable is to take a look at [NinjaRocker.java](https://github.com/fizzed/ninja-rocker/blob/master/module/src/main/java/com/fizzed/ninja/rocker/NinjaRocker.java).\n\n## Application-specific templates\n\nLooking for the ultimate integration of Ninja into your application?  Create your\nown application-specific template that subclasses `NinjaRockerTemplate` and\nexpose any number of useful variables and/or methods to any of your templates.\n\nThe demo has an example of how to do it [here](demo/src/main/java/utils/ApplicationRockerTemplate.java).\n\n### Write your own application-specific template\n\nCreate a new class called `utils.ApplicationRockerTemplate`. This class will\nsubclass `com.fizzed.ninja.rocker.NinjaRockerTemplate` and then it will need to\noverride two methods to participate in the rendering process.\n\n```java\npackage utils;\n\nimport com.fizzed.ninja.rocker.DefaultNinjaRocker;\nimport com.fizzed.ninja.rocker.NinjaRockerTemplate;\nimport com.fizzed.rocker.RockerModel;\nimport com.fizzed.rocker.RockerTemplate;\nimport com.fizzed.rocker.RockerUtils;\n\nabstract public class ApplicationRockerTemplate extends NinjaRockerTemplate {\n\n    public ApplicationRocker A;\n    \n    public ApplicationRockerTemplate(RockerModel model) {\n        super(model);\n    }\n    \n    /**\n     * Apply NinjaRocker to template immediately before rendering. Best place\n     * to setup your own application-specific properties or methods that rely\n     * on Ninja context, router, messages, etc.\n     * @param N The ninja rocker instance\n     */\n    @Override\n    public void __apply(DefaultNinjaRocker N) {\n        super.__apply(N);\n        this.A = new ApplicationRocker(N);\n    }\n\n    /**\n     * Associate this template with another template during the rendering\n     * process.  This occurs when Template A calls or includes Template B.\n     * Usually, you simply want to copy over the variables you created in\n     * the __apply method.\n     * @param template The template to associate us with\n     */\n    @Override\n    protected void __associate(RockerTemplate template) {\n        super.__associate(template);\n        ApplicationRockerTemplate applicationTemplate\n            = RockerUtils.requireTemplateClass(template, ApplicationRockerTemplate.class);\n        this.A = applicationTemplate.A;\n    }\n    \n}\n```\n\n(demo/src/main/java/utils/ApplicationRockerTemplate.java)\n(demo/src/main/java/utils/ApplicationRocker.java)\n\n### Use your own `A` variable\n\nIn this example, we are exposing the `ApplicationRocker` class as a variable\nnamed `A`.  In your template, you can then access it like so\n\n```html\n\u003ch1\u003e@A.user.getName()\u003c/h1\u003e\n```\n\nThe possibilities are obviously endless -- and remember that the Java compiler\nwill check for type safety on everything.\n\n### Your templates need to extend your application-specific template\n\nThere are two ways you can instruct a template to extend a specific superclass.\nFirst, you can do it in the maven plugin:\n\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003ecom.fizzed\u003c/groupId\u003e\n            \u003cartifactId\u003erocker-maven-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e\u003c!-- version here --\u003e\u003c/version\u003e\n            \u003cexecutions\u003e\n                \u003cexecution\u003e\n                    \u003cid\u003egenerate-rocker-templates\u003c/id\u003e\n                    \u003cgoals\u003e\n                        \u003cgoal\u003egenerate\u003c/goal\u003e\n                    \u003c/goals\u003e\n                    \u003cconfiguration\u003e\n                        \u003cextendsClass\u003eutils.ApplicationRockerTemplate\u003c/extendsClass\u003e\n                    \u003c/configuration\u003e\n                \u003c/execution\u003e\n            \u003c/executions\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\nAlternatively, your template can set an option for itself\n\n```html\n@option extendsClass=utils.ApplicationRockerTemplate\n\n@args (String title)\n\n\u003ch1\u003e@title\u003c/h1\u003e\n```\n\n## Common issues\n\nIf your Ninja project compiles and runs, but you get a runtime error like this:\n\n    ERROR c.f.n.rocker.TemplateEngineRocker - Unable to handle renderable not of type: class views.ApplicationController.helloWorld\n\nYou likely forgot to configure your rocker maven plugin to \"extendsClass\" from\ncode\u003ecom.fizzed.ninja.rocker.NinjaRockerTemplate\u003c/code\u003e. See below for more info.\n\nIf your project won't compile and you see compiler warnings like:\n\n    [ERROR] /fizzed/java-ninja-rocker/demo/target/generated-sources/rocker/views/ninja.java:[162,65] cannot find symbol\n    [ERROR] symbol:   variable N\n\nYou most likely did not configure your rocker maven plugin to extend templates\nfrom \u003ccode\u003ecom.fizzed.ninja.rocker.NinjaRockerTemplate\u003c/code\u003e rather than the\ndefault of \u003ccode\u003ecom.fizzed.rocker.runtime.DefaultRockerTemplate\u003c/code\u003e.  The \"N\"\nvariable is defined in \u003ccode\u003ecom.fizzed.ninja.rocker.NinjaRockerTemplate\u003c/code\u003e.\n\nThe configuration section for your rocker plugin for maven should look like this:\n\n## License\n\nCopyright (C) 2016 Fizzed, Inc.\n\nThis work is licensed under the Apache License, Version 2.0. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffizzed%2Fninja-rocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffizzed%2Fninja-rocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffizzed%2Fninja-rocker/lists"}