search

qbicsoftware-archive / portlet-template

This repository provides a template for a QBiC Liferay Vaadin Portlet based on Maven.
1 stars 1 forks source link
portlet

readme

Template for QBiC Portlets

This project is no longer maintained. Please visit: https://github.com/qbicsoftware/cookiecutter-templates-cli

Build StatusCode Coverage

Table of Contents

Motivation

There is a lot of boilerplate code associated to building Vaadin portlets for Liferay portals, so it makes sense to automate their creation. This repository provides a cookiecutter template for a basic QBiC Liferay Vaadin Portlet based on Maven. Whenever you start a new Vaadin portlet in QBiC, you should use this template to generate a folder containing all of the needed files for development.

Requirements

You will need the following:

Usage

Generating a basic QBiC Portlet

Execute the following command on your terminal:

cookiecutter https://github.com/qbicsoftware/portlet-template

You will first notice that you are prompted to enter some values, as seen here:

author [Winnie the Pooh]: Homer Simpson
email [pooh@qbic.uni-tuebingen.de]: simpson@burns.com
artifact_id [helloworld-portlet]: donut-portlet
display_name [HelloWorld Portlet]: Donut Portlet
version [0.0.1-SNAPSHOT]:
short_description [Simple portlet]: Mmm donuts
main_ui [QBiCPortletUI]: DonutPortletUI
copyright_holder [QBiC]: Mr. Burns
Select use_openbis:
1 - yes
2 - no
Choose from 1, 2 [1]: 1
Select use_qbic_databases:
1 - yes
2 - no
Choose from 1, 2 [1]: 1

The values shown between brackets are the defaults. To use the default value (as Winnie did here for most values), simply press ENTER without entering any other text. Default values are provided in cookiecutter.json. In any case, make sure to consult our naming and versioning conventions guide.

Cookiecutter will generate a folder which you can use for portlet development. References to cookiecutter variables (e.g., {{ cookiecutter.version }}) will be properly replaced and resolved. The name of the generated folder is determined by the value of the {{ cookiecutter.artifact_id }} variable (i.e., donut-portlet in our example). This will be generated on the same folder on which you executed the cookiecutter command:

donut-portlet/
├── CODE_OF_CONDUCT.md
├── LICENSE
├── pom.xml
├── README.md
└── src
    ├── main
    │   ├── java
    │   │   └── life
    │   │       └── qbic
    │   │           └── portal
    │   │               └── portlet
    │   │                   └── DonutPortletUI.java
    │   ├── resources
    │   │   ├── life
    │   │   │   └── qbic
    │   │   │       └── portlet
    │   │   │           └── AppWidgetSet.gwt.xml
    │   │   ├── log4j2.xml
    │   │   └── portlet.properties
    │   └── webapp
    │       ├── VAADIN
    │       │   └── themes
    │       │       └── mytheme
    │       │           ├── addons.scss
    │       │           ├── mytheme.scss
    │       │           ├── styles.css
    │       │           └── styles.scss
    │       └── WEB-INF
    │           ├── liferay-display.xml
    │           ├── liferay-plugin-package.properties
    │           ├── liferay-portlet.xml
    │           ├── portlet.xml
    │           └── web.xml
    └── test
        └── java
            └── life
                └── qbic
                    └── portal
                        └── portlet
                            └── DonutPortletUITest.java

Post "portlet-creation" tasks

Write tests, check code coverage

The generated folder already contains a simple jUnit test (i.e., in src/test/java/life/qbic/portal/portlet/DonutPortletUITest.java). Writing code that tests your code is an important part of the development lifecycle (see: https://makeameme.org/meme/Yo-dawg-I-wgn8jg).

As a general guideline, try to code the logic of your portlet independent of the user interface so you can easily write code that tests your portlet.

Maven has been configured to execute unit tests under the src/test folder that match the *Test name (e.g., DonutPortletUITest). To locally run the unit tests and generate a code coverage report, use the following maven command:

mvn cobertura:cobertura

Similarly, we have configured the Maven plug-ins to run integration tests. These tests are also under the src/test folder, but their names must end with *IntegrationTest, such as DonutPortletUIIntegrationTest.

Test your portlet locally

Go to the generated folder (i.e., donut-portlet in our case) and run:

mvn jetty:run

You should see an output similar to:

[INFO] Started ServerConnector@67c06a9e{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
[INFO] Started @30116ms
[INFO] Started Jetty Server

Direct your browser to localhost:8080. If everything went fine, you will see a portlet with several controls. So far so good, congratulations!

Interact with the UI and, if this is your first portlet, we strongly suggest you to try to change a few things in the code and see what happens after you test again.

Create a new GitHub repository for your new portlet

You now have a simple QBiC portlet with all the required dependencies. You still need to create a remote repository for it, though, so it's available for everyone. Follow this guide to create a repository on GitHub. For this example, we will still use donut-portlet as the name of our repository. You need to create your GitHub repository under the QBiC's GitHub organization.

Navigate to your new repository's website (i.e., github.com/qbicsoftware/donut-portlet) and click on Settings. On the left side, click on Integrations & Services and add the Travis CI service. Leave all fields as they are and click on the Add Service button.

Enable your GitHub repository on Travis CI

The generated donut-portlet folder contains a .travis.yml file that will help you integrate your GitHub repository with Travis CI, our continuous integration service. Broadly speaking, everytime you push a change into your GitHub repository, Travis CI will download the code from your repository, compile it, run the unit tests and generate a code coverage report. Follow this guide to enable your new GitHub repository in Travis CI.

Deploying your project as a Maven artifact

Even though our Maven repository is visible to everyone publicly as read-only, you need a password to deploy artifacts into it. You will need to modify your .travis.yml file to add the encrypted username and password of our Maven repository. In your local GitHub repository directory (i.e., donut-portlet) run:

travis encrypt "MAVEN_REPO_USERNAME=<username>" --add env.global
travis encrypt "MAVEN_REPO_PASSWORD=<password>" --add env.global

Ask the people who wrote this guide about the proper values of <username> and <password>. Encryption and decryption keys in Travis CI are bound to their GitHub repository, so you cannot simply copy them from other places.

Pushing your first version

In your local GitHub repository directory (i.e., donut-portlet) run the following commands:

git init
git add .
git commit -m "Initial commit before pressing the 'flush radioactive material' button"
git remote add origin https://github.com/qbicsoftware/donut-portlet
git push origin master

Of course, you must replace donut-portlet with the real name of your repository. You can now start using your repository containing your brand new portlet.

Getting slack notifications from Travis CI (optional)

You can edit the .travis.yml file to tell Travis to send slack notifications. In your GitHub local repository folder execute:

travis encrypt "<your GitHub Account>:<token>" --add notifications.slack.rooms

Where <token> can be obtained by clicking on the "Edit configuration" icon (it looks like a pencil) in this page.