Development on a fast moving Web

Web development is full of passion. It’s a big thing that moves fast, where new technologies, new frameworks and new tools are created on a daily basis by individuals, groups and corporations, all striving to create better things. Web development is also full of debates, because of all of these tools, speed and pride.

As Web developers, it’s hard to stay afloat, to keep pace with all of these new shiny toys. We tend to see the big picture. The Web. Then, everything that gravitates around it. It’s really close to our job, but yet, that’s not exactly it. We create websites and applications. They all live on the mighty Internet, but rather than seeing all of this as a whole, we need to look closer, and see all of these thin layers, all interacting together. Most layers don’t need to be in a constant novelty war. Our job needs to evolve, but not that fast, not on everything, and surely not daily.

I like to think of Web development as three levels of abstraction all tightly living together: Standards, Technologies and Tools. Continue reading “Development on a fast moving Web”

Styling Chosen

Using libraries like Chosen is a good way to simplify your code. Otherwise difficult tasks can be completed in a matter of seconds. The main problem we find with libraries though is that their default styles almost never blend well with our own designs, in terms off color, size, shape or something else. Following up on Olivier’s blogpost about how to set up and use Chosen, we will try to fix that styling problem, step by step. If you prefer to read some code instead, have a look at the final application repository.

The basics

Styling Chosen can be achieved by overwritting some classes or simply providing a new stylesheet.

As shown in the default resources file for Chosen, there are 3 stylesheets that can be easily swapped to match your needs :

Chosen also uses a set of icons that you can change, to uzs GSSS Mixins instead.

Changing colors

Creating a custom stylesheet

In this first example, we will create a dark style for Chosen.

Screen Shot 2015-11-03 at 2.37.22 PM

We will copy the default colors.gss, create a new file with it in the CSS resources folder of our project, and call it chosenDarkColors.gss. We will fine tune the colors later, but to be sure that we are loading the new stylesheet, we should change at least one variable. Giving the #000 value for the CHZN_C_PRIMARY variable will do the trick.

Don’t forget to keep the @provide 'chosen-color';, otherwise it will crash.

Creating the associated resources file

In order to make our Chosen widgets use the new colors, we need to provide the widgets with a resources file that will make use of this new stylesheet, instead of the default one.

We only need to mimic the default resources file for Chosen, swapping the color.gss for the one we created, and providing the default files for the rest, using relative paths.

This new resources file then need to be loaded in the application via the ResourceLoader.

Loading the custom style

Now that we have our custom stylesheet and it is loaded into the application, it’s time to tell our Chosen widgets how to use all of this.

In the view file where the widgets are declared (HomeView.java in this example), we will start by creating a variable containing the link to the newly created resource. Then, we will create the ChosenOptions object for our widgets (if it’s not already done) and pass it the new resources. And that’s it!

Go ahead and style! The hardest part – and I can’t help you with this – is choosing the right combinations of colors!

Changing the default style

You can use the same process seen previously in Changing colors to change anything defined in chosen.gss and mobile.gss.  Even better, you can overwrite only the part you want, so you don’t have to duplicate the whole stylesheet.

Conclusion

Styling Chosen is not that hard, in fact it can even be fun! I created an open project on Github with the completed dark style that we started working on (it is an example of the custom stylesheet approach) and, as a bonus, were are including a second color scheme called Unicorn style (you will have to run the application to see it in action).

Have fun styling!

Frontend Style Guide

Since my very first days at Arcbees, I’ve been coached in code styling. I always had my own way of writing code, but never did so using strict rules. Following a pre-defined structure for my CSS, like writing properties in a specific order, was kind of annoying at first. I had to print the CSS property order and always refer to it, so my CSS stayed consistent with Arcbees’ styling conventions.

However, it only took a few days before I switched from resisting this practice to embracing it. The power of following a structured approach became clear, and I wanted more! ArcBees followed a very rich set of code styling conventions for Java files, but there were fewer conventions for writing CSS and HTML, except for the Rule of arrangement mentioned above. As a new convert believing strongly in the value of conventions, I began reading a lot about front-end best practices and style. The result of this research was ArcBees’ very own Frontend Style Guide.

What is it and what it does

A frontend style guide is a collection of guidelines to apply when writing CSS and HTML. One of its main purposes is to provide a common syntax and vocabulary for a project. Rules are created to ensure cohesion in the code, to ease maintainability and to construct a common and familiar structure for the team to work on.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it.
– Google HTML/CSS Style Guide

When your company consistently follows one style guide, you can jump into the middle of a new project you did not help start, and soon become an active contributor. The new project will feel familiar enough to work on because it follows the same rules and structure as all your other projects.

Following a style guide will also make it much faster to find elements. You will not have to guess where a specific element is. With ordering rules, you will know at a glance if a specific type of property is present inside your CSS element or not.

What we did

We started by analyzing how we were coding most of the time, both to reveal patterns that we were repeating, and also to illuminate practices that changed from time to time. We then had a look at what people in other companies do, and why. We merged all of these observations together to create our own Frontend Style Guide.

Here’s is a quick overview of some guidelines we developed :

HTML

  • Soft tabs, 4 spaces
  • Nested elements should be indented
  • Only use lowercase on HTML element names, attributes and values (except for text)
  • Don’t add values on boolean attributes (disabled, selected, checked …) : <input disabled=”disabled” type=”text” />
  • Each page should have its own <title>

Read the complete HTML Style Guide.

CSS

  • Put spaces before { in rule declarations
  • Use shorthand hex values, when possible. Use #fff instead of #ffffff
  • Avoid specifying units for zero values. Use margin: 0; instead of margin: 0px;
  • Properties are grouped by categories :
    • Typography, color and background
    • Display
    • Positioning
    • Visual and animation
    • Others
    • Mixins
  • Avoid over-qualified selectors. Use .widget_link instead of a.widget_link
  • Class names should be human readable, communicating useful information. Use structural and purposeful names over presentational ones
  • Place media queries as close to their relevant rule sets whenever possible. Don’t bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future.

Read the complete CSS Style Guide.

Create your own

You should definitely create your own style guide, adapted to your needs, and try to stick to it as much as possible. Feel free to start from our Frontend Style Guide if you want a structure to play with. You should also check out other great style guidelines available online, such as the following :

Have fun coding!

GWT Theo : GSS variables, theme file, icons and style guide made easy

So say you have a beautiful GWT application that uses GSS. Smart developer that you are, you did this using a theme file to easily manage your variables, in order to speed up your coding and ensure visual consistency across your screens. Now it’s time to automate things with GWT Theo!

GWT Theo is my adaptation of the powerful Theo set of Gulp plugins to automate theme creation. It has been stripped down a lot and tweaked to meet the specifics requirement of GWT. It will create your Java classes for each set of variables (fonts, colors, sizes, …) and your unique theme file, regrouping all those elements. It will also generate a style guide based on your variables for quick reference . Last but not least, it will facilitate custom icon integration (currently only supporting icon sets from Icomoon).

There’s a repository with a working project available on Github and a live application just here. Have a look at the style guide, you will fall in love! This blog post walks you through how to use GWT Theo.

Importing GWT Theo to your project

Let’s start by cloning the GWT Theo repository at the root of your application (at the same level of your src repository).

git clone https://github.com/ArcBees/gwt-theo.git

You will then need to update the gulpfile.js in order to match your application’s paths. On Arcbees’ website, it would look like this :

Once it’s done, you can give it a try and run gulp in your terminal in the GWT Theo folder. You will need Gulp installed on your computer. Default files should be generated inside folders specified in your gulpfile.js. The default Colors.java file will look like this :

Using the generated theme file

Once your files have been generated, you can bind the theme with your GSS files. All you need to do is to locate a GSS file you’d like to power-up with your theme, making it possible to use your custom variables inside of it, and providing the theme.gss in it’s source.

In my case, my source declaration for my style.gss file is in my AppResources.java file. Don’t forget to require the theme in your GSS file, and that’s it! You can now use all of your variables :

Custom variables

By default, GWT Theo comes with 3 files for variables : colors, fonts and sizes, located inside the theme-properties folder. You can add more, of course, or remove anything that you won’t need. Variables are declared in a JSON file with a default structure looking like this :

  • global [object] : Definition for this set of variables
    • type [string] : The variable type (this will influence the layout of the style guide)
      • color [option for type] : Used for colors
      • size [option for type] : Used for string variables
    • category [string] : Defines the category, and creates a section in the style guide
    • classname [string] : The class name for the file that will be generated from this set of variables
    • title [string] : ?
  • props : Definition of your variables
    • title-* [object, optional] : Everything starting with “title-” will be converted into a title in the style guide. Must be unique (“title-foo”, “title-bar”).
      • value [string] : Your title
    • * [object] : The name of your variable
      • value [string] : The value of the defined variable
      • comment [string, optional] : For variable of size type, a comment about that variable

Adding or removing a set of variables

Variables files are loaded from the theme.json file. You can remove or add a new set from here.

Custom icons

Using custom icons in your application is fun, but can be a real pain with GWT. You need to declare a lot of stuff in order to make it work. GWT Theo can help you with that, but it currently supports only one way of doing it.

Generating everything

  1. Select icons from Icomoon. These can be predefined icons from various packs available on Icomoon, or you can create your own by uploading svg files.
  2. Once you have made your choices, generate your font (bottom right).
  3. Before downloading the package, open the Preferences (top left) and :
    1. Rename the font name to “icons”
    2. Rename the class prefix to “icon_”
  4. Download the package.
  5. Extract it.
  6. Inside of your GWT Theo folder, create an theme-files folder and paste your extracted icons folder into it.
  7. Now, inside GWT Theo’s gulpfile.js, after the gwt variable (around line 29), add this one, and don’t forget to update the path to match your application :

If you run gulp now, it will create the required ThemeResources.java and icons.gss files :

Using custom icons in a view

To use your custom icon set in a view for the first time, you will need to inject it into your Resource Loader :

You can now use it in any of your views :

In a project that is always evolving, where you add adding new custom fonts often, this process will save you a lot of time! New icons to add? Generate a new font, dump it into the theme-files folder, gulp it, and voilà!

The style guide

GWT Theo will also create a style guide for you. You can define it’s path in the gulpfile.js. The default path is src/main/webapp/_theme-guide, which means that you can access it from your application at : your-application-url/_theme-guide/index.html.

The style guide will help your team quickly see predefined variables for your GSS files, and it will also help them spot the icons that they can use, if you have added some.

Conclusion

GWT Theo is still a work in progress and a lot could be added. Nevertheless, it already has the ability to save you precious time. Never forget that these kinds of tools should suit your own workflow and development needs, so feel free to tweak GWT Theo as much as required!

Managing your CSS (GSS) files with variables and a theme

My previous article showed you how to use CSS inside your GWT application. Today, we will introduce the concept of variables, and show you how to manage them effectively using theme files.

Variables

One of the best examples of variable use in CSS is probably color management. If your application has a default blue color, let’s say #2054e8, and it is used in multiple places, you will need to remember this particular color code every time you specify that color. Then if you decide to make your default color the lovely #f31ae5 shade of pink, you will need to do a find and replace across your whole project, and hope that everything went well.

All these hassles can be avoided if you use variables for your colors, so let’s do that!

Creating the Colors file

We will create Colors.java in src/main/java/com/company/project/client/resources.

We will discuss variable naming conventions later. Right now, you only need to understand that we can define a variable, like C_PRIMARY, and assign it a value, such as our initial shade of blue #2054e8.

The main purpose of this file is to contain all color values in the same place. It will then be easy to replace them later, and create different themes for our app.

Creating the associated GSS file

This is where we start to feel the real power of GSS over regular CSS files. After compilation, GSS files output basic CSS, transforming variables into the values associated with them.

In order to easily use our variables, we need to define them in a file. We will name that file colors.gss and put it into src/main/resources/com/company/project/client/resources/css.

We define variable names, and point them to the associated variables inside Colors.java.

The most important part is the very first line: @provide 'colors';

We are providing this file with a name that we will be able to import later on, making the variables defined in this file accessible in other contexts.

Binding it with your default resources style file

Before we can use this file, we need to supply it to our style’s resource file. My default style file is named style.gss and it uses the AppResources.java resource file, located in src/main/java/com/company/project/client/resources.

You can probably guess what you’ll find in this file:

We can see that we are using style() with the file located at css/style.gss. We need to add the color.gss to @Source, so it’s accessible. Instead of a string, we need to pass an array of strings, pointing to the desired files.

Note that we need to declare colors.gss before style.gss. Otherwise, style.gss will try to load the colors.gss file, but it will not yet be defined, causing an error.

Using variables inside of the style file

Remember when we defined @provide 'colors'? It is now required inside style.gss. Once that’s done, you will have access to your variables!

Structure

You can define variables for a lot of things beside colors, like sizes and fonts. You could decide to create a variables.gss file and add all your variables there, but this can pose a problem as your application grows. I prefer to structure my files by what they do, giving each set of variables their own file:

// src/main/java/com/company/project/client/resources/variables
    -> Colors.java
    -> Fonts.java
    -> Sizes.java

// src/main/resources/com/company/project/client/resources/variables
    -> colors.gss
    -> fonts.gss
    -> sizes.gss

This way, if you only need to use Colors inside of a specific style sheet, you can import them alone. Variable types become more modular.

Naming Conventions

As variables are not prefixed with any symbols, it helps to write them in uppercase. That way it’s easy to spot them in your CSS.

I also like to prefix them with a single letter that represents the type of variable that it is.

- Colors.java   -> C_VARIABLE_NAME (C_PRIMARY, C_BACKGROUND, C_TEXT ...)
- Fonts.java    -> F_VARIABLE_NAME (F_PRIMARY, F_SECONDARY_BOLD ...)
- Sizes.java    -> S_VARIABLE_NAME (S_SECTION_PADDING, S_LINE_HEIGHT ...)

Give your variables meaningful names, something that you will be able to remember and understand upon reading. Describe the purpose of the variable, not its value.

For example, F_PRIMARY is the primary font used inside the app, the most common one that will be almost everywhere. I find the use of primary / secondary easy to remember. It has a strong meaning, and it’s about what the variable is used for, and not about the value held by the variable. A bad example would be F_ARIAL for the same variable with the same purpose. It’s bad because if, in the middle of the project, you decide to change the main font from Arial to Helvetica, you will need to refactor the name of your variable. This is what we are trying to avoid.

Instead of C_RED for an error message color, go for C_ERROR. Or even better : C_STATE_ERROR. You will be able to manage your state colors easily, like C_STATE_SUCCESS and C_STATE_DEFAULT without worrying about the color it is.

Theme

The problem

If you create different variable files, you gain the ability to only load the ones you want. This is both good and bad. If you need several variable types, you have to specify each one of them inside of your resource loader, and then require them in your GSS file. This can quickly become annoying, and it makes your code harder to maintain.

As you can see, if you have multiple GSS files, you need to include required variables inside each of those files. And if you need to add another variable set, or remove one, you will need to go inside each of your Resource and GSS files and adapt them accordingly. And that sucks.

The solution

Faced with the above problem, you might think going back to having just one Variables.java file and a variables.gss file is not a bad idea after all. But we can have our cake and eat it too. We can keep the separation in our Java files and have only one GSS to rule them all. This way, variable files will remain modular, and yet we will still have only one file to require in each GSS file that need to access variables. If we need to change the structure, like adding a new subset of variables, we will only need to update one file, and that’s all!

I call this super GSS file theme.gss because it will be used to produce different themes, but you could name it variables.gss and it would still be totally accurate.

With this new method, things are now easier to maintain:

As the constants’ values are stocked in Java files, these constants can be modified easily. With this technique, it is now super easy to create different themes that can be user-based or changed at compile time.

Updated Structure

Using a theme file, my structure now looks like this:

src/main/java/com/company/project/client/resources/
    -> elements/
    -> pages/
    -> theme/
        -> Colors.java
        -> Fonts.java
        -> Sizes.java
    -> AppResources.java
    -> ResourcesLoader.java

src/main/resources/com/company/project/client/resources/css
    -> elements/
    -> pages/
    -> style.gss
    -> theme.gss

Tips

A variable will output the string of text inside of it into your CSS. Sometimes, you will need a variable to output more then one set of properties. You can do so this way:

Can you spot the trick in F_PRIMARY_BOLD? The variable is defining the font-family, closed with the semicolon ;, then define the font-weight, without a closing semicolon ; because the closure will be handled in the CSS.

Conclusion

You now understand the true power of variables. When used with a theme file, the management of your application becomes a breeze. Things can be made even easier, using a tool to manage the generation of your theme and the associated files. But that, my friends, is a topic for another blog post.

 

12

Getting started with CSS (GSS) in GWT

GWT can be hard to tackle at first, especially if your experience is entirely in front-end web development. You may be an HTML and CSS ninja, but not much of a Java wizard. This tutorial introduces how style sheets are used in GWT. I will not explain how to create a new GWT project, and will assume that you have an application you can run. That will let us focus on style sheets in GWT.

Once completed, don’t forget to have a look at the second part : Managing your CSS (GSS) files with variables and a theme.

From the beginning

If there is no style sheet inside of your application, or if you want a rough understanding of how it works, here’s a small step-by-step guide to add your default CSS file. Note that your application might be using a different folder structure than my example program, and that you will have to replace com/company/project to match your project.

The CSS file

We will create our initial CSS file into src/main/resources/com/company/project/client/resources/css and will name it style.gss. That’s right, .gss and not .css, as GSS files are like CSS files, but with more power. And we always want more power, don’t we?

We should add at least one line in our file, so we know that it’s working. Let’s use :

body { background-color: pink; }

At this point, it should not be working yet.

The Resource file

We then need to create the resource file that will be the bridge between your GSS file and your Java classes. This is because GWT will obfuscate class names on compliation, so this file will handle the links between the obfuscated names and classes inside of your GSS file.

Let’s create AppResources.java inside of src/main/java/com/company/project/client/resources

The code inside of it goes like this:

The Resource Loader file

We now need to setup the loader file to, well, to load everything inside the application.

Once again inside src/main/java/com/company/project/client/resources, create a file named ResourceLoader.java, containing :

The ensureInjected() is the important part here, as it will inject your CSS into the DOM.

Don’t forget to bind this file inside your ClientModule, probably located at src/main/java/com/company/project/client/gin/ClientModule.java

Activate GSS

GSS has been included in GWT since version 2.7, but is not enabled by default. To enable it, you need to add one line of code inside your GWT module. Mine is located at src/main/java/com/company/project/AppModule.gwt.xml and looks like this:

Voilà! If things went well, your application should build and run, loading your style.gss file in the process. Don’t worry if it fails, as you might have your application structured in a different way than shown in this tutorial. If you take time to read compile errors, you should manage to make it right. If you don’t, but have a backend dev near you, it’s always good to ask for help.

Using classes

One of the most confusing thing at first while working on GSS files in GWT is that you will need to declare your classes inside of your resource file to be able to access them.

Let’s add some classes into our style.gss file :

We then need to adapt the resource file accordingly:

Congratulations! You can now use you classes inside your views (you know, the files ending with .ui.xml) and even with your Java files.

We will first need a view. The file that we will be working on, aka ApplicationView.ui.xml, looks like this:

In order to use our classes, we will need to import the desired resource into the view :

 

We can now call the required classes using resources.style.name_of_my_class

In the precedent view, the final code would be :

You should know that Java uses the CamelCase naming convention, and that hyphenated class names using “-" will not compile. In order to make it work, you will need to use @ClassName inside of your CssResource:

Structure

It’s good to split your CSS into multiple files. It will be easier to maintain and understand, and will help you think in blocks and structure your classes accordingly; rather than having only one CSS file that does everything, but where you are not sure what that everything is.

A structure that I like, (but feel free to adapt it), is this one:

/resources
    /css
        /elements               // -> Elements that you reuse here and there
            section.gss
            form.gss
            anyElement.gss
        /pages                  // -> Pages related style
            login.gss
            contact.gss
        style.gss               // -> Your main style

Working with multiple GSS files

While working with multiple GSS files, you have two options: you can create a resource file for that GSS and include it only in views that will need it, or you can declare multiple GSS files into the same resource.

One resource file per GSS

It might sound easier to stack everything into the same resource file, but as with CSS files, it’s always better to break your code in blocks. If you have a contact.gss file that will only be used inside of your contact.ui.xml, you should create a dedicated resource for that. And I’d guess that you would also need your default style inside that view.

Multiple GSS files in the same resource

Let’s say you have a small application with only 3 pages: homepage, services and contact. For each page, you created a corresponding GSS file (homepage.gss, services.gss and contact.gss).

You could create one resource file for each, like in the previous example. You could also create one resource file to rule them all, named PageResources.java.

You will need to update your ResourceLoader.java accordingly:

Now, you can include the PageResources in each of your pages. It will give you access to every interfaces in it (homepage, services, contact).

Using images

If you want to use images inside of your GSS file, you will need to declare them as an ImageResource. Your image will need to be inside your resources folder, and like your GSS files, it’s always a good thing to create a proper folder structure in order to maintain control.

Conclusion

CSS with GWT is not an easy task at first, but after mastering the basics, you can regain your status as a front end ninja in GWT-land. Find the workflow that suits your need, structure your files and don’t forget to have fun!

In my next post, I will teach you how to leverage the real power behind GSS and simplify your life, using variables and a theme file. Stay tuned!

 

14