Module admin_experience 

Admin Experience of lib-humus

This document is mainly an implementation guide, but also tries to be a bare minimum guide for admins who come across a lib-humus application.

What is admin experience?

You may know User Experience which makes things more enjoyable and consistent for users. When writing rust code you may also know Developer Experience which makes things more enjoyable and consistent on the development side. Admin Experience is … making things more enjoyable and consistent for Admins.

Since lib-humus is a non trivial and configurable frontend part it not only interacts with application developers, but also with their administrators, this guide makes sure that admins have a consistent experience when interacting with an application that builds on lib-humus.

Logging

lib-humus uses the log crate to communicate errors and warnings, if no other logging sytem in planned please set up an env_logger. Its verbosity can be controlled through the RUST_LOG environment variable.

You should do this as the first thing in your main function (even before parsing cli args):

// Initalize logger:
env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();

Command line options

lib-humus needs some options that should be easily settable from the outside. For (sub)commands that spawn a server process that uses lib humus please add the following options:

• --listen-on <socket_addr> parse this as a SocketAddr and open your server socket on.
• --template-location <path>, allows overriding the default template location. Pass it to HumusEngineLoader::cli_template_location.
• --static-location <path>, when set it should override path where static files are served from.
• --extra-config <path>, allows overriding the default path ot the extra.toml template configuration. Pass it to HumusEngineLoader::cli_extra_config_location.

Use a PathBuf when reading file paths.

Static files

The directory static/ in the template directory is reserved for static files so that no reverse proxy is needed to serve static content by default.

The command line option --static-location <path> must ovveride this path.

As a developer do not assume that your application is in control of serving static files, the administrator should be able to point their webserver at the static content and have it just work!

Provide robots.txt with some good defaults.

Example snippet of how serving the static directory could be implemented using tower_http::services::ServeDir:

let static_file_directory = args.static_location
	.unwrap_or(humus_engine_loader.base_dir().join("/static"));
log::info!("Static files will be served from: {static_file_directory:?}");

let app = Router::new()
	/* put your routes here */
	.fallback_service(
		ServeDir::new(static_file_directory)
			.fallback(your_not_found_handler),
	)

Provide documentation

Even though lib-humus takes care of a lot of frontend work please document the following:

• Parameters for the reverse proxy:
  • A restrictive content security policy that can be applied in a reverse proxy. (Keep in mind that browsers have special treatment for localhost when testing)
  • Should cache headers be set, if yes what makes sense on which paths.
• Templating parameters:
  • Which API formats do you provide? (The JsonOnlyApiFormat only provides the json format)
  • Which views are available and what do they provide in the data variable.
  • Additional variables you are setting in HumusView::initalize_template_context.
  • Additional functions you’ve made available to the template.
  • Additional functionality you’ve registred with the fluent templates in the language engine.
• What do your default templates expect in the extra.toml file? (The easiest way to do this is to put comments in your default extra.toml)