# Getting Started with Application Themes

Creating a new Application Theme is not as daunting as it may seem. In general, we recommend all those intending to make styling changes to do so in a new app theme, not in the "Basic" theme. Changes made to the Basic theme risk being overwritten when Exago is updated.

In this guide we'll walk through the process of creating a new app theme, then demonstrate how to change images and css styles.

# Creating an App Theme

> IMPORTANT. Creating and editing app themes must be done in a TEST environment. Only once the app theme is finalized should it be added to a live environment.

> NOTE. App Themes are available in Exago versions 2016.3 and later.

Creating a new app theme could not be simpler. First, navigate to the Exago directory in your test environment. The folder ApplicationThemes should be present. Double-click to enter that folder.

In ApplicationThemes, you should see a Basic folder. This is the default Exago theme. Do not modify this folder. Create a new folder, and give it a name. This will be the name of your new app theme. We'll call our new theme "New".

Double-click on the new folder to enter it. Inside create two new folders with the names "Css" and "Images". (And optionally a "Fonts" folder).

...and, that's it. You're done! (Yes, it's just two empty folders; we'll explain in a bit).

To see the new theme in action, use your Admin Console or edit your config file to select the theme you just added. If you're using the Admin Console, you should see your new theme in the Application Theme Selection drop-down menu:

Config file: <csstheme>New</csstheme>

Then refresh your application. Ta-da! If you don't see any difference, that means it's working! Why is that? Well, all custom application themes automatically load the "Basic" theme before applying any custom styles. This way you don't have to maintain a folder full of copy-pasted images and css code from the Basic theme. Any images or css added to your app theme override the default style.

Now we'll discuss how to add some customizations to your new app theme.

# Customizing Your App Theme

So we have a new app theme, which is now essentially a blank canvas. Two basic types of changes we can make involve Changing Images or Changing Styles. We'll discuss easy ways to accomplish both in the following sections.

## Changing Images

The first thing we need to figure out when changing images is figuring out the filename for the image in question. Sometimes we can scan the image folder and identify it at a glance. However, this may not be simple for every image. A more precise way to identify application images is to use a Web Inspector tool, which is built into most modern web browsers.

This guide uses the Google Chrome Developer Tools, but the process should be similar for other browsers.

To get started, open Exago in your browser and navigate to a page containing the image you want to replace. Using Chrome, press F12, or Ctrl-Shift-I, or open the menu and select More tools > Developer Tools. A two-pane window will open up at the bottom of the browser tab.

Make sure the Elements tab and the Styles sub-tab are open. Press the Inspect button or Ctrl-Shift-C. This will temporarily turn your mouse cursor into an element inspector. Hovering over elements will display their css selector (this will be useful in the next section), and the size of the element in px. Then click on the image you want to identify.

Look in the Elements tab of the Web Inspector. The left pane shows you the actual html being rendered at the pointer location. The element highlighted in blue is what you've just selected. The right pane shows the styles for that element.

It should only take a glance to be able to determine the filename for the selected image. Look at the src property for the <img> element, which is underlined. The filename in this example is UserPreferences.png.

Now that we know the image filename, we know how to name our replacement image. Simply take our new image, and re-name it to UserPreferences.png, then copy it into the Images folder in our New app theme. (Make sure that the new image is the same size as the old).

Then refresh the browser:

###

And we're done!

### Image Defined in CSS

It may be the case where a selected image has no src property. This is because the image is being defined in the application css instead of in the html. If this is the case, look at the right panel's Styles sub-tab, and scroll down until you find a background-image style.

The url property for the style contains the filename. In this example, the filename is MainCompanyLogo.png.

If this is the case, then replacing the image file is not enough to apply the change. We also have to add a custom css style for the image. Write down the full css selector which contains the background-image property. In our example:

    .wrNoSVG .wrMainCompanyLogo {
       background-image:
          url(Images/MainCompanyLogo.png);
    }

Then all we have to do is copy this into a css file in your app theme. See the next section for instructions on adding css.

> NOTE. We have provided an icons.css file in the Custom Theme Template (available here), which contains the css overrides for all applicable images. If you'd prefer to avoid the above steps, copy this file directly into your css directory.

## Changing Styles

Any css added to an application theme overrides any "Basic" css for the selected elements. The question is, how do we figure out what selectors to use for specified elements.

Once again, the solution is to use a Web Inspector. Recall what happens when we hover over an element using the Inspect tool:

You can see a tooltip pop up which shows us the element type, id, and class. This works for all elements on the page, not just images! The tooltip has three main parts:

- type in purple (before the # symbol)
- id (name) in orange (after the # symbol, but before the . symbol)
- class in blue (after the . symbol)

We recommend only using the class selector.

Additionally, if you click on the element using the Inspect tool, looking in the Styles window in the Developer Tools shows you the full list of css properties that currently apply to that element.

To add custom css, navigate to your app theme folder, and open the Css folder. Create a new text file, with any name you like, with a .css file extension.

Then open your file in a text editor, and add your custom styles.

Save the file, then refresh your browser to see the changes applied.

# Custom Theme Template

A template for custom Application Themes is available for download here. Simply extract the directory into your ApplicationThemes folder, making sure that CustomTheme is the top-level folder, and within it Css, Fonts, and Images folders. Then re-name CustomTheme to a name of your choice.

The template includes an icons.css file which contains overrides for all css-defined images. Including this file will allow you to skip manually looking up each image's selector.

# Additional Notes

w3schools is an excellent resource for learning more about how to use css.