@informaticon/base-assets

lib.npm.base.template

This package contains everything frontend-related of our informaticon template. This package is published to npm as @information/base-assets.

Prerequisites

Your project is already prepared to use npm packages, and you already have a bundler like Webpack, Rollup, or something similar set up.

If you are unsure on how to set that up in a Play! project, check out the internal Using Webpack with Play! Framework guide.

Usage

Install the package via npm

npm i @informaticon/base-assets -D

Import the template in your Loader

import { Template } from "@informaticon/base-assets";

// optional
declare global {
    interface Window {
        template: Template
    }
}

export class Loader {
    constructor() {
        /**
         * If you create an instance of the 'Template' class 
         * and 'initializeComponents' is set to true, then 
         * all Template-related elements in your HTML will 
         * automatically be registered and made available 
         * on the 'Template' object you created.
         * 
         * BEWARE: The elements are registered AFTER the 
         * 'DOMContentLoaded' event.
         */
        window.template = new Template({initializeComponents: true});
    }
}

Import the stylesheets of the template in your Sass file

@import "~@informaticon/base-assets/dist/template.css";

💡 Importing scss instead of compiled css
You can also import the source SCSS code instead of the compiled CSS:

@import "~@informaticon/base-assets/src/stylesheets/main";

It's recommended to use the compiled CSS and the CSS3 variables instead of the SCSS source though.

Use components from the template (Optional)

import { InfConfirm } from "@informaticon/base-assets";

// show a new notification
const notification: InfNotification = InfNotification.showInfo("hello world!");

// If you enabled "initializeComponents", most components present 
// on the page are registered automatically, you can access them via the
// template object.
//
// Components that are identified by a specific name are provided
// in a Map<> structure where you can access the specific item,
// other components are simply returned as an array of components.
window.template.confirms.get("my-confirm").show();

Contribution

Make sure your system meets the following requirements when contributing to this project.

Requirements

Rollup installed

npm install --global rollup

Commands

Build the project

npm run build

Watch the project and re-build immediately when changes are made

npm run watch

Test with lib.play.base.template

As you may have realized, this project only contains scss and typescript files. The HTML views are not (yet?) part of this project because they are (still) written in Twirl.

If you want to add new components or modify existing ones, you'll probably want to see how your changes actually look.

1. Checkout the lib.play.base.template project on your computer

2. Make sure that the directories for this project and the lib.play.base.template are siblings in the same parent directory.

3. Run this project with npm run watch so your changes are compiled immediately

4. Open lib.play.base.template in IntelliJ and start it as a Play! application.

5. You can import your local build of the scss and typescript bundles by importing them as follows:

   // for development purposes, don't commit this
   @import "../../../../../../../../../lib.npm.base.template/dist/template.css";

   // for development purposes, don't commit this
   import {ConfirmResult, InfNotification, Template} from "../../../../../../../../../lib.npm.base.template/dist/template"

6. Now you can open the Play! Application and you will see our example page with the Template components rendered. If you make changes in the scss and typescript files of the npm package, the bundle in the Play! application will automatically be re-compiled. Refresh the page for the changes to appear.

7. When you are done, make sure that you change the imports back to the ones you'd use in production:

   // in production
   @import "~@informaticon/base-assets/dist/template.css";

   // in production
   import {ConfirmResult, InfNotification, Template} from "@informaticon/base-assets";