Welcome to autumo enterprise products.
Download. Try. Build fast. Grow solid.

Welcome to beetRoot.




Logo

autumo beetRoot

A slim & rapid Java web-dev framework
Report Bug · Request Feature


Table of Contents

  1. What is beetRoot ?
  2. Distributions
  3. Running Modes
  4. Running
  5. Configuration and Passwords
  6. Default Database and Schema
  7. CRUD Generator PLANT
  8. Standard HTML Templates
  9. Routing
  10. Logging
  11. Mailing
  12. Mail Templates
  13. Java Translations
  14. Webapp Design and Javascript
  15. HTTPS
  16. Roadmap | Backlog
  17. License
  18. Contact
  19. Acknowledgments

What is beetRoot ?

autumo beetroot screen

beetRoot is a rapid Java web-development framework ready to run! If you know CakePHP (cakePHP.org), you'll like beetRoot. It is based on the same principles and comes with a full CRUD generator generating all views, the model specification and controllers (handlers in beetRoot's terminology) based on the database model!

It is shipped with the following features ready to use:

Enjoy!

Built With


Distributions

  1. autumo-beetRoot-x.y.z.zip: Stand-alone server version with all files for every distribution.
  2. autumo-beetRoot-web-x.y.z.zip: General web-app version.
  3. beetroot.war: Tomcat version.
  4. beetroot-jetty.war: Jetty version.

Distributions are available here: Releases - they can be generated with the make shell-script `make.sh` too.

Running Modes

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

beetRoot can be run within two modes:

  1. Stand-alone web-server, based on a partially patched version of NanoHTTP and RouterNanoHTTPD (https://nanohttpd.org); the specific versions are:

    • NanoHTTP a.b.c-SNAPHOT, which is distributed by autumo GmbH through the library nanohattpd-a.b.c-BEETROOT.jar

    • RouterNanoHTTPD a.b.c-SNAPHOT, patched within autumo-beetroot-x.y.z.jar

  2. Within a servlet container such as tomcat or jetty.


Running

  1. Stand-alone usage:
    • beetRoot.sh start / beetRoot.bat start

      See shell-script if you need special modifications. The stand-alone beetRoot web-server reads the configuration cfg/beetroot.cfg. Most configuration parameters are used for servlet-container operation too. All Configuration parameters are explained in the configuration file itself.

    • Surf to http://localhost:8778 (8778 is the default port for the stand-alone server).

    • The stand-alone server with its resources is packed into autumo-beetRoot-x.y.z.zip.

    • Use beetRoot.sh stop / beetRoot.bat stop to properly stop the stand-alone server.

  1. Servlet-container:

    Throw beetroot.war into tomcat webapps/ and throw beetroot-jetty.war into jetty's webapps/ folder. Fire it up and surf to http://localhost:8080/beetroot. Configure your containers as you wish. We recommend running the beetroot webapp extracted, so any change on the HTML templates and the model configuration (columns.cfg for each entity) can be made on-the-fly.

If you want to keep everything under control use the archive autumo-beetRoot-web-x.y.z.zip.


Configuration and Passwords

Have a look at cfg/beetroot.cfg. Every configuration parameter is explained. You can run beetRoot with ALL passwords encoded if you wish. You can define, if passwords used in the configuration file should be encoded. The same for passwords stored in the beetRoot-database-table users.

There are two configuration variables for this: admin_pw_encoded & db_pw_encoded (yes/no).

For security reasons, you should change the secret key seed (secret_key_seed) in the beginning and then generate new passwords with the tool pwencoder.sh/pwencoder.bat. If you do, you have to change the initial encoded password for the beetRoot admin user in the database to gain access again!

NOTE: All passwords are beetroot in the beginning!

Furthermore, the configuration offers wide possibilities of customization for your app, such as:


Default Database and Schema

Every beetRoot package (stand-alone & web-apps) come with a < a href="https://h2database.com">H2 database filled with sample data and the configuration points to this database. If you want to connect to your own database, simply change the connections parameters in the configuration.

To setup a new database scheme use the SQL-Script db/install_beetroot.sql and customize it to your needs and database.

A word when using MySQL: Due to the GPL license, we don't distribute or create a dependency to the MySQL Connector for Java. Visit Oracle MySQL website and download it yourself if you want to use this connector. Note that the MariaAB connector for Java works also for MySQL databases up to the version 5.5 of MySQL or even for higher versions! Also have a look here for further valuable information in this context: [MariaDB License FAQ] (https://mariadb.com/kb/en/licensing-faq).


CRUD Generator PLANT

Start the CRUD generator with the script plant.sh / plant.bat and follow the steps!

The generator reads the entities in the database that is configured in cfg/beetroot.cfg, from which you can choose one or all!

NOTE: Entities for beetRoot MUST be named in plural form in the database, e.g.: tasks, users, cities, properties, cars, etc.

In the Generated HTMLs the following standard transformation takes place:

  • tasks -> task (singular)
  • properties -> property (singular)

Hence, we suggest you use English names for your database entities, even you can adjust the named versions in the generated HTMLs of course and which is even necessary if you copy the templates for other languages.

It generates the following sources:

HTML templates & model configuration (columns.cfg):

  • web/html/{entity-plural-name}/add.html
  • web/html/{entity-plural-name}/edit.html
  • web/html/{entity-plural-name}/view.html
  • web/html/{entity-plural-name}/index.html
  • web/html/{entity-plural-name}/columns.cfg

Java sources (handlers):

  • src/planted/beetroot/handler/{entity-plural-name}/{Entity-plural-name}AddHandler.java
  • src/planted/beetroot/handler/{entity-plural-name}/{Entity-plural-name}EditHandler.java
  • src/planted/beetroot/handler/{entity-plural-name}/{Entity-plural-name}ViewHandler.java
  • src/planted/beetroot/handler/{entity-plural-name}/{Entity-plural-name}IndexHandler.java
  • src/planted/beetroot/handler/{entity-plural-name}/{Entity-plural-name}DeleteHandler.java

Adjust them to your needs (see existing handlers for examples) and more IMPORTANT: Move the Java sources to another package! All generated files are overwritten the next time if you re-generate sources for the same entity!

The HTML templates & model configuration are usually moved/copied to a language sub-directory:

  • web/html/en/{entity-plural-name}/*.html|columns.cfg
  • web/html/de/{entity-plural-name}/*.html|columns.cfg
  • web/html/fr/{entity-plural-name}/*.html|columns.cfg
  • etc.

We suggest to keep your original generated HTML templates and model configuration, they serve as a fallback scenario when the user request a language that is not present!

The model configuration columns.cfg does the following for every entity:

  • It defines what columns you see for every view (add, edit, view/single-record, index/list). See existing files for sample entities Task and/or User.

  • It also defines which columns are UNIQUE in the database by defining them with the key unique, e.g.:

    unique=name, path

  • Furthermore, you can define transient values that are nor read from or stored to database nor they are loaded within a bean, they are just delievered within the handler methods, so another value can be served for these transient columns/fields, e.g.:

    transient=status

Your TODO's are the following after generating:

  • Adjust mandatory fields in java add handler: only the mandatory fields need a default value in the add handler that are not present in the GUI!

  • Remove unwanted GUI fields from columns.cfg for the views view, add and edit.

  • Also Remove unwanted <col span..> tags in the index.html; e.g. if you removed standard fields id, created and modified from columns.cfg.

  • Add entity to menu or admin menu and overwrite hasAccess-method for every handler if necessary.

NOTE: PLANT uses its own templates stored within the gen/-directory. Of course, you can even adjust these templates next to the block-templates, so they have the structure you want to have for your own web-app.


Standard HTML Templates

The following standard HTML templates are present, which can be customized too of course:

  1. web/html/blocks/*.html:

    • Defines the layout of the page with its general elements such as head, header, menu admin menu, language menu, message block and script section (javascript).

    • They can be copied to other language directories too (e.g. web/html/blocks/en/*.html), if they need to be language specific, which in most cases, is not necessary. They also serve as fallback templates, if the user requested a language that isn't found respectively the web-app is not yet translated into that language.

    • NOTE: Here, as well as with the generated HTML templates, the lookup algorithm is: a) First, lookup templates in requested language directory (2-letter ISO code) b) If not found, try the default language; this is the one that is first defined in the configuration, see parameter web_languages. c) If still not found, use the templates by omitting the language code, respectively the language directory in the web/html-directory structure.

NOTE: Valid for templates and any other HTMLs file that are added to the web/html-directory structure:

The following template variables are always parsed and you can use them as many times as you want:


Routing

The router defines which resources are served by the requested URL of a web-app user. The out-of-box router is the BeetRootDefaultRouter.java. In any case, it always should be replaced for your own app. The define your router's java class in the web_router parameter. You simply have to implement the Router interface.

Let's have a look at some routes:

/** Home stuff */
new Route("/:lang/home", HomeHandler.class, "home"),
new Route("/:lang/home/index", HomeHandler.class, "home"),

/** Files */
new Route("/:lang/files/view", ExampleDownloadHandler.class, "files"),
new Route("/:lang/files/add", ExampleUploadHandler.class, "files"),

/** Tasks */
new Route("/:lang/tasks", TasksIndexHandler.class, "tasks"),
new Route("/:lang/tasks/index", TasksIndexHandler.class, "tasks"),
new Route("/:lang/tasks/view", TasksViewHandler.class, "tasks"),
new Route("/:lang/tasks/edit", TasksEditHandler.class, "tasks"),
new Route("/:lang/tasks/add", TasksAddHandler.class, "tasks"),
new Route("/:lang/tasks/delete", TasksDeleteHandler.class, "tasks")

The requested URL's are translated to generated (or self-created) handlers which always must implement the method:

public  String getResource();

For generated handlers (with the CRUD generator) this is usually not necessary, because they have a standard implementation:

@Override
public  String getResource() {
    return "web/html/:lang/"+entity+"/index.html";
}

If your handlers need customization, just overwrite this method. As you can see, here the translation of the requested URL takes place and points to the 'web/html'-directory structure!

The language is replaced by the requested language, and if not found the above algorithm is executed. The 'entity' name is assigned through the construction of the handler (see route examples above). That's it, more or less!

NOTE: You never have to reference the servlet-name within any request URL not in the router, not even in your HTML templates when running beetRoot in a servlet container. Just specify the configuration parameter 'web_html_ref_pre_url_part'.

For example ('beetroot' is the default servlet name/url):

beetRoot handles every pre-url-path / servlet-name-path by its own, if configured correctly!

IMPORTANT: If you run beetRoot as a stand-alone server or in a servlet container, where beetRoot is installed on the ROOT path, NEVER specify the parameter web_html_ref_pre_url_part!
When you define a HTML a-tag (e.g. <a href="/{$lang}/tasks/index"....>) or an image source or any other source (e.g. <img src="/img/beetroot-100.png">), you always point to the root-path "/". Tough, you have to include the language placeholder :lang for HTML templates always.


Logging

beetRoot uses SLF4j. For the stand-alone and tomcat wep-app version, the log4j2 implementation (the one that has NOT the log4j2 bug in it...!) is used and the default configuration cfg/logging.xml (stand-alone) and logging.xml (in tomcat web-app servlet directory) is used. If you want to specify your own, adjust it this way:

As for jetty, they stand above all that "log-framework-soup" and they just simply use a SLF4j implementation that needs no further configuration. Hence, the library slf4j.simple-x.y.z.jar is packed into beetroot-jetty.war. The only concern is to add your package to the the jetty basic logging configuration in {JETTY_BASE}/resources/jetty-logging.properties:

## Configure a level for specific logger
ch.autumo.beetroot.LEVEL=INFO

NOTE: All logging levels are set to INFO in the beginning!


Mailing

NOTE: Due to the licenses, we don't distribute or create a dependency to Java Mail implementations behind the Jakarta Mail and Activation API. You have to download them by yourself e.g. through maven-dependencies or here: Eclipse Jakarta Mail). You basically need to add the libraries jakarta.activation-x.y.z.jar and jakarta.mail-x.y.z.jar.


Mail Templates

Mail templates are here and follow the same lookup-patterns as for HTML templates:

HTML format:

Text format:

beetRoot can send both HTML and text emails. Formats are configured with the parameter mail_formats.

NOTE: Java mail doesn't allow sending HTML with a head nor body-tag, hence you only are able to define HTNML templates with tags that would be inside of a the body-tag. It is specification!


Java Translations

If you need translations within the Java code, you simply add language java resource bundle keys within the web/lang directory to the specific language resource bundle, e.g. lang_en.properties. You can change beetRoot's standard messages too. For every new language added respectively requested by the web-app user, add the corresponding language java resource bundle within this directory.


Webapp Design and Javascript

All you need for this, is located here:

These resources are straightly routed by the user's URL request, e.g.:

Also, in this case, you never have to reference a servlet name in any HTML template, you always point to teh root-path "/", no matter what!

A few words about existing stylesheets:


HTTPS

If you run beetRoot as a stand-alone server and you want to run it with the HTTPS protocol, there's a prepared and self-signed keystore file: ssl/beetroot.jks that is valid forever.

If you configure beetRoot to run with the HTTPS protocol (configuration parameter ws_https), you can use this keystore file and it is specified by default in the configuration (ws_ks). Your browser will still complain, because it is not issued by a valid Certificate Authority (CA), but you can force the browser to still load the web-app by adding this exception. If you run beetRoot in productive mode, you have to acquire a valid certificate and store it this keystore or in a an own; Java supports the PKCS#12 format and Java keystore can be opened with tools such as this one: https://keystore-explorer.org. The password for ssl/beetroot.jks is beetroot.


Roadmap | Backlog

See also the open issues for a full list of proposed features (and known issues).


License

Distributed under the BSD 3-Clause-License.


Contact

autumo Switzerland - @autumo - autumo.switzerland@gmail.com

Project Link: https://github.com/autumoswitzerland/autumo/tree/master/autumo-beetroot


Acknowledgments


Donate

Your donation helps to develop autumo beetRoot further. Thank you!





( back to top )




Contact | © autumo GmbH

Accept
This website is using cookies. More details