Main menu configuration - fieldenms/tg GitHub Wiki

This is an overview how to create and customize main menu for TG-based application.

WebUiConfig is the place where the main menu is configured by specifying modules, providing their layout, customising module menu, registering centres and masters.

At the initial stage of any project, generated using Archetype, there is only one User / Personnel module with few items included. WebUiConfig.initConfiguration is the exact place where all magic happens. Let's have a closer look:

 @Override
    public void initConfiguration() {
        super.initConfiguration();

        final IWebUiBuilder builder = configApp();
        builder.setDateFormat("DD/MM/YYYY").setTimeFormat("HH:mm").setTimeWithMillisFormat("HH:mm:ss")
        // Minimum tablet width defines the boundary below which mobile layout takes place.
        // For example for Xiaomi Redmi 4x has official screen size of 1280x640,
        // still its viewport sizes is twice lesser: 640 in landscape orientation and 360 in portrait orientation.
        // When calculating reasonable transition tablet->mobile we need to consider "real" viewport sizes instead of physical pixel sizes (http://viewportsizes.com).
        .setMinTabletWidth(600);

        // Personnel
        final PersonWebUiConfig personWebUiConfig = PersonWebUiConfig.register(injector(), builder);
        final UserWebUiConfig userWebUiConfig = new UserWebUiConfig(injector());
        final UserRoleWebUiConfig userRoleWebUiConfig = new UserRoleWebUiConfig(injector());

        // Configure application web resources such as masters and centres
        configApp()
        .addMaster(userWebUiConfig.master)
        .addMaster(userWebUiConfig.rolesUpdater)
        .addMaster(userRoleWebUiConfig.master)
        .addMaster(userRoleWebUiConfig.tokensUpdater)
        // user/personnel module
        .addCentre(userWebUiConfig.centre)
        .addCentre(userRoleWebUiConfig.centre);


        ...

As first step it is required to register specific WebUiConfig for every entity type to be able to call its centre/master during menu configuration. There are two ways how to achieve this. In the example above

final PersonWebUiConfig personWebUiConfig = PersonWebUiConfig.register(injector(), builder);

one line of code will register all centres and masters that were created in PersonWebUiConfig.

In case of UserWebUiConfig and UserRoleWebUiConfig different approach is used: first registration is taking place and after that all masters and centres are added one by one.

Next step is to configure application menu and specify all menu items:

        ...
        
        // Configure application menu
        configDesktopMainMenu().
            addModule("Users / Personnel").
                description("Provides functionality for managing application security and personnel data.").
                icon("mainMenu:help").
                detailIcon("mainMenu:help").
                bgColor("#FFE680").
                captionBgColor("#FFD42A").menu()
                .addMenuItem("Personnel").description("Personnel related data")
                    .addMenuItem("Personnel").description("Personnel Centre").centre(personWebUiConfig.centre).done()
                .done()
                .addMenuItem("Users").description("Users related data")
                    .addMenuItem("Users").description("User centre").centre(userWebUiConfig.centre).done()
                    .addMenuItem("User Roles").description("User roles centre").centre(userRoleWebUiConfig.centre).done()
                .done()
            .done().done()
        ...
    }

After that we can add all required modules in the similar way.

When all modules and menu items are included it is required to specify layouts. The following layout will have only one row and one column as there is only one module.

        ...
       
        .setLayoutFor(Device.DESKTOP, null, "[[](/fieldenms/tg/wiki/[)]")
        .setLayoutFor(Device.TABLET, null, "[[](/fieldenms/tg/wiki/[)]")
        .setLayoutFor(Device.MOBILE, null, "[[](/fieldenms/tg/wiki/[)]")
        .minCellWidth(100).minCellHeight(148).done();
    }

Let's create layout configuration for four modules. If we simply want to have two rows and two column we can configure menu as following:

        ...
       
        .setLayoutFor(Device.DESKTOP, null, "[[], [](/fieldenms/tg/wiki/[],-[), [], [](/fieldenms/tg/wiki/],-[)]")
        .setLayoutFor(Device.TABLET, null, "[[], [](/fieldenms/tg/wiki/[],-[), [], [](/fieldenms/tg/wiki/],-[)]")
        .setLayoutFor(Device.MOBILE, null, "[[](/fieldenms/tg/wiki/[), [](/fieldenms/tg/wiki/), [](/fieldenms/tg/wiki/), [](/fieldenms/tg/wiki/)]")
    }

This is how it will look: menu_wiki_images/1.png

Let's try some more complex layout, for example:

        ...
       
        .setLayoutFor(Device.DESKTOP, null, "[[{\"rowspan\": 2,\"colspan\": 2}], [{\"colspan\": 2}](/fieldenms/tg/wiki/[{\"rowspan\":-2,\"colspan\":-2}],-[{\"colspan\":-2}),[], [](/fieldenms/tg/wiki/],-[)]")
        .setLayoutFor(Device.TABLET, null, "[[], [](/fieldenms/tg/wiki/[],-[), [], [](/fieldenms/tg/wiki/],-[)]")
        .setLayoutFor(Device.MOBILE, null, "[[](/fieldenms/tg/wiki/[), [](/fieldenms/tg/wiki/), [](/fieldenms/tg/wiki/), [](/fieldenms/tg/wiki/)]")
    }

the result will look like this: menu_wiki_images/2.png