We provide UCW IoT Cloud where you can run multiple instances of the UCW Platform for needs of your projects. You can start by registering here and get access to the IoT platform with unique functionality. To learn more check out the UCW Platform overview.


Tutorial overview

This is "Hello world" tutorial of a UCW portal add-on. Throughout the tutorial, you will learn how to create a portal application, understand the basic structure of an add-on (plugin), learn how to add links to the main navigation menu of UCW Portal using section and section items and create a simple controller. See source code.

Requirements 

Step 01: Download tutorial sources

In order to download tutorial sources and test their functionality, do as follows:

  1. Make sure you have downloaded all the requirements.
  2. Open a terminal/console and navigate to your working directory.

  3. Download the sources using the following command:

    git clone https://github.com/unitycloudware/ucw-portal-helloworld.git ucw-portal-helloworld

  4. Move into newly create a folder

    cd ucw-portal-helloworld

  5. Checkout to a starting point of the tutorial

    git checkout start

    Note

    In the tutorial, you will be working in "start" branch. However, at any moment of the tutorial, you can checkout into "master" branch to see correct solution.

  6. Test downloaded files by building and running the sources using following commands

    Unix / Linux based OS
    ./build.sh
./run-portal.sh

    or

    Windows
    build.bat
run-portal.bat

  7. The application should be up and running on http://localhost:9570. After clicking the link, you should see a login page.

  8. Log into the application using default credentials (User: admin, Password: admin) and admin page should be displayed.


You just setted essential environment for developing your first plugin.

As you can see, there is a lot of stuff that has been already created. All of it has been created using UCW Template Module. If you have not familiarised with it yet, please see its documentation for more information.

Step 02: Change redirect path

In the previous step, you could notice that after login you have been redirected to the admin page. That is usually not the behaviour you want. In general, you want to redirect a user to your plugin page directly. Do as follows to change it

  1. Go to HelloWorldPlugin.java file 
  2. Change value of PORTAL_REDIRECT_DEFAULT variable to "/ucw-helloworld".

That's it. From now on whenever you access default application URL, you will be redirected to ucw-helloworld page. 

Step 03: Add controller

If you build and run the application 404 status error page will be shown after login. This is because you did not specify yet what to render. Following steps will help you with it:

  1. Since we are using Spring Controller annotations to create controllers, check if the base-package parameter of component-scan is set correctly. See applicationContext.xml file and verify that base-package points to "com.unitycloudware.portal.tutorial.helloworld". See Spring documentation for more information component-scan, controllers or another Spring related issues.
  2. Create HelloWorldController class in controller package
  3. Make HelloWorldController extend AbstractPortalController
  4. Add @Controller annotation 
  5. Add @RequestMapping annotations with "/ucw-helloworld" value

  6. Paste following code into the controller

    @RequestMapping(method = RequestMethod.GET)
public ModelAndView showPage(final HttpServletRequest request, final HttpServletResponse response) {
    Map<String, Object> context = new HashMap<>();
    return render("/templates/helloworld-page.vm", context, request, response);
}

Step 04: Add velocity template

Creating the controller is just the first step on the way. The second one is to create velocity template which will be used by the render function.

  1. Create helloworld-page.vm file inside "resources/templates" folder 
  2. Write "Greetings from UCW Hello World!" in it

Now you can build and run the application again. See the result 


Congratulations! You just created your first plugin. You can follow next steps to see how to use some features of our platform.

Step 05: Add page header

AbstractPortalController provides an option to render header above the content of the page. Let's do it by adding following lines into the showPage function in HelloWorldController

setDisplayName("UCW Hello World");
setHeaderDisplayable(true);

The result should look as follows 

The header is the simplest version which you can create. There is also support for more complex headers which can include an image or action buttons. See Step 06 or Step 07.

Step 06: Add page header logo

AbstractPortalController provides a method showHeader which takes three input parameters. To add a logo, we will need to set the first one. Do as follows:

  1. Save an image into "resources/images" folder

  2. Paste following code into the showPage function in the controller (see Step 03)

    String imageUri = getResourceUrl("/resources/images/ucw_logo.png", request);
showHeader(imageUri, null, null);

  3. Build and run the application

Step 07: Add page header action buttons

To add action buttons, we will use showHeader function again. This time the second parameter needs to be set. Do as follows: 

  1. Open nsys-plugin.xml

  2. Define button section

    <navigation-section key="ucw-helloworld_helloworld-header-actions" name="UCW Hello World Header Actions" location="ucw.tutorial.helloworld.header.actions" weight="0">
    <label>Hello World Header Actions</label>
</navigation-section>

  3. Define button Example Button Hello World

    <navigation-item key="ucw-helloworld_helloworld-header-actions_mgmt" name="UCW Hello World" section="ucw.tutorial.helloworld.header.actions" weight="0">
    <label>Show Hello World</label>
    <link>/ucw-helloworld</link>
</navigation-item>

    Note

    See Navigation Section / Navigation Item Plugin Module page for more information about navigation-section and navigation-item components

  4. Open the controller again and change the second attribute of showHeader function to "ucw.tutorial.helloworld.header.actions". 

    showHeader(imageUri, "ucw.tutorial.helloworld.header.actions", null);

    Note

    Note that the value of the second parameter is same as location attribute of navigation-section defined in nsys-plugin.xml

  5. Build and run the application

Step 08: Add plugin to top navigation menu

Users may find useful if your plugin could be quickly accessible from the top navigation menu. To do so, you need to modify nsys-plugin.xml again. Do as follows:

  1. Add a new navigation section in the main menu. To do so paste the following snippet into nsys-plugin.xml.

    <navigation-section key="ucw-portal-tutorial_nav-main_demo" name="UCW Demo" location="system.top.navigation.bar/ucw.demo" weight="1000">
    <label>UCW Demo</label>
    <description>UCW Demo Examples</description>
</navigation-section>

  2. Let's add new navigation item so that you can redirect a user to the UCW Hello World controller. Paste the following into the nsys-plugin.xml

    <navigation-item key="ucw-helloworld_nav-main_helloworld" name="UCW Hello World" section="system.top.navigation.bar/ucw.demo" weight="0">
    <label>UCW Hello World</label>
    <link>/ucw-helloworld</link>
    <conditions>
        <condition class="org.nsys.portal.conditions.UserIsLoggedInCondition" />
    </conditions>
</navigation-item>

  3. Build and run the application

Step 09: Velocity parameters

Apache velocity templates allow you to create dynamic content in the templates (see documentation). Our platform allows you to use this feature as well. Just put your variables into context variable created in showPage function. Let's demonstrate it by doing following changes:

  1. Change content of helloworld-page.vm to "<p>$!{msg}</p>"

  2. Paste following lines after initialisation of context map in the HelloWorldController

    String msg = "Greetings from UCW Hello World!";
context.put("msg", msg);

  3. Build and run the application. You should not see any change after login. Message variable in velocity template is filled in by the value from context.


That's it. Do not forget that you can check our implementation of all the previous steps in the master branch. To do so either checkout in the branch or check it out on the web.

Summary

During this tutorial you have learnt how to:

  1. Use UCW Template Module
  2. Add basic Controller
  3. Add basic Velocity template and set velocity variables
  4. Customize page header
  5. Customize navigation menu