Vojtech Ruzicka's Programming Blog

Netlify build plugins: 3x faster GatsbyJS build

Wed, 13 May 2020 22:12:03 GMT

UPDATE: Build plugins are no longer in beta and are officially available.

Netlify build plugins

Netlify build plugins allow you to run custom plugins as a part of your Nelify build process. This allows you to alter your build and run some additional actions.

Enabling plugins

Netlify build plugins are not enabled by default. This feature is still in beta (as of 5/2020). You can, however, explicitly enable beta build plugin support. Just click on the link Build Plugins in the main navigation.

Now simply click Enable the beta button:

Now you need to select which repositories should be enabled for plugins. Note that for sites to be available for plugins, they need to be based on the Xenial image. New sites should be based on this by default, but for older sites, you might need to change the image explicitly. You can find this configuration under your site settings:

Settings → Build & Deploy → Build image selection

After selecting repositories, you can see the list of available plugins.

Configuration

Plugins are not enabled and configured directly from the Netlify UI. Instead, you enable and configure your build plugins in netlify.toml file, which should be located inside of your project on the root level.

The configuration for netlify-plugin-gatsby-cache can be as simple as this:

[build]
  publish = "public"

[[plugins]]
package = "netlify-plugin-gatsby-cache"

If you have plugins enabled for your site and this configuration file is present, Netlify will automatically trigger any build plugins defined in your file with the provided settings.

Gatsby cache plugin

This blog uses GatsbyJS as a static site generator. Originally, the build would take quite a lot of time. This is usually not a problem with GatsbyJS - only the original build takes long, but the subsequent builds are much faster due to Gatsby's cache. Netlify does not preserve this cache by default, so each build is long.

Even if the deployment time is not critical for your application, it can help a lot to improve it. That's because after running out of build minutes, you have to pay for more. And the free plan only currently offers 300 build minutes.

Fortunately, there is a Netlify build plugin called netlify-plugin-gatsby-cache, which fixes this and makes the subsequent builds much faster.

My current site is as follows:

4087 image thumbnails (various sizes)
119 GraphQL queries
92 articles

Without the plugin the build takes 13m 20s. With the plugin it takes 3m 44s. That is 3.57x faster!

The time can vary as it depends on the size of your site and the changes that you make.

The official docs also provide examples of time reduction:

Site Size	No Cache	Cache	Savings
231 GraphQL queries 1,871 images 224 pages	293207ms (build log)	72835ms (build log)	75%
5 GraphQL queries No image processing 32 pages	22072ms (build log)	15543ms (build log)	30%

More plugins

There are currently 20 plugins available, featured on the Netlify site. Here are some of the interesting ones:

netlify-plugin-a11y: Validate your site with pa11y and fail the build if there are accessibility problems.
netlify-build-plugin-speedcurve: Test your performance using SpeedCurve after each deploy.
netlify-plugin-checklinks: Check your site for broken links.
netlify-plugin-inline-source: Inline some of your assets to reduce the amount of HTTP request and increase performance.
netlify-plugin-sitemap: Automatically generate sitemap of your site.
netlify-plugin-rss: Generate RSS feed for your site.

Additional resources

CSS Flexbox tutorial

Fri, 24 Apr 2020 22:12:03 GMT

Flexbox is a powerful layout tool, which allows you to automatically arrange and size items inside a container.

Flexbox

Flexbox, short for Flexible Box, is defined in the CSS Flexible Box Layout Module specifiation.

It allows you to control the layout in a parent container. It offers some useful settings, which allow you to control the alignment of the items and to distribute the extra space. Flexbox is one-dimensional. That means it lays out its items in one dimension - either horizontally or vertically. An example of a two-dimensional layout can be CSS Grid.

Flexbox is a powerful tool, which allows you to control layout in a way that was previously very difficult or possible only using hacky solutions.

Flex container

With Flexbox, we have to consider both the element itself and also its children. That's because Flexbox is mainly focused on how its children (flex items) are positioned within the main element (flexbox container).

<div class="flexbox-container">
    <div class="flexbox-item">1</div>
    <div class="flexbox-item">2</div>
    <div class="flexbox-item">3</div>
    <div class="flexbox-item">4</div>
    <div class="flexbox-item">5</div>
</div>

It is important to grasp the concept of flexbox-container and flexbox-items. That's because some properties for Flexbox are applied to the container level and some for the individual items.

Without any CSS styles, the code above will display all the flexbox-items under each other. Each item will span the whole width available. That's because div is a block element, and it is how block elements behave.

Let's try to turn the flexbox-container to Flexbox. All we have to do is to add the following style:

.flexbox-container {
    display: flex;
}

Now the layout will be different. All the items are now displayed horizontally, from left to right. I've also added some background colors and borders, so you can better see the layout.

The display: flex; property is always applied on the container level, not the item level. It defines that the container should layout its children using Flexbox.

Block vs. inline Flexbox

Flexbox is slightly different from positioning normal elements using display property. If we use display: block; or display: inline; we define how the element should be displayed in the document flow.

When we defined display: flex; we saw that it affected how the children are displayed in the flex-container. But what about the container itself - how is it displayed? Is it inline element, or is it block?

Block elements:

Block elements span the whole width available
Block elements are positioned one under another
Block elements can have properties such as width and height
Examples: div, h1, ul

Inline elements:

Inline elements are positioned on a line next to each other, from left to right
Inline elements take only as much space as required by their contents
Inline elements ignore properties such as width and height
Inline-block elements behave as inline elements, but you can also specify properties such as width and height
Inline elements example: span, b, i, label

Actually, we have two options when using Flexbox. We can make the container either inline or block element using:

display: flex;
display: inline-flex;

If we want to our container to be displayed inline, we use display: inline-flex;. If we want it to be displayed as a block, we use display: flex;.

Note that display: inline-flex; behaves actually as inline-block rather than inline. That means it is still displayed on a line, but you can define properties such as width and height.

Be aware that this defines only how the container should be displayed in the document flow, not its child items.

Flex direction

In our example, the child items were displayed horizontally, from left to right. That's the default behavior, if you don't specify otherwise.

You can control the flow direction of flex items by defining flex-direction. This is done on the container level, not the item level.

row (default, horizontal, from left to right)
row-reverse (horizontal, from right to left)
column (vertical, from top to bottom)
column-reverse (vertical, from bottom to up)

When we did not specify flex-direction, it used the default value, which is row. For horizontal placement, but from the other direction, you can use row-reverse. For vertical, you can use either column or column-reverse.

.flex-conteiner {
    display:flex;
    flex-direction: column-reverse;
}

If you use row-reverse or column-reverse, be aware that this has some usability and accessibility implications. This only changes the visual order of the elements, not their logical order. Screen readers will still process the items in the order they are declared in your HTML. The same applies for navigation using Tab key.

We said that row means horizontally, left to right. It is not entirely true, though. It applies in languages, which have writing order from left to right. In languages, which use the opposite order (right to left), the Flexbox row setting would follow that direction. This means that in languages, such as Arabic, flex-direction: row; would actually order items from right to left instead of left to right.

Main vs. cross axis

To better understand some of the following concepts, we need to introduce some more terminology. Flexbox uses two axes. The main axis and the cross axis. They are perpendicular to each other.

The main axis is horizontal in row mode and vertical in column mode
The cross axis is vertical in row mode and horizontal in column mode

The direction of each axis depends on the writing mode (left to right in English) and flow-direction.

Main axis is left-to-right in row and right-to-left in row-reverse
Cross axis is top-to-bottom in column and bottom-to-top in column-reverse

Justify content

In our previous examples, all the items were aligned to the flex-start - that is to the left when displaying as a row and to the top when displaying as a column. This is the default behavior, but you can change it with justify-content property. For alignment, you can use the following values:

flex-start (default)
flex-end
center

It allows you to align items on the main flex axis, that is:

horizontally when the flex-direction is row or row-reverse
vertically when the flex-direction is column or column-reverse

Because you can have either normal or reversed flex order, you can't specify alignment as left, right, top, or bottom. Instead, you work with flex-start and flex-end, which depends on whether you are in normal or reverse mode.

Distributing extra space

The justify-content property can be used not only for aligning items, but also for spreading items evenly across all the available space on the main axis.

You can use these valus:

justify-content: space-between;
justify-content: space-around;
justify-content: space-evenly;

In all cases, the items are distributed, so the space between neighboring items is always the same. The three values differ only in a way how the spacing between first and last item and the edge of the container is calculated.

space-between;: first and last items have no space relative to the edge of the container
space-around;: half of the space compared to the gaps between items
space-evenly;: same space as between items

Align items

We learned how to align items on the main axis using justify-content. What about the other axis, the cross axis?

The cross axis is the axis perpendicular to the main axis, that means:

in row mode, the cross axis is vertical
in column mode, the cross axis is horizontal

You can use align-items property on the container level to define cross-axis alignment. There are several properties you can choose from:

flex-start: align to the start of the cross axis
- top in row mode
- left in column mode
flex-end: align to the end of the cross axis
- bottom in row mode
- right in column mode
center: align to the middle
stretch: stretch the component to fill the available space on the cross axis (respects max-width and max-height of items)
baseline: items are aligned by their baselines

This works as expected and is self-explanatory, considering what we've already learned. The baseline setting is a bit trickier, though. It aligns items by their baselines. The following image from Wikipedia shows this nicely.

Let's look at a specific example:

As you can see, the baseline, in this case, is usually the bottom of the first line of text in each item. The bottom here means where most of the regular letters end. There are some letters such as p or j. that go under the baseline.

Note how multiline items and items with no content are handled. You can check more details about the baseline calculation in Flexbox.

Wrapping

So far, our flex container was big enough to fit all of its content properly. But what happens if there are too many items, which do not fit the size of its parent container?

By default, the container tries to shrink the items if possible, but eventually, the items may overflow out of the container. Note that the container tries to shrink items when not enough space is available even though we explicitly set width: 50px;. This width is preserved only if there is enough space. We'll learn how to control or disable this behavior a bit later using flex-shrink.

This may be ok in some cases, but usually, you want more control over how this case is handled. You can also use flex-wrap property on the container level to specify how the wrapping of items should be handled. There are three possible values:

nowrap - (default) one line, may overflow the container
wrap - wrap to multiple lines from top to bottom
wrap-reverse - wrap to multiple in the opposite order from bottom to top

The difference between wrap and wrap-reverse may be confusing, let's better look at an example.

Aligning wrapped content

When items are wrapped in a Flexbox, and you have, therefore, multiple lines, you can control how these lines are aligned on the cross axis. You can use property align-content.

Do not confuse this with align-items and justify-content.

justify-content: aligns across the main axis
- the main axis is horizontal when in row mode
- the main axis is vertical when in column mode
align-items: aligns items within a row on cross axis
- the cross axis is perpendicular to the main axis
align-content: aligns wrapped lines across the cross axis
- used to align multiple wrapped lines; for regular cross axis aligning, we can use align-items

This property has no effect unless you have either flex-wrap: wrap; or flex-wrap: wrap-reverse;.

The good news is that the possible values of align-content are very similar as with justify-content:

stretch (default)
flex-start
flex-end
center
space-between
space-around
space-evenly

The alignment just works on the other axis, but the behavior is the same.

Item level properties

So far, we've covered properties, which are defined on the flex container level. Now let's look into properties, which are defined on the level of individual flex items.

Aligning individual items

So far, we covered several options for handling alignment:

justify-content: align items on the main axis
align-items: align items on the cross axis
align-content: align multiple rows when wrapping on the cross axis

All these settings apply for the whole container. It is possible to also handle the alignment of individual items on the cross axis. This is defined on the item level, not the container level. It uses property align-self. You can use the following values:

flex-start
flex-end
center
stretch
baseline

Of course, this can be combined with defining alignment on the container level using align-items. You can define general alignment for the items on the container level, and then override it for individual items. For example, you can define items to be aligned for the whole container using align-items: flex-end; and then change the alignment for individual items using align-self.

Ordering items

Items in the flexbox container are not necessarily displayed in the order, in which they are declared in HTML. That is, you can reorder items by assigning them specific order property. This is an integer value and defaults to 0 if not specified otherwise. This property is set not on the flex container level, but at the item level, as you want to order individual items.

If you want to put items before those, which don't have order specified, you can use negative values.

Multiple items can have the same order value. Such items belong to the same ordinal group. Items within the same group are then ordered in the same order in which they are declared in HTML.

For example, if you have three items with order 1, they will be placed after all the items with the lower order. All these three items with the same order value will then be placed in the same order as in HTML.

Visual, not logical order

You have to be careful when changing the order in a flexbox container this way. This only changes the visual order of the items, not logical order. In other words, in DOM, the items are still placed in the same order as in HTML.

This has several implications. Most notably, any assistive technologies such as screen readers will process the items in their original order. This also applies to keyboard navigation using Tab key, unless you also explicitly change tab-order of your components.

Flexibility

One of the most powerful features of Flexbox is the ability to adjust the size of the items inside based on the size of the container. This means:

You can enlarge the items to fill all the available space
You can shrink the items to fit when there is not enough space

This is very powerful as all the items are automatically resized when the size of the flex container changes. Moreover, you can define resizing behavior per each item inside the container. For example - some items can grow more, some items less, and some not at all.

Flex-grow

Using this property, you can control how items should grow when there is extra space available. The default value, if not specified otherwise, is flex-grow: 0. That means that items will not grow to fill the extra space on the main axis by default.

However, this can be changed by assigning any numeric value greater than 0. Negative values are not allowed.

Let's say we assign flex-grow: 1; to all items. This means that the extra space will be assigned proportionally to each item in a way that each item gets the same amount of extra space. This is because their flex-grow values are the same.

So what does the value actually do?

Extra space available is distributed among the components proportionally to their flex-grow values.

This means if there are two items, and both have flex-grow: 1; they both get 50% of the available space. That's because the ratio of their values is 1:1.

If one item has flex-grow: 3 and the other one flex-grow: 1, the ratio of their values is 3:1, which means he first one will get 3x as much as space (75%) as the second one (25%). If there are 100px of extra space, the first component will get grow by 75px, and the second one will grow by 25px.

The common misconception is that ratio, let's say 2:1, means that the first component will end up being twice as big as the second one. But remember, it is about how the extra space is distributed, not the final size. The ratio of flex-grow values determines the percentage of the extra space each item will get, not their final sizes.

Values between 0 and 1

Values greater than 0, but less than 1 have special behavior. If the sum of all the flex-grow values in a container is less than 1, items will still grow, but will not fill the entire container.

For example, if we have three items, each with flex-grow: 0.25; their sum is 0.75. This means that the items will grow, but only occupy 75% of the available space, the rest will be empty.

In the example above, we have two items with value 0.1 and one with 0.4. The sum is 0.6. That means that only 60% of extra space will be occupied while the items with 0.1 will get 1/6 of space each, and the item with 0.4 will get 4/6 of distributed space.

In other words, 10% of extra space will get two items with 0.1 each, 40% will be added to item with 0.4, and the rest of 40% will stay unoccupied.

Flex-shrink

This property determines how items should be reduced in size if there is not enough space available in the container.

Again, it is a non-negative numeric value, where 0 means no shrinking at all. The ratio of these values determines how much each item will shrink compared to others. The difference is that the default value is 1. This means that the items will shrink by default (but they don't grow by default).

We already encountered this with wrapping - items shrink only to certain degree, so they can still fit their content. After that point, these items will overflow unless you specify wrapping.

There is one more notable difference between flex-grow and flex-shrink. In addition to ratios (same as with growing), the base size of each item is considered when determining how much each item will shrink. This means even if the flex-shrink value is the same, bigger items will shrink more than smaller items.

In other words, larger items (which are able to shrink more) will shrink faster than smaller items (which have limited space left for shrinking).

Flex-basis

When calculating shrinking and growing in a Flexbox, it is important to know the size of each item on the main axis. For example, to calculate the space available for growth, you need to take the size of the flex container minus sizes of all the items. How are the sizes of individual items calculated, though?

You can specify width or height of items
If not specified, the items are sized based on their content

You can also specify flex-basis property, which is used for sizing. It can use the same values as width or height. You can see, that width and height are two properties for horizontal and vertical sizing. But there is only one flex-basis. That's because it controls sizing on the main axis. This means if you are in row mode, it controls width. In column mode, it controls the height. So even if you switch between rows and columns dynamically, you can still use the same flex-basis property.

The behavior of flex-basis is the following:

it defaults to auto
auto uses either specified width or height. If these are not specified, it uses sizing based on contents of the item
it overrides any width or height
it respects min/max width and height
you can also use content value, which uses automatic size based on content (it was not present in the initial spec, and older browsers do not support it)

Shorthand properties

Although you can specify flex properties such as flex-grow or flex-shrink individually, there are some shorthand properties, which allow you to combine multiple individual properties together. Using shorthand properties is usually a preferred way instead of defining the properties individually.

Flex-flow

This property allows you to combine flex-direction and flex-wrap.

flex-flow: flex-direction flex-wrap;

Of course, you need to provide specific values instead of flex-direction and flex-wrap:

flex-flow: column wrap-reverse;

/* Equivaluent css without using shorthand flex property: */

flex-direction: column;
flex-wrap: wrap-reverse;

Flex

This property allows you to combine the following individual properties together:

flex-grow
flex-shrink
flex-basis

It is defined like this:

flex: flex-grow flex-shrink flex-basis;

You need to substitute flex-grow, flex-shrink and flex-basis with specific values here:

flex: 1 2 100px;

/* Equivaluent css without using shorthand flex property: */

flex-grow: 1;
flex-shrink: 2;
flex-basis: 100px;

There are also several options to specify less than three values.

One value

With one value, you can use:

flex: auto; - equivalent to flex: 1 1 auto;
flex: none; - equivalent to flex: 0 0 auto
flex: [positive number] - defines just flex-grow, the rest uses default values; equivalent to flex: [positive number] 1 0px;

Two values

You can also specify just two values instead of 3. In this case, the first one is always flex-grow. The second one depends on the type of value that you provide.

number (eg. flex: 1 1;) is interpreted as flex-shrink, flex basis defaults to 0px in this case
valid size value (eg. flex: 1 100px) is interpreted as flex-basis, flex shrink defaults to 1

Note when using flex shorthand,flex-basis defaults to 0, if not specified. This is different from the default value of flex-basis, which is auto.

Shorthand or individual properties?

This shorthand is preferred over defining the properties individually, as stated in the spec.

Authors are encouraged to control flexibility using the flex shorthand rather than with flex-grow directly, as the shorthand correctly resets any unspecified components to accommodate common uses.

Firefox DevTools

If you want to tinker with Flexbox settings, Firefox developer tools offer powerful support for Flexbox debugging and visualization. Check it out.

Browser Support

Fortunately, Flexbox currently has great support across all the major browsers. That is 98.72% of all the users. It is even supported by IE 11, even though it has many issues and some non-standard behavior.

If you are targeting some old browsers, you can check Advanced Cross-Browser Flexbox.

Learning flexbox with zombies

Learning Flexbox is way more fun if there are zombies involved. Instead of reading boring tutorials, you can shoot zombies with your crossbow, while learning Flexbox. Try Flexbox Zombies browser game. It is for free.

Want some more practice? You can check other games helping you to master Flexbox, such as Flexbox Defense - a tower defense game where you position your towers using CSS and Flexbox. Another one is Flexbox Froggy - help Froggy and his friends to reach lilypads and cross a pond by writing CSS code.

Additional resources

Flexbox specification
Solved by Flexbox - showcase of common layout problems solved by Flexbox
Interactive Flexbox playground for testing various flex properties

As you can see, the space required for the original location of the element is still allocated.

As a result of an element being moved from its original position, there can be a situation, where multiple elements overlap each other. Fortunately, with z-index property, you can control which elements should be in the front and which in the back. We'll discuss this in more detail later.

absolute

Absolute positioning is trickier. Unlike with the relative position, elements are removed from the normal document flow, and their original space is not reserved.

Using top, bottom, left, and right properties, you determine where the element should be placed relative to the first parent in the element hierarchy, which has position set to anything else than static.

If there is no such parent, it is set relative to the whole page.

Each orange box is positioned relative to the gray container box. This is possible because the container has position set to relative. If the container's position was static, the orange boxes would be positioned relative to the whole page.

Another important behavior to notice is that we explicitly set the height of the gray container to 200 px. That's because, unlike with relative position, absolutely positioned elements are removed from the normal document flow and don't occupy any space when calculating the size of the parent container.

When we don't specify the height of the gray container box, it will collapse to zero as it does not contain any elements, which are used to determine its size.

fixed

Fixed positioning is similar to absolute in a way that the element is also removed from the normal document flow, and its original space is not reserved.

The position is determined relative to the viewport. This means that even if you scroll, the element preserves its original location on the page. This can be useful, for example, if you want to have a navigation bar, which is always visible on the top, no matter where you are on the page. Or a cookie info bar on the bottom.

Although this can be tempting, be careful with its usage. On a mobile device with a small screen, it can be a big deal if a large portion of your screen is always covered with a navigation bar or something similar. It dramatically reduces space for the actual content of your page and can significantly limit usability.

sticky

The sticky position is the latest addition to the list of position properties. It is a hybrid between relative and fixed positions.

The element is normally positioned on the page, but when you reach its position when scrolling, its position becomes fixed. It sticks to its location and stays there when you scroll further.

Browser Support

The sticky value is not universally supported.

For example, Internet Explored does not support it at all. With Safari, you can use it, but you need to use vendor-specific prefixed variant position: -webkit-sticky;. Therefore for maximum compatibility, you should use both:

position: sticky;
position: -webkit-sticky;

If you need to support IE as well, you can use a polyfill such as StickyBits or stickyfill.

z-index

When working with position other than static, elements can easily appear in position, where they overlap each other.

In such cases, it is handy to have control over the order of these elements. That is - which elements should be displayed in front and which in back.

Fortunately, this is quite easy with a property called z-index. It controls the position of your elements on the z-axis. That is, which ones are in front of other elements and which ones are in the background.

You can use z-index like this:

z-index: 1;

The elements with higher z-index are displayed in front of elements with lower z-index.

In the example, you can see that you can also specify negative numbers, which places these elements behind those with no z-index or index with value 0.

Summary

Let's sum it up. The position property allows you to determine how elements should be placed on the page.

You can define the exact location using top, bottom, right and left properties.

In case your elements overlap each other, you can change their order using z-index. The higher the index, the closer is the element to the user.

static

Default value
Positioning as usual, same as if you didn't specify the position

relative

The element is placed relative to its normal position on the page
The place occupied by the element is preserved at its original location

absolute

The element is removed from the normal flow and does not occupy space
The location is determined relative to the first parent set position (other than static)
If there is no such parent, it is determined relative to the whole page

fixed

The element is removed from the normal flow and does not occupy space
The location is determined relative to the viewport
Elements keep their locations as you scroll

sticky

Elements are positioned relatively until you reach them by scrolling
Then the elements stick to one location, similar to fixed positioning
Not supported by all the browsers, you can use polyfills

Java Records (JEP 359)

Mon, 03 Feb 2020 22:12:03 GMT

The problem

One of the issues with Java is its verbosity and the amount of boilerplate code needed. That's nothing new.

Let's consider a simple Cat class in Java. We want each cat to have:

Name
Number of lives
Color

Quite simple, right? Now let's look at the code in Java. For simplicity, let's make our class immutable - no setters, we'll set up everything in our constructor.

public final class Cat {
    
    private final String name;
    private final int numberOfLives;
    private final String color;

    public Cat(String name, int numberOfLives, String color) {
        this.name = name;
        this.numberOfLives = numberOfLives;
        this.color = color;
    }

    public String getName() {
        return name;
    }

    public int getNumberOfLives() {
        return numberOfLives;
    }

    public String getColor() {
        return color;
    }
}

It's already quite long, isn't it? It gets worse. We'll also want to have some basic implementation of equals() and hashCode().

@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;
    Cat cat = (Cat) o;
    return numberOfLives == cat.numberOfLives &&
            Objects.equals(name, cat.name) &&
            Objects.equals(color, cat.color);
}

@Override
public int hashCode() {
    return Objects.hash(name, numberOfLives, color);
}

Are we done yet? Not quite, we'll also need some nice toString() method:

@Override
public String toString() {
    return "Cat{" +
            "name='" + name + '\'' +
            ", numberOfLives=" + numberOfLives +
            ", color='" + color + '\'' +
            '}';
}

And we're finally done. It's about fifty lines of code! It's quite painful to write (although your IDE can help here) and difficult to read. What's worse, it's hard to find some extra functionality (such as new methods) in all the boilerplate.

In these fifty lines, there are only three lines that are actually interesting and bear some information:

private final String name;
private final int numberOfLives;
private final String color;

The rest is just boilerplate, which is predictable and can be automatically generated based on these three lines. Your IDE can do that, and there are tools such as Lombok, which can do this for you as well.

In Java, you often use classes, which just hold data, like our Cat. The implementation is always pretty much the same - a bunch of fields, getters, equals(), hashCode() and toString(). Often it is useful to have them immutable, if possible, which has many benefits. But to write and read such classes is a lot of work as there is a lot of code involved. And it is error-prone. Who knows whether your hashCode() and equals() code is actually correct?

Records

Java 14 tries to solve this issue by introducing a new type called Record, it is described by JEP 359: Records (Preview)

The same 50 lines long class from the example above could be written as a record like this:

public record Cat(String name, int numberOfLives, String color) { }

It's a lot less code, right?

The functionality is the same as in our previous example - we have:

an immutable class with three fields
Constructor assigning these fields
Getters
equals(), hashCode() and toString()

To illustrate this better, let's look at the decompiled version of our record.

public final class Cat extends java.lang.Record {
    private final java.lang.String name;
    private final int numberOfLives;
    private final java.lang.String color;

    public Cat(java.lang.String name, int numberOfLives, java.lang.String color) { /* compiled code */ }

    public java.lang.String toString() { /* compiled code */ }

    public final int hashCode() { /* compiled code */ }

    public final boolean equals(java.lang.Object o) { /* compiled code */ }

    public java.lang.String name() { /* compiled code */ }

    public int numberOfLives() { /* compiled code */ }

    public java.lang.String color() { /* compiled code */ }
}

You can see that the code is pretty much the same as our old Cat. One notable exception is that getters for the fields generated are not named as usual - instead of getColor(), there is just color().

Also, the class extends java.lang.Record.

The equals() implementation considers two records to be equal if they are the same Type and have the same values. The toString() implementation prints our record like this:

Cat[name=Fluffy, numberOfLives=9, color=White]

Even though these methods are automatically provided for you, it is possible to override them if necessary.

Limitations

There are some restrictions and limitations of records, which you should be aware of.

Records cannot extend any class, although they can implement interfaces
Records cannot be abstract
Records are implicitly final; they cannot be inherited from
You can declare additional fields in the body of a record, but only if they are static

Adding methods

Even though records are mostly used just as plain data carriers, you can declare your own methods. Of course, since records are immutable, you cannot change any state, but it can still be useful. For example:

public record Cat(String name, int numberOfLives, String color) {
 
    public boolean isAlive() {
        return numberOfLives >= 0;
    }

}

You can also add static methods.

Custom constructors

By default, new records contain only a constructor, which requires all the fields of the record as parameters. For example, our cat, which has three fields, needs to be constructed like this:

Cat cat = new Cat("Fluffy", 9, "White");

What if some parameters can be optional - if we don't provide them, we can use some default value.

In our case, the number of lives for new cats is likely to be always 9. We can create an additional constructor, which accepts only name and color, and the number of lives can be set to 9 as a default value. Of course, the constructor with all three fields still exists and is available.

public record Cat(String name, int numberOfLives, String color) {

    public Cat(String name, String color) {
        this(name, 9, color);
    }
}

The all-fields constructor is automatically generated for us. But sometimes you need to perform some custom logic there. Such as input validation. You can declare the all-fields constructor by yourself if you need to:

public record Cat(String name, int numberOfLives, String color) {

    public Cat(String name,int numberOfLives, String color) {
        if(numberOfLives < 0) {
            throw new IllegalArgumentException("Number of lives cannot be less than 0.");
        }

        if(numberOfLives > 9) {
            throw new IllegalArgumentException("Cats cannot have that many lives.");
        }

        this.name = name;
        this.numberOfLives = numberOfLives;
        this.color = color;
    }
}

If you are overriding the constructor with all the fields which record specifies (canonical constructor), you can use a declaration without writing the parameters. They are still available for use, but the code is shorter.

public record Cat(String name, int numberOfLives, String color) {

    // This is the same as public Cat(String name, int numberOfLives, String color)
    public Cat {
        // name, numberOfLives and color available here
    }
}

Runtime introspection

There are two new methods added to java.lang.Class, which have records-related functionality.

The first one is called isRecord(). It is pretty straightforward, you can just check if something is a record or not:

Cat cat = new Cat("Fluffy", 9, "White");
if(cat.getClass().isRecord()) {
    //...
}

The other one is getRecordComponents(). You would call it in the same way as in the example above. It returns a list of java.lang.reflect.RecordComponent. It is basically a list of all the fields, which are in the record with information such as:

Name
Type
Accessor
Annotations

Try it yourself!

If you want to try this feature yourself, you can already do so even though Java 14 is not out there yet (as of 2/2020).

Preview feature

Records functionality is available in Java 14. However, currently only as a preview feature. What does it mean?

A preview language or VM feature is a new feature of the Java SE Platform that is fully specified, fully implemented, and yet impermanent. It is available in a JDK feature release to provoke developer feedback based on real-world use; this may lead to it becoming permanent in a future Java SE Platform.

Before the next JDK feature release, the feature's "real world" strengths and weaknesses will be evaluated to decide if the feature has a long-term role in the Java SE Platform and, if so, whether it needs refinement. Consequently, the feature may be granted final and permanent status (with or without refinements), or undergo a further preview period (with or without refinements), or else be removed.

Such features are shipped in the JDK but are not enabled by default. You need to explicitly enable them to use them. Needless to say, it is not intended for production use, but rather for evaluation and experimentation as it may get removed or heavily changed in a future release.

To try this feature yourself, you'll need to have JDK 14 installed.

IntelliJ IDEA setup

In IntelliJ IDEA, you can enable preview features under File → Project Structure.

To use records in IntelliJ IDEA, you'll need version 2020.1and later. As of 2/2020, it is available as Early Access Program build. Currently, IDEA has basic support for records, but full-fledged support should be available with the release version.

Manual compilation

Alternatively, if building manually, you need to provide the following params to javac:

javac --release 14 --enable-preview ...

That is for compile-time. At run-time, you just provide --enable-preview

java --enable-preview ...

Maven projects

For Maven builds, you can use the following configuration:

<build>
    <plugins>
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <release>14</release>
                <compilerArgs>
                    --enable-preview
                </compilerArgs>
                <source>14</source>
                <target>14</target>
            </configuration>
        </plugin>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <argLine>--enable-preview</argLine>
            </configuration>
        </plugin>
        <plugin>
            <artifactId>maven-failsafe-plugin</artifactId>
            <configuration>
                <argLine>--enable-preview</argLine>
            </configuration>
        </plugin>
    </plugins>
</build>

Also new in Java 14

IntelliJ IDEA best plugins

Tue, 21 Jan 2020 22:12:03 GMT

Key promoter X

Using keyboard shortcuts instead of your mouse can greatly increase your productivity. With so many features IDEA offers, it can be intimidating and difficult to learn all the shortcuts. Fortunately, there is a plugin called Key Promoter X, which can help you.

The idea is simple: whenever you use your mouse to invoke a command in your IDE, a popup is shown, which tells you what the keyboard shortcut for this action is.

It even offers you to assign a keyboard shortcut to an action just performed if there is none yet. After a while, it gets so annoying, that you rather make sure you remember your keyboard shortcuts.

Snyk

Application security is often unfortunately neglected. These days most of the application code comes from third-party libraries and frameworks. You need to make sure you use new versions without security vulnerabilities. There are tools, which can help you with this. One of them is Snyk.

Snyk – Detecting dependencies with known vulnerabilities

22 November, 2017

#Security

How to detect and fix security vulnerabilities in your dependencies using Snyk?

Snyk offers many features. One of them is IDE plugin, which can scan your dependencies and detect what security vulnerabilities they contain.

Presentation assistant

This is a simple plugin, which shows a pop-up notification every time you perform an action in IDEA. It shows what action was performed and what is the keyboard shortcut associated with it.

This can be very useful when presenting, during screencasts, pair programming and so on. Especially when using keyboard shortcuts, it can be difficult to follow what's happening without this plugin.

Edu Tools

This is a great plugin for coding lessons, workshops, and so on. It allows you to build courses, with a set of tasks, which can be performed directly in your IDE. You can build your own courses or import public courses.

IDEA EduTools: Learning directly in your IDE

05 May, 2019

#IDEA

Study programming courses directly in your IDE or create your own.

This is available either as a separate plugin or as IntelliJ IDEA Edu Edition, which is basically IDEA Community edition with this plugin already bundled.

Extra icons

This is basically an icon pack, which provides new icons for special files such as Travis configuration, package.json, lint config, and many more.

This can be very useful as you can immediately recognize these special files, and your project is, therefore, much easier to navigate. For example, package.json is a json file, but it is much more useful to have a special icon for it as it is an important file for npm projects.

Grazie

UPDATE: As of 2020.1, Grazie is bundled by default in IntelliJ IDEA.

IntelliJ IDEA has a basic spelling checker, which allows you to detect some typos, but it is not much useful on top of that. It is definitely not a replacement for dedicated grammar checking services such as Grammarly.

Fortunately, there is a plugin called Grazie, which enhances the basic spell checker with a lot of useful features. It also detects more advanced issues, such as incorrect grammar. It works completely offline, as well.

It allows you to enable checking of commit messages as well. You can learn more in the blog post Meet Grazie: the ultimate spelling, grammar, and style checker for IntelliJ IDEA.

Maven Helper

IDEA already has powerful tools for analyzing your dependencies and potential problems with them, such as conflicts or cyclic dependencies.

Maven helper offers an alternative UI, which shows your dependencies hierarchically. This can be easier to read and navigate. Also, if you're using the community edition, this is your only option.

InnerBuilder

Creating complex objects can be hard. Of course, you can stick with a simple POJO with a whole bunch of setters, but you cannot enforce that created objects have all the required fields and are not used in an incomplete state. To solve this, you need constructors. With more complex objects, this can lead to a whole bunch of telescopic constructors with many parameters. In these cases, using a builder is much more appropriate.

This plugin can automatically generate a builder for you from a POJO.

Rainbow Brackets

If you are struggling with a lot of nested blocks and a lot of brackets, this plugin is for you. It makes it very easy to locate matching brackets as each pair of brackets is color-coded.

It is quite hard to read with the default color theme, so Darcula is much more suitable for use with this plugin.

Indent Rainbow

This plugin is similar to Rainbow brackets, but it does not color your brackets, but rather your indentation. It can be beneficial if you have a lot of indentation levels, which are harder to navigate. It can even mark lines, which don't mark proper indentation levels with red, so it is immediately obvious when there is a mismatch.

Again, this is much less visible in the light theme, so Darcula may be a better choice.

String Manipulation

This is a handy plugin, which allows you to perform various actions with your strings such as:

Escaping/un-escaping for various contexts (Java, HTML, XML, SQL, ...)
Case switching (lower, upper, kebab, pascal, camel, ...)
Sorting
Grep
Trimming

Git Toolbox

Although git support in IntelliJ is already pretty good, this plugin still offers some useful features on top of that.

You can easily see how many commits is your branch ahead/behind. You can configure automatic fetch with configurable frequency. You can automatically see inline blame information on your current line.

Request Mapper

IDEA already offers pretty powerful navigation among files. When working with REST endpoints, you may sometimes prefer to navigate to a specific mapping (such as /persons) instead of class (such as PersonController). This is in cases where you know the URL, but don't remember which class or method it corresponds to. After pressing the associated keyboard shortcut, you can search your URL mappings and navigate to them directly.

The plugin currently supports Spring, JAX-RS, and Micronaut.

Multirun

IDEA does support running multiple tasks (configurations) at once, however, this feature is currently very limited.

Multirun plugin does support running multiple configurations at once with much more sophisticated options. This can be very useful when running both Backend and Frontend at once, testing multiple modules, and so on.

IDEA Mind Map

It can be very useful to have a mind map editor and viewer directly integrated in your IDE. Not only for quick brainstorming, but also for documentation. The plugin works with MMD files, which are text-based, so it is very easy to have your mind maps under version control and manage their changes.

Codota and TabNine

These two plugins are similar. They enhance your autocomplete based on scanning open-source projects and intelligently predicting what you probably want to type based on the context.

With Codota, you can also look up relevant examples of some class or method in public projects, which can be handy.

Nyan cat progress bar

Want to make waiting when idea is loading or building indices more fun? You can replace IDEA progress bars with a Nyan cat version.

If you're a fan of Street Fighter, you can have Hadouken version instead.

Grep console

This is a powerful plugin with a lot of useful features. It allows you to filter your console output, add custom highlighting or folding of similar line groups. You can even play sound or execute a script when a specific line type occurs in your console output. You can also tail files in your project and much more.

UPDATE: Plugin Ideas

There is a lot of plugins already available, plenty to choose from. Still, there may be no plugin to cover functionality you are looking for. Fortunately, you may be able to get what you need without resorting to developing it yourself.

In March 2021, Jetbrains launched a new site called Plugin Ideas. Essentially you can submit your own idea for a plugin, other people can add their own comments and suggestions. Ideas can be up-voted, so they can get more attention from potential developers who might pick up the idea and implement it. Ideas are neatly integrated with Youtrack issues, so you can track the progress.

Is something missing?

What are your favorite IDEA plugins? Share in the comments below.

JavaFX Weaver: Integration of JavaFX and Spring Boot

Mon, 18 Nov 2019 22:12:03 GMT

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

There is an example repository for this blog post, where you can check the final project.

JavaFX & Spring

When working with Java these days, you rarely work just with plain Java. In most of the projects, people usually use the Spring Framework or Spring Boot, respectively. It has a lot of advantages and many useful features.

However, when you're developing JavaFX applications, there is no easy way to integrate it with Spring. The integration does not work out of the box as JavaFX applications have their own lifecycle and take care of instantiating controllers.

JavaFX-Weaver

JavaFX-Weaver is a project by Rene Gielen, which aims to integrate Spring and JavaFX. The setup is, fortunately, not that hard.

Getting started

Let's try with a plain simple Spring Boot project, and let's try to integrate JavaFX. You can generate a new project using Spring Initializr. You don't need to add any dependencies here. If you want to avoid getting into setting up JavaFX as a dependency, select a Java version pre-11 as it still contains JavaFXas a part of the JDK.

Adding a controller

We'll need a controller and a companion .fxml view to be able to test that our application works properly both with Spring and JavaFX. Let' create a controller first. Let's keep it empty for now.

public class MyController {
}

Adding a view

Now we need a .fxml file, which will be used with our controller as a view. We'll place it in the resources folder. For the integration to work properly, it is necessary to create it in the resources folder, but in a directory structure matching the package where is our controller.

For example, let's assume our controller is in package com.vojtechruzicka.javafxweaverexample. The .fxml file needs to be placed precisely here:

src\main\resources\com\vojtechruzicka\javafxweaverexample

Let's call our file main-scene.fxml.

Dependencies

If you are using plain Spring, the setup is little different, but for Spring Boot you just need to add the following dependency to your pom.xml file:

<dependency>
    <groupId>net.rgielen</groupId>
    <artifactId>javafx-weaver-spring-boot-starter</artifactId>
    <version>1.3.0</version>
</dependency>

Or this one if you are using Gradle:

implementation 'javafx-weaver-spring-boot-starter:1.3.0'

Spring Boot Application class

When we generated our base Spring Boot application, the main application class was also generated for us. It is the class annotated with @SpringBootApplication, which is used as an entry point to run the whole app.

But wait! JavaFX also has its main application class, which is used as an entry point for starting JavaFX applications.

That's confusing. So which one should be actually used to run our app, which is both Spring Boot and JavaFX?

We'll still use our @SpringBootApplication with a slight modification. Instead of running the Spring app directly, we'll use it to run our JavaFX app. And the JavaFX Application will be responsible for properly starting the Spring application context and integrating everything together using JavaFX Weaver.

We need first to make sure that the Spring Boot app launches our JavaFX app.

import javafx.application.Application;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBootExampleApplication {

    public static void main(String[] args) {
        // This is how normal Spring Boot app would be launched
        // SpringApplication.run(SpringBootExampleApplication.class, args);

        // JavaFxApplication doesn't exist yet, 
        // we'll create it in the next step
        Application.launch(JavaFxApplication.class, args);    }
}

JavaFX Application class

Now our @SpringBootApplication is calling JavaFxApplication, which does not exist yet. Let's create it now.

public class JavaFxApplication extends Application {

    private ConfigurableApplicationContext applicationContext;

    @Override
    public void init() {
        String[] args = getParameters().getRaw().toArray(new String[0]);

        this.applicationContext = new SpringApplicationBuilder()
                .sources(SpringBootExampleApplication.class)
                .run(args);
    }

}

When the JavaFX initializes, it creates a new application context based on the configuration in our SpringBootExampleApplication - the main class of the Spring Boot application, which we modified in the previous step.

Now we have a Spring Boot application running with our new application context. But we need to make sure the context is properly closed when the JavaFX application terminates. For example, when you close the window. Let's handle this now.

@Override
public void stop() {
    this.applicationContext.close();
    Platform.exit();
}

Now the last part is to actually create a new window (Stage) and show it.

@Override
public void start(Stage stage) {
    FxWeaver fxWeaver = applicationContext.getBean(FxWeaver.class);
    Parent root = fxWeaver.loadView(MyController.class);
    Scene scene = new Scene(root);
    stage.setScene(scene);
    stage.show();
}

This is where Fx Weaver comes into play. We need to obtain its bean from the application context and then use it to load our FXML.

Spring-managed controllers

Traditionally we would create our Stage using FXMLLoader, which would load the FXML file and create a Controller instance declared in it for us.

FXMLLoader loader = new FXMLLoader();
URL xmlUrl = getClass().getResource("/main-scene.fxml");
loader.setLocation(xmlUrl);
Parent root = loader.load();
Scene scene = new Scene(root);
stage.setScene(scene);
stage.show();

So why are we using FX Weaver instead? What's problematic is that FXMLLoader creates the controller instance for us. That means it is not created and managed by Spring. Therefore we cannot use dependency injection and other Spring goodies in our controllers. And that's why we introduced Spring in our JavaFX in the first place!

But when FX Weaver creates the controller for us, it creates it as a Spring-managed bean, so we can fully utilize the features of Spring.

Enabling Spring for the controller

The first thing we need to do is to annotate our existing JavaFX controller with @Component so it gets recognized and managed by Spring. Next, we need to add @FxmlView annotation, so it gets recognized by FX Weaver.

import net.rgielen.fxweaver.core.FxmlView;
import org.springframework.stereotype.Component;

@Component@FxmlView("main-stage.fxml")public class MyController {
}

Note the parameter of @FxmlView("main-stage.fxml"). It specifies the name of your .fxml file, which should be matched with the controller. It is optional. If you don't specify it, Fx Weaver will use the name of the controller class as the file name with .fxml extension. The FXML file needs to be in the same package as the controller, but in the resources folder.

Making sure everything works

Now let's make sure everything works and integrates nicely. Let's run our @SpringBootApplication with its main method. You should see a simple window with a label, nothing fancy.

Ok, that means that the application runs, but we didn't really do anything Spring-specific in our controller. No dependency injection or anything. Let's try that now.

Adding a Service

To make sure Spring integration works properly, let's create a new Spring-managed service. Later, we'll inject it in our controller and use it there.

import org.springframework.stereotype.Service;

@Service
public class WeatherService {

    public String getWeatherForecast() {
        return "It's gonna snow a lot. Brace yourselves, the winter is coming.";
    }
}

Nothing special, it's a service for weather forecasting, which is not very dynamic right now, but it will be enough for our example.

Injecting the service

Now let's inject our new service into our existing controller. It's the usual Spring stuff, nothing special here.

@Component
@FxmlView("main-stage.fxml")
public class MyController {

    private WeatherService weatherService;
    @Autowired    public MyController(WeatherService weatherService) {        this.weatherService = weatherService;    }}

Loading the forecast

Now we need to load the data from our service somehow. Let's change our FMXL view, so:

There is a button which loads the data from WeatherService on click
The loaded data is shown in a label

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.*?>
<?import javafx.scene.layout.*?>

<VBox xmlns="http://javafx.com/javafx"
            xmlns:fx="http://javafx.com/fxml"
            fx:controller="com.vojtechruzicka.javafxweaverexample.MyController"
            prefHeight="100.0" prefWidth="350.0" spacing="10" alignment="CENTER">

    <Label fx:id="weatherLabel"/>    <Button onAction="#loadWeatherForecast">Get weather</Button></VBox>

Note the fx:id="weatherLabel" identifier, we'll use it to get access to this label in our controller so that we can change its text.

onAction="#loadWeatherForecast" is a method on our controller, which should be called when the button is clicked. We still need to add it to the controller. Let's do it now.

Controller logic

The last step is to change our controller, so it reacts to the button click in the view, loads weather forecast data, and sets it to our label.

So we need a reference to the label from our view so that we can change its text. We need to select its name to match the fx:id="weatherLabel".

@FXML
private Label weatherLabel;

Now we need to add the method, which is called when the button is clicked - onAction="#loadWeatherForecast".

public void loadWeatherForecast(ActionEvent actionEvent) {
    this.weatherLabel.setText(weatherService.getWeatherForecast());
}

In this method, we take the weather forecast from the service and set it to our label, which we defined before.

If you run the app now, after you click the button, it should load the current weather forecast.

Accessing components from view

Same as in plain JavaFX, you can declare components from view to be injected to your controller, so you can interact with them.

@FXML
private Label weatherLabel;

We already saw this works well. You just need to be careful about timing. Our controller is annotated by @Component, so it is a regular Spring-managed bean. It means it is instantiated by Spring when the application context starts and all the dependencies are injected. However, the weaving by FX Weaver happens later. And during this weaving, the component references are injected.

This has one implication. In your constructor and @PostConstruct you can already work with Spring injected dependencies as usual. However, be aware that during this time, references to components from the view are not yet available and are therefore null.

Conclusion

JavaFX Weaver provides a nice and easy way to integrate Spring with JavaFX applications. It is otherwise not so straightforward as JavaFX manages its own lifecycle and lifecycle of its controllers. JavaFX Weaver makes the integration possible and quite straightforward, so you can finally use all the cool features of Spring even with JavaFX.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

Commitlint: validate commit conventions automatically

Mon, 11 Nov 2019 22:12:03 GMT

Automatically check and enforce your commit conventions either with various available configurations.

Commit conventions

Although you can put pretty much anything in your commit messages, it is beneficial to have a more standardized and structured approach. It is better to stick to a convention, so all your commit messages follow the same structure. This has many advantages:

Your commit history is more readable and easier to navigate
You can automatically generate changelogs
Based on the type of changes, you can properly bump your version when using semantic versioning:
- major: when introducing breaking changes
- minor: when adding a feature
- fix: when adding a fix

There are various conventions. One example can be Conventional Commits.

Conventions can be very useful, but only as long as you can make sure everybody follows them. You can rely on your developers' discipline, but it is risky. Especially with external contributors to your codebase who may not be familiar enough with your convention. What's much better is having an automated tool to check your commits for you and reject them if they don't follow your conventions.

Githooks & Husky

Fortunately, Git already allows you to perform some actions when specific events are triggered. It is called git hooks. You can react in many phases of the git workflow, such as:

pre-commit
pre-push
pre-rebase
post-update

The bad news is that this is configured locally in your .git directory, so by default, each developer needs to be sure to install their hooks. If they don't, there are no checks, and you cannot check your conventions.

Fortunately, there is a tool called Husky for Node/NPM projects, which solves this issue. You can define your hooks in your project and they are automatically installed for you when running the project. This way all the developers will have proper hooks installed with no effort. If you need to change your hooks, you can do it n just one place, and it gets propagated to all your developers. You can read more about Husky in one of my previous posts:

Easy git hooks with Husky

21 June, 2018

#Git

Effortless creation and management of git hooks for your Node/NPM projects with Husky.

While Husky can be used to enforce your commit conventions, it can do much more. You can run your static code analysis, tests, automatic code formatting, and much more when committing.

Commitlint

Commitlint is an automated tool that can check your commit conventions for you and reject the commit if it does not follow your rules. These rules, of course, can be configured. Under the hood, Commitlint uses Husky git hooks.

Local setup

Husky

Since Commitlint utilizes Husky, we need to install it first. Husky is provided as dev-dependency, so it is used only locally and not bundled with your production code.

npm install --save-dev husky

Now we need to register a hook for checking a commit message. The hook is called commit-msg and can be registered in your package.json.

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }  
  }
}

Alternatively, you can use a dedicated .huskyrc file, which contains only Husky configuration:

{
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

Commitlint

Now when We have Husky, we need to install Commitlint CLI, which will be executed by Husky hook to validate commit messages. Again, it is just a dev dependency, which is not included in your production bundle.

npm install --save-dev @commitlint/cli

Convention configuration

Commitlint is just a tool for checking if your messages follow your conventions. It does not for you to use a specific convention, you can use whatever you want, it is fully configurable. It offers some configurations out of Currently supported configurations are:

Let's use @commitlint/config-conventional for now, but the process would be the same for any different configuration. We just need to install the proper package:

npm install --save-dev @commitlint/config-conventional

The last step is to create a Commitlint configuration file, where you define, which configuration should be used. We'll set up the one we just installed. Create a new file called commitlint.config.js in the root directory.

module.exports = {
    extends: ['@commitlint/config-conventional']
};

Verifying the setup

Now we're good to go. Let's just make sure everything works. Let's make sure our commit messages are tested against the Conventional Commits specification. Let's try an ordinary, not structured commit message first.

C:\projects\commitlint-example>git commit -m "created base project structure"
husky > commit-msg (node v10.16.3)
⧗   input: created base project structure
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky > commit-msg hook failed (add --no-verify to bypass)

The commit was rejected due to missing subject and type. Let's fix that.

git commit -m "feat: created base project structure

Now the commit was accepted. We added the type of the commit feat and the part after the colon : is considered the subject.

The full structure of conventional commits is the following:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Continous Integration

Local setup, as described above, is necessary and useful as the first line of defense. However, it is not bulletproof. Developers can Tinker with the local setup or suppress git hooks. You cannot rely purely on the local Husky setup. As another line of defense, it is viable to integrate Commitlint with your CI. You can reject invalid commits on the server even if developers manage to sneak them in.

Travis

Commitlint supports integration with Travis CI. First, elt's create a .travis.yml file in your root directory. We need to configure that it should run the Commitlint script.

language: node_js
node_js:
  - node
script:
  - commitlint-travis

Now we need to install Travis support in our project:

npm install --save-dev @commitlint/travis-cli

Now Travis can watch your Pull Requests and check whether new commits are compliant.

Commitlint GitHub action

Even simpler alternative to Travis is adding a GitHub Action. There is an action for Commitlint available.

The setup is super-easy. You just need to go to [this page] and click Install. You can select whether this action should apply for all your repost or just selected ones. And that's it. Now, whenever you create a Pull Request, it will be automatically checked by Commitlint.

Now if your PR contains invalid commit messages, the checks will fail:

And you will get a comment explaining all the failures:

Commit message wizard

Conventions are useful, but what's even more useful is to have some tool, which can help you compose valid commit messages. Especially when your convention is new, there are new joiners or external contributors. Fortunately, there are tools available that help you with crafting compliant commit messages.

Prompt CLI

Commitlint offers a tool, basically a command-line wizard, which lets you create your commit messages based on a series of questions. It is called @commitlint/prompt-cli. You can easily install it:

npm install --save-dev @commitlint/prompt-cli

Now you can register commit command in your package.json.

{
  "scripts": {
    "commit": "commit"
  }
}

Now instead of git commit, you can run npm run commit. It launches an interactive wizard in your console, which will ask you for all the parts of a commit message such as type, subject, and so on.

Please enter a type: [required] [tab-completion] [header]
<type> holds information about the goal of a change.

<type>(<scope>): <subject>
<body>
<footer>

72 characters left
❯ type:

What's cool is that this wizard automatically loads your configuration from your commitlint.config.js and behaves based on that config.

Commitizen

Another option instead of prompt-cli is a third-party solution called Commitizen.

It is also a wizard, which lets you easily create specification-compliant commit messages.

Custom configuration

If you're not happy with any settings of the predefined conventions, you can override them and provide some more configuration options for linting. This can be done in the commitlint.config.js file, which we already created.

The detailed configuration is beyond the scope of this article, but you can check the official configuration documentation and the list of all available rules.

Example repo

You can find an example repository I created with fully set up Commitlint here. It also includes Travis integration and prompt-cli with examples of rejected PRs.

Conclusion

Having convention for commit messages has many benefits, and you can use many automated tools to utilize that. Automatic generation of changelogs and version bumps are no longer a problem. Not to mention much better readability. Commitlint helps you with that both locally and on your Continous Integration server.

Husky, used by Commit lint, is a powerful tool for managing git hooks and can be used not only for commit messages but also for a wide variety of other quality checks.

Stackbit: build JAMStack sites in a few clicks

Thu, 07 Nov 2019 22:12:03 GMT

How to easily create full-blown JAMStack sites with a theme, CMS, and deployment using various static site generators.

JAMStack

JAMStack is a powerful concept of building static sites. It is an alternative to having a traditional heavyweight CMS, like WordPress, which is also responsible for dynamically creating and serving your content.

While tools like WordPress are powerful, they are much slower than static sites and can be easily hacked unless you diligently keep everything up to date.

When you build your sites statically, you can easily distribute them via a CDN for much better performance and utilize stronger caching. Since everything is static, you don't need to worry about your system being hacked as there are no moving parts. Everything is also much cheaper to run and host.

You can learn more about JAMStack and its benefits in one of my previous posts on how I migrated from WordPress to GatsbyJS:

Migration to GatsbyJS and JAM stack from WordPress

25 March, 2018

How and Why I migrated from WordPress to static JAM Stack site built with Gatsby JS.

Building Static sites

While JAMStack-powered sites have many advantages, there are drawbacks as well. The main disadvantage is that it takes much more effort to build a full-fledged site including theme, Content Management System and deployment.

With WordPress, you can have a running site in minutes with a little effort. Even non-developers can easily create and maintain a site. Not so much with JAMStack. You have to select and learn your static site generator. Then choose a theme and make sure it works well with your generator. Then choose one of many available CMSs. Then figure how to set up your deployment pipeline.

It takes a lot of effort for developers, and it is nearly impossible for somebody not so tech-savvy. At least it was until now.

Stackbit

Stackbit is a service, which solves the biggest pain point of static sites described above. It is a wizard, which lets you build and deploy a fully functioning static site using one of the supported static generators, with a theme, CMS and a functional deployment.

Creating a new site

New sites are created with a wizard in four simple steps.

1. Selecting a theme

The first step is to select a theme for your new site. There are currently 14 built-in themes, with 23 more marked as coming soon.

However, on top of built-in themes, you can import your own.

Traditionally, there was a problem of using themes with a static site generator as each theme is generator specific and cannot be easily shared between generators. This is where Stackbit really shines as it allows you to create universal themes independent on a generator. This way, it makes it easy to reuse a theme when migrating to a new generator.

To achieve this, Stackbit defines Uniform theme model and then offers a tool called Unibit to convert it from this model to a theme specific for any supported generator. This means if a new generator is introduced in the future, you can use your old theme with it.

2. Selecting a static site generator

The second step is selecting your generator. No matter which one you choose, it will work with your theme and CMS seamlessly.

Stackbit currently supports the following static site generators:

Jekyll
Gatsby
Hugo

Two more are marked as coming soon: VuePress and Hexo. They are likely to add more generators in the future.

3. Selecting a CMS

With JAMStack, you don't have to use any Content Management System at all. Your articles are usually saved in your git repo in the form of Markdown files or a similar format. You can create and edit your content directly in your IDE.

However, usually, content creators are non-technical people, so you need to integrate some kind of CMS for them, so they can easily create and edit content using a nice and simple GUI.

As a third step of the project creation workflow, Stackbit allows you to choose one of the supported CMSs, which will be used to manage the content on your site.

If you don't want to use any CMS, you can skip this step. It is always possible to add a CMS later.

Stackbit currently supports:

Forestry
Netlify CMS
Contentful
DatoCMS
Sanity

Prismic is marked as coming soon.

4. Deployment

The last step is to select a deployment method. That means:

Selecting a git repository, where your project will be created
Selecting a service which will be used for deployment

As a git repository hosting, you can currently use GitHub, but GitLab and Bitbucket are coming soon.

As a deployment method, there is currently offered just Netlify. It is a great service, which I currently use for my blog, you can read more details about it in this post:

Migration to JAM stack and Netlify from WordPress

21 May, 2018

How and Why I migrated from WordPress to static JAM Stack site deployed on Netlify.

GitHub Pages and GitLab pages are going to be supported soon, as well.

Once you authorize your GitHub and Netlify access, you're done. A git repo is created for you, and the project is automatically deployed.

Dashboard

When you finish creating your first project, it becomes available on your main dashboard, where you can see and manage all the projects. You have a single place from which you can edit your settings, navigate to your site, CMS, or git repository.

But the dashboard is not the only place you can manage your site from. If you go directly to your site and are logged in to Stackbit, you can see a special Stackbit button, where you can manage the site directly without going to your dashboard.

Medium import

A few years back, Medium got very popular as a blogging platform. These days, with the recent changes, many people are migrating back from Medium. Hosting your own static site for your blog is a viable alternative.

With Stackbit, migration from Medium is fortunately effortless. There is a dedicated page, where you can upload your Medium export archive, and it will automatically create a new Stackbit project for you with your data.

DEV.to integration

Services such as Medium are no doubt convenient to use, and you can reach a much larger audience than on your own. There is one major drawback, though. You don't really own your content and your audience. When such service goes out of business or changes its pricing model, you lose your content and audience. It is much better to have your own site so that you can build a stable audience, and you're safe from any changes of third-party services.

It would be great if you could combine the advantages of both approaches. It turns out you can! With Stackbit and DEV.TO integration.

DEV.to is an excellent service, focused purely on developers, which lets you publish your content to reach a wider audience. It already offers you a possibility to automatically publish to DEV.to using your RSS feed. So you still have your content hosted on your site, and it adds a canonical URL to your original site, so you do not cannibalize your SEO.

Now with Stackbit, it is possible also the other way around. You can publish your existing DEV.to content to your Stackbit site.

Beta

Stackbit is already publicly available and functional, but it is still running in open beta. Not all the features may be final, and there are many more features and supported services to be added soon. Go ahead and check their blog periodically to stay informed about the new features.

Conclusion

Stackbit is a very powerful tool, which lets you create a fully functional JAMStack site with all the bells and whistles just in minutes using a simple wizard. The main disadvantage of JAMStack - the high barrier of entry and accessibility to only technical people applies no more. Go ahead and give it a try!

Comparing files and folders in IntelliJ IDEA

Fri, 25 Oct 2019 22:12:03 GMT

IntelliJ IDEA offers numerous ways of comparing files, folders and code snippets and even synchronizing folder contents.

Comparing project files

Let's say there are two similar files in your project, and you need to compare them line by line. With IDEA, that's very easy. Just select both files in your project window (holding Ctrl for multi-selection).

Now you have two options:

Right click one of the files and select Compare Files
Press Ctrl + D

Now the new window opens, which contains two panels, each with one file. This is very similar to diff in Version Control Systems such as Git.

Each difference is color-coded:

No coloring means the content is the same
Blue means changes on the same line
Green means new content
Gray means removed content

You can click the arrow icons » and « to apply a particular change from one file to another.

This comparison works for images, too, although you cannot see and apply individual differences.

Comparing with non-project file

Another case is when you need to compare a file from your project with another file outside of it.

The process is again very similar. Select a single file in your project window and:

Right-click one of the files and select Compare With...
Press Ctrl + D

The last step is to browse for an external file to compare with. Now the comparison is the same as in the example above.

Comparing with the clipboard

Maybe you have a file in your project, and you need to compare it with some external content, which is not saved as a file on your machine. Maybe it is a code snippet from the web, for example, from stack overflow.

First, you need to open the file from your project in your editor. Then copy to clipboard the snipped you want to compare (Ctrl+C).

Now you have two options. Either compare the whole file against the clipboard or just a selection. If you want the whole file to be compared, just right-click anywhere in the editor and select Compare with Clipboard from the context menu. If you want just a selection instead, select some fragment of the file first and then right-click as before.

Custom comparison

What about the case when you want to compare two non-file code snippets from external sources? You can do this too! Just run Find Action via Ctrl + Shift + A and then search for Open Blank Diff Window.

This opens a brand new diff window with both panels blank, so you can copy and paste both snippets to be compared.

Comparing with the previous local version of the file

Even if you're not using any Version Control system, IDEA stores historical versions of your local files. You can right-click in your editor and select Local history → Show history.

Here you can browse older versions of your current file and see the difference between the old and the current version and apply any changes if required.

Compare with VCS

If you're using a Version Control System, you have several more comparison options. For example, if you're using Git, you can go to VCS → Git or right click your editor and select Git. Now you can:

Compare with the same repository version: Compares the current local file with the version in your remote repository
Compare with branch: Compares the local file with the same file in a different branch
Show history: Compares the local file with its previous versions

Comparing Folders

The comparison works not only for individual files but also for the whole directories. The process is the same as for files - just select two folders in your Project window and press Ctrl + D or right click and Compare Directories.

Here you can see a list of all the files present in both or in either one of the directories. You can easily spot which files are present in just one folder and which in both. These in both, you can compare as usual.

Synchronizing folders

The directory diff tool is useful not only for spotting differences in both directories, but also for synchronizing changes. You can apply changes for individual sections of each file as usual. But you can also mark files present only in one of the directories to be either kept or synchronized to the other directory. You can change the desired action for each file in the * column. Once you are satisfied, you can hit either Synchronize selected or Synchronize all.

Netlify Analytics Review: Google Analytics alternative?

Fri, 11 Oct 2019 22:12:03 GMT

Zero-impact server-side analytics for your Netlify projects. Works even with adblockers.

Netlify Analytics

Netlify is a cool service focused on building and deploying your static and JAM Stack sites. If you're interested you can read more about the service in one of my previous posts:

Migration to JAM stack and Netlify from WordPress

21 May, 2018

How and Why I migrated from WordPress to static JAM Stack site deployed on Netlify.

One of the new features recently announced by Netlify is Netlify Analytics. In its purpose, it is similar to Google Analytics - gather stats about people visiting your pages. Unique visitors, pageviews, that sort of stuff.

Unlike Google Analytics, it does not rely on JavaScript to gather and send this data. Instead, everything happens on the Netlify servers. That has some advantages we'll discuss in a moment. Now let's see how the Netlify Analytics dashboard looks like.

That's it: just this one screen, no other sub-views per category of per various metrics. Netlify's philosophy here is not to overwhelm users with a lot of data and keep it simple. Still, the product is new, and there are more features to come. It will never be as feature-rich as GA, though.

Advantages

Unlike Google Analytics and other similar services, Netlify Analytics runs on the server-side, which has some nice implications.

Better performance

Since everything happens server-side, there is zero impact on client performance. You don't need to include any external JavaScript, parse and execute it and make any calls to an external service. Google Analytics script currently has 43.4 kb (although it is much smaller compressed). It may not seem as much, but it can make a difference on low-end devices and with poor network connectivity.

Works with adblockers

Adblockers are really popular these days. What's problematic, is that most of them also block analytics tools. You lose information on all of your visitors, who use adblockers. According to the following report from 2018, globally 27% of desktop users on average use adblockers. But that's just average. It goes as high as 42% in Greece! That's huge. It means that a huge portion of your traffic can go untracked. It can get even worse, depending on your target audience. Likely, more tech-savvy users use adblockers more often. If you have a developer-targeted blog like me, the percentage is going to be way higher than the broad average.

Works with Javascript disabled

Since Netlify Analytics doesn't rely on Javascript, it works even if a client has JavaScript disabled. In the era of React, Angular, and other JS frameworks everywhere, the percentage is very low these days. Still, it may be useful to capture these visitors as well (assuming your page can actually run without JS).

Historical data when enabled

The good news is that Netlify already collects analytics data for you, even if you don't have analytics enabled. You just have to pay to view it. Once you do, you'll be able to view historical data up to 30 days back. It may take some time to import everything, though, so don't expect to see everything immediately.

Error & Not Found pages

By its nature, JS-powered tools such as Google Analytics, can show you only valid pages. Since Netlify Analytics is server-side, it can also capture requests to non-existent pages and resources. This may be handy to detect broken links and other ismilar issues.

Simplicity

GA is a very powerful tool, but it may be intimidating at first, if you're not familiar with it. For casual usage, it may be too complex. Netlify analytics is very simple and easy to understand, which is good.

Disadvantages

Although Netlify Analytics has some powerful features, it has, currently, also some serious flaws. This is to be expected as the project is still fresh and not mature yet. According to Netlify, there are fixes and enhancement to many of the disadvantages currently on the roadmap.

Accuracy

Netlify Analytics promises improved accuracy because it can track even users without javascript, those who have adblockers, and even missing resources. It's true to some degree. The problem is that it currently also tracks visits from bots, which can greatly affect your stats and provide irrelevant data.

Let's compare my stats on Netlify vs Google Analytics to illustrate this:

Unique visitors: 44K vs 50K ⟶ + 13.6%
Page views: 57K vs 439K ⟶ + 770 %

The Netlify data is supposed to be higher as it also detects users with adblockers, but this looks like way too much and is likely because of the bot activity.

Fortunately, according to Netlify, it is something they are already working on, and hopefully, it will be fixed soon. Currently, however, your stats include a lot of irrelevant data from bot visits.

Limited date range

One of the most significant shortcomings is a limited history of your data. Currently, you can see only the last 30 days of user activity. You don't have any means of determining how is your traffic changing in the a long term. Did all these new articles bring enough traffic, or is it stagnant? How did your traffic rise over the past few years?

According to Netlify, the date range is likely to be increased in the future, but is it ever going to full history, which GA already offers? Is it much better to have 180 days instead of 30 if your site is running for years?

Limited functionality

The feature set of Netlify Analytics is so far very limited; it's just one screen, which we saw in the image above. That's it. And it's not likely to be anywhere near to what GA offers anytime soon. Or ever. There a list of features which are currently offered:

Total pageviews
Total unique visitors
Total bandwidth used
Pageviews over the last 30 days: chart
Unique visitors over the last 30 days: chart
Top pages by pageviews
Top resources not found by the number of requests
Top sources of traffic by pageviews
Bandwidth used over the last 30 days: chart

If it is good enough for your case, that's great. However, it's likely you need more. There's not drill down per page, region, or device. No bounce rate, time spent on-page, or session flow. No demographics about users. Not to mention custom metrics.

Price

The biggest downside is pricing. Adding analytics costs $9 per month PER SITE. This can quickly ramp up if you're running multiple different sites on Netlify. The price seems quite steep, considering the biggest competitor, Google Analytics, has many more features and is completely free. I can imagine running and developing such kind of service can cost a lot of money. However, for a user, there needs to be a strong justification to choose a $9 service with fewer features over a free, more powerful alternative. It doesn't mean Netlify analytics is bad, but the alternatives may be more compelling considering the cost.

Also, the $9 price is only for pages with less than 250K monthly pageviews. If you have more, they have custom pricing, and you need to contact their sales team.

Conclusion

Netlify Analytics is a nice service, which has some powerful features, because of the fact, that it is running completely server-side. That means better performance and tracking of a portion of your traffic, which would otherwise not be visible. The setup is effortless and straightforward, and it's nicely integrated with Netlify.

It is still a new product and I'm expecting it to evolve and mature over time. Hopefully, some pain-points, such as bot tracking, will be fixed soon, and the service will be even better.

As for the price, it may not be justifiable on its own, but you have to take into consideration that Netlify provides a cool service with a generous free plan, and this is a way to make some profit by an optional product. Even though analytics are not perfect yet, I expect it to mature, and I'll be happy to pay $9 as a way to support a company offering a great product (Netlify as a whole), while still using the free plan.

If you're not too keen on supporting Netlify, it may be a better approach to wait some time until the product is more mature.

As for now, I'll still be using Netlify Analytics. However, I cannot really ditch GA either as I also want to have historical data. This way, I lose the performance benefit, and the only real remaining advantage is tracking users with adblockers and disabled JavaScript.

JavaFX Tutorial: CSS Styling

Thu, 10 Oct 2019 22:12:03 GMT

How to style JavaFX components using good old CSS.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

Separating visuals

In the previous article about FXML, we learned how JavaFX achieves clean separation of concerns by dividing the user interface code into two parts. Components and their properties are declared in an FXML file, while the interaction logic is neatly separated in a controller.

Now there is a third part on top of this. FXML manages only what components are in your app, their properties, and how they are nested. It does not define the visuals of the component, though. That is - fonts, colors, backgrounds, paddings. To be honest, you can achieve it in FXML, but you shouldn't. Instead, visuals should be clearly separated in CSS stylesheets.

This way, your styling is independent and can be easily replaced or changed without affecting the rest of the application. You can easily even have multiple themes, which you can switch on demand.

CSS

You probably know CSS (Cascading Style Sheets) from the web, where it is used to style HTML pages. In JavaFX, this is very similar, although JavaFX uses a set of its own custom properties.

Let's see an example:

.button {
    -fx-font-size: 15px;
}

There are two essential concepts here. The first one is the selector. That's .button. This determines to which components the styling should be applied. There it is for ALL the buttons.

The second part is actual styling properties, which will be applied to all the components, which match our selector. Properties are everything inside the curly braces.

Each property has a specific value. In our example, we have a property -fx-font-size, which means how big the text will be. The value is 15px here but could be anything else we would desire.

To sum it up - we created a rule which says - all the buttons everywhere should have their text of size 15px.

Selectors

Now let's take a closer look at how selectors work in JavaFX. It pretty much the same as in regular CSS.

Class

Class in CSS represents multiple similar elements. For example, buttons or checkboxes. A selector, which should apply to all of the elements of the same class starts with a dot . followed directly by the class name. The convention is to separate individual words with a comma -. The following selector applies to all the elements with class label.

.label {
    // Some properties
}

Built-in classes

The good news is that all the built-in JavaFX components (such as Label or Button) have already a class assigned out of the box. If you want to target all the labels in your app, you don't have to add any custom classes to each of your labels. Each Label has by default label class.

It is easy to determine the class name from the component.

Take the name of the Java class of the component - eg. Label
Make the name lower-case
If it consists of multiple words, separate them by -

Some examples:

Label → label
CheckBox → check-box

When using such classes as selectors, don' forget to add .. That means the selector for the label class is .label.

Custom classes

If build-in classes are not enough, you can add your own custom classes to your components. You can have multiple classes separated by a comma:

<Label styleClass="my-label,other-class">I am a simple label</Label>

Or in Java:

Label label = new Label("I am a simple label");
label.getStyleClass().addAll("my-label", "other-class");

Adding classes this way does not remove the default class of the component (label in this case).

There is one special class called root. It means the root component of your scene. You can use it to style everything inside your scene (such as setting a global font). It is similar to using body tag selector in HTML.

ID

Another way of selecting components in CSS is to use the component's ID. It is a unique identifier of a component. Unlike classes, which can be assigned to multiple components, ID should be unique in a scene.

While classes are using . before the name in their selectors, IDs are marked with #.

#my-component {
  ...
}

In FXML, you can use fx:id to set the component's CSS id.

<Label fx:id="foo">I am a simple label</Label>

There is one caveat, though. This same ID is used to link to a component object declared in your controller with the same name. Since the id and the name of the field in controller need to match, fx:id needs to respect Java's naming restriction for field names. Even though the CSS naming convention dictates individual words separated by -, it is an invalid character for Java field names. For fx:id with multiple words, you need, therefore, to use a different naming convention such as CamelCase or use underscores.

<!--  This is not valid  -->
<Label fx:id="my-label">I am a simple label</Label>
<!--  This is valid  -->
<Label fx:id="my_label">I am a simple label</Label>
<Label fx:id="MyLabel">I am a simple label</Label>

In Java, you can just call the setId() method on your component.

Label label = new Label("I am a simple label");
label.setId("foo");

Properties

Although CSS used in JavaFX is very similar to the original web CSS, there is one big difference. The property names are different, and there is a lot of new properties specific to JavaFX. They are prefixed with -fx-.

Here are some examples:

-fx-background-color: Background color
-fx-text-fill: Text color
-fx-font-size: Text size

You can check the list of all the properties in the official styling guide.

Pseudo-classes

In addition to regular classes, which mark specific components, there are so-called pseudo-classes, which mark a state of a component. This can be, for example, a class for marking that a component has the focus or there is the mouse cursor over the component.

There's a whole bunch of built-in pseudo-classes. Let's take a look at Button. There are multiple pseudo-classes, you can use such as:

hover: mouse is over the button
focused: the button has the focus
disabled: the button is disabled
pressed: the button is pressed

The pseudo-classes start with : (e.g. :hover) in the CSS selectors. You need, of course, specify to which component your pseudo class belongs - e.g. button:hover. The following example shows a selector, which is applied for all buttons, which have focus:

.button:focused {
    -fx-background-color: red;
}

Unlike in CSS, which has just basic pseudo-classes for states like focus and hover, JavaFX has component-specific pseudo-classes, which relate to different states or properties of components.

For example:

Scrollbars have horizontal and vertical pseudo-classes
Cells have odd and even
TitledPane has expanded and collapsed

Custom pseudo-classes

In addition to build-in pseudo-classes, you can define and use your own.

Let's create our custom Label (inheriting from Label class). It will have a new boolean property called shiny. If it is true, we want our Label to have a shiny pseudo-class.

When the Label has the shiny pseudo-class, we'll set its background to gold:

.shiny-label:shiny {
    -fx-background-color: gold;
}

Now the class itself.

public class ShinyLabel extends Label {
    private BooleanProperty shiny;

    public ShinyLabel() {
        getStyleClass().add("shiny-label");

        shiny = new SimpleBooleanProperty(false);
        shiny.addListener(e -> {
            pseudoClassStateChanged(PseudoClass.getPseudoClass("shiny"), shiny.get());
        });
    }

    public boolean isShiny() {
        return shiny.get();
    }

    public void setShiny(boolean shiny) {
        this.shiny.set(shiny);
    }
}

There are several important parts here:

We have our boolean property BooleanProperty instead of regular boolean. This means it is observable, and we can listen to changes in its value.
We register a listener to be called every time the shiny value is changed using shiny.addListener()
When the value changes, we add/remove the shiny pseudo-class depending on the current value pseudoClassStateChanged(PseudoClass.getPseudoClass("shiny"), shiny.get()).
We add a custom class for all the labels shiny-label, instead we would have just the label class from our parent. This way, we can select only shiny labels.

Default stylesheet

Even if you don't provide any styles yourself, each JavaFX application already has some visual styling. There is a default stylesheet, which is applied to every application. It is called modena (since JavaFX 8, previously it used to be caspian).

This stylesheet can be found in:

jfxrt.jar\com\sun\javafx\scene\control\skin\modena\modena.css

Or you can check the file directly here. In the same directory, there is a whole bunch of images used by the stylesheet.

This stylesheet provides the default styling but takes the lowest priority compared to other types of stylesheets, so you can easily override it.

Scene stylesheet

In addition to the default stylesheet mentioned above, you can, of course, provide your own. The highest level on which you can apply styling is the whole scene. You can either provide that in your FXML:

<BorderPane xmlns="http://javafx.com/javafx"
            xmlns:fx="http://javafx.com/fxml"
            stylesheets="styles.css"
            ...
            >
  ...
</BorderPane>

Or in your Java code:

String stylesheet = getClass().getResource("/styles.css").toExternalForm();
scene.getStylesheets().add(stylesheet);

Note the toExternalForm() call. Scene expects stylesheet contents as a string, not the file, so we need to provide the contents of our stylesheet instead.

Parent stylesheet

In addition to having a stylesheet for a whole scene, sometimes it may be useful to have styling on layout level. That is - for an individual container such as VBox, HBox, or GridPane. The common parent of all layouts is Parent class, which defines methods for handling stylesheets on layout level. These styles apply only for the components in the given layout, not for the whole scene. Layout level styling takes precedence over scene level styling.

<HBox stylesheets="styles.css">
    ...
</HBox>

In Java, you need to load the stylesheet contents yourself, same as previously with scene:

HBox box = new HBox();
String stylesheet = getClass().getResource("/styles.css").toExternalForm();
box.getStylesheets().add(stylesheet);

Inline styles

So far, we've covered only cases of assigning an external stylesheet to a whole scene or layout. But it is possible to set individual style properties on the component level.

Here you don't have to bother with a selector as all the properties are set to a specific component.

You can provide multiple properties separated by semicolon:

<Label style="-fx-background-color: blue; -fx-text-fill: white">
  I'm feeling blue.
</Label>

In Java, you can use setStyle() method:

Label label = new Label("I'm feeling blue.");
label.setStyle("-fx-background-color: blue; -fx-text-fill: white");

Styling on component level takes precedence over both scene and parent (layout) styling.

Why to avoid them

Styling on component level may be convenient, but it is a quick and dirty solution. You give up the main advantage of CSS, which is separating styling from the styled components. You hardcode your visuals directly to the components now. You can no longer easily switch your stylesheets when needed, you cannot change themes.

Moreover, you no longer have a single central place where your styling is defined. When you need to change something across a set of similar components, you need to modify each of the components individually instead of editing just one place in your external stylesheet. Inline styling components should be therefore avoided.

Stylesheet priorities

You can provide styling on multiple levels - scene, parent, inline styles, and there is a default modena stylesheet. If you change that same property of the same component on multiple levels, JavaFX has a priority setting, which resolves what styles should be used. The list of priorities is - from highest to lowest:

Inline styles
Parent styles
Scene styles
Default styles

That means if you set the background color of a specific label both inline and on the scene level, JavaFX will use the value set in inline styles as it has higher priority.

JavaFX Tutorial: Advanced layouts

Fri, 04 Oct 2019 22:12:03 GMT

How to organize and position your GUI components in JavaFX application using advanced layouts.

In the previous article we covered some basic JavaFX layouts. Now it's time to go through the rest of the available layouts.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications

AnchorPane

AnchorPane is an interesting and powerful layout. It allows you to define anchor points to the components inside. There are 4 types of anchors:

top
bottom
left
right

Each component can have any combination of anchors. From zero up to all four. Anchor point also defines a distance.

Anchoring means that the component keeps the defined distance from a particular edge of the layout (e.g., TOP). This distance is preserved even on resize of the layout.

For example: anchorRight=10 means that the component will keep distance 10 from the right edge of the layout.

You can combine two anchor points, which are not in the opposite direction, to anchor your component to a specific corner of the layout.

Anchor TOP = 10, RIGHT = 10 means that the component will stay in the top right corner of the layout in the distance 10 from both edges.

In the example above, the size of each component stays the same on resizing. However, if you define anchor points in the opposite directions, you can make your component grow/shrink on resizing.

You can have various combinations like this:

LEFT+RIGHT resizes horizontally
TOP+BOTTOM resizes vertically
All 4 anchors mean both horizontal and vertical resizing

Defining anchor points in FXML is easy. In the following example, there are all four, but you can include none or only these which you want.

<AnchorPane>
    <Button AnchorPane.topAnchor="10"
            AnchorPane.leftAnchor="10"
            AnchorPane.rightAnchor="10"
            AnchorPane.bottomAnchor="10">I am fully anchored!</Button>
</AnchorPane>

Now let's look how anchoring is achieved in Java:

AnchorPane anchorPane = new AnchorPane();
Button button = new Button("I am fully anchored!");
AnchorPane.setTopAnchor(button, 10d);
AnchorPane.setBottomAnchor(button, 10d);
AnchorPane.setLeftAnchor(button, 10d);
AnchorPane.setRightAnchor(button, 10d);
anchorPane.getChildren().add(button);

GridPane

GridPane is a layout that allows you to organize your components into a grid. Unlike TilePane, which is adding components one after another, here you need to specify the coordinates of the target location in your grid when adding a new component.

<GridPane hgap="10" vgap="10">
    <Label GridPane.rowIndex="0" GridPane.columnIndex="0">First</Label>
    ...
</GridPane>

In Java, when adding a new component, we specify first the ColumnIndex (x) and RowIndex(y).

    GridPane grid = new GridPane();
    grid.add(new Label("Hello!"), columnIndex, rowIndex);

Spacing

By default, grid cells have no spacing. The components are directly next to each other, with no margins. Spacing can be defined separately for rows and columns - that is: horizontally and vertically.

hgap sets horizontal spacing (between columns)
vgap sets vertical spacing (between rows)

<GridPane hgap="10" vgap="10">
    ...
</GridPane>

Spacing defined in Java:

GridPane grid = new GridPane();
grid.setHgap(10);
grid.setVgap(10);

Spanning multiple cells

Components in GridPane can span multiple rows and/or columns.

A component with rowspan is expanding to the bottom from its original cell. A component with colspan is expanding to the right.

<GridPane>
    <Label GridPane.columnSpan="2"           GridPane.rowSpan="2"           GridPane.rowIndex="0"            GridPane.columnIndex="0">        Foo!
    </Label>
</GridPane>

In Java, there are two ways of setting row and column span. You can either set it directly when adding a component to the grid:

grid.add(component, columnIndex, rowIndex, columnSpan, rowSpan);

Or through GridPane:

GridPane.setColumnSpan(component, columnSpan);
GridPane.setRowSpan(component, rowSpan);

Sizing

Even though in the initial example, all the cells were the same size, it does not necessarily have to be the case. The sizing of grid cells is the following:

Height of each row is equal to the highest element in the row
Width of each column is equal to the widest element in the column

Column and row constraints

As mentioned, by default, the columns and rows are sized based on the components inside. Fortunately, you can have better control over how individual columns and rows are sized.

There are ColumnContstraints and RowConstraints classes, which are used for this.

You have basically two options. Either set percentage of available space for individual rows and columns, or you set preferred width/height. In the latter case you can also define preferred behavior when the columns and rows are resized.

Percentage

This is quite straightforward. You can set a percentage of the available space to be occupied by the given row or column. When the layout is resized, the rows and columns are resized as well to match the new size.

<GridPane>
    <columnConstraints>
        <ColumnConstraints percentWidth="50" />
        <ColumnConstraints percentWidth="50" />
    </columnConstraints>
    <rowConstraints>
        <RowConstraints percentHeight="50" />
        <RowConstraints percentHeight="50" />
    </rowConstraints>
    ...
</GridPane>

The same example in Java:

GridPane gridPane = new GridPane();

ColumnConstraints col1 = new ColumnConstraints();
col1.setPercentWidth(50);
ColumnConstraints col2 = new ColumnConstraints();
col2.setPercentWidth(50);
gridPane.getColumnConstraints().addAll(col1, col2);

RowConstraints row1 = new RowConstraints();
row1.setPercentHeight(50);
RowConstraints row2 = new RowConstraints();
row2.setPercentHeight(50);
gridPane.getRowConstraints().addAll(row1, row2);

Absolute size

Instead of defining percentage size, you can define preferred and minimal size. In addition to that, you can specify how the row/column should behave on resize. Columns are using hgrow property, and rows have vgrow.

These properties can have three distinct values.

NEVER: Never grow or shrink on resizing. The default value.
ALWAYS: When resized, all the elements with this value are either stretched to fill the available space or shrank.
SOMETIMES: These elements are resized only if there are no other elements with ALWAYS.

<GridPane>
    <columnConstraints>
        <ColumnConstraints minWidth="50" prefWidth="100" />
        <ColumnConstraints minWidth="50" prefWidth="100" hgrow="SOMETIMES" />
    </columnConstraints>
    <rowConstraints>
        <RowConstraints minHeight="50" prefHeight="100" />
        <RowConstraints minHeight="50" prefHeight="100" vgrow="SOMETIMES" />
    </rowConstraints>
    ...
</GridPane>

The same example in Java:

 GridPane gridPane = new GridPane();

ColumnConstraints col1 = new ColumnConstraints();
col1.setMinWidth(50);
col1.setPrefWidth(100);
ColumnConstraints col2 = new ColumnConstraints();
col2.setMinWidth(50);
col2.setPrefWidth(100);
col2.setHgrow(Priority.SOMETIMES);
gridPane.getColumnConstraints().addAll(col1, col2);

RowConstraints row1 = new RowConstraints();
row1.setMinHeight(50);
row1.setPrefHeight(100);
RowConstraints row2 = new RowConstraints();
row2.setMinHeight(50);
row2.setPrefHeight(100);
row2.setVgrow(Priority.SOMETIMES);
gridPane.getRowConstraints().addAll(row1, row2);

You can also specify maxHeight and maxWidth for individual rows and columns.

BorderPane

BorderPane is a layout with five sections:

Top
Bottom
Right
Left
Center

You can assign components to the individual sections of the BorderPane:

<BorderPane>
    <top>
        <Label>TOP</Label>
    </top>
    <bottom>
        <Label>BOTTOM</Label>
    </bottom>
    <left>
        <Label>LEFT</Label>
    </left>
    <right>
        <Label>RIGHT</Label>
    </right>
    <center>
        <Label>CENTER</Label>
    </center>
</BorderPane>

Now the same example in Java:

Label top = new Label("TOP");
Label bottom = new Label("BOTTOM");
Label left = new Label("LEFT");
Label right = new Label("RIGHT");
Label center = new Label("CENTER");

BorderPane borderPane = new BorderPane();
borderPane.setTop(top);
borderPane.setBottom(bottom);
borderPane.setLeft(left);
borderPane.setRight(right);
borderPane.setCenter(center);

Sizing

All the regions except the center have a fixed size. The center then fills the rest of the space.

Top and Bottom regions are stretched across all the available horizontal space. Their height is based on the height of the component inside.

Left and right fill all the available vertical space (except what's occupied by top and bottom). Their width is dependent on the width of the component inside.

The center has a dynamic size and fills the rest of the space not occupied by other sections. Let's look at an example:

What's next

Now when we know how to use various layouts, we'll cover how to style JavaFX components using CSS.

All posts in the JavaFX series

JavaFX Tutorial: Getting started
JavaFX Tutorial: Hello world
JavaFX Tutorial: FXML and SceneBuilder
JavaFX Tutorial: Basic layouts
JavaFX Tutorial: Advanced layouts
JavaFX Tutorial: CSS Styling
JavaFX Weaver: Integration of JavaFX and Spring Boot applications