Working with Resources

An XMLUI application, being a web application, can use static resources such as images, icons, fonts, etc provided by the application developer. The XMLUI framework is then able to load these resources and use them seamlessly without the need to define how to load and manage these resources.

Adding Resources to a Project

The following guide will walk you through adding different kinds of resources to your application and also how to use them.

The resources Folder

Resources are generally stored in the resources folder of an XLMUI project, similar how regular websites store static resources in their public folder.

The first step of adding static resource files to your XMLUI application is moving or copying relevant files such as images to this folder. Here is an example of how the folder looks like for a simple project.

Using Resources Directly

After adding the files you wish to use, you can opt to refer to them directly from code. This is a fast way to add any static files to your project:

<App
  name="Tutorial"
  logo="resources/custom-logo.svg">
  <AppHeader>
    <H2>Using Resources Tutorial</H2>
  </AppHeader>  
  <Image 
    src="/resources/breakfast.jpg" fit="contain" 
    width="240px" />
</App>

Configuration File

The other way you can refer to resources in your application code is by telling the application where to look for resources and what their handle should be. This is done in the project configuration file called config.json in the project root.

Continuing with the example in the The resource Folder section, the configuration object in the file gets a resources entry which looks like so:

{
  "name": "Tutorial",
  "version": "1.0.0",
  "resources": {
    "favicon": "resources/favicon.ico",
    "custom-logo": "resources/custom-logo.svg",
    "icon.empty-folder": "resources/empty-folder.svg",
    "breakfastImg": "resources/breakfast.jpg"
  }
}

Using Resources

Finally, you can access newly added resources by their handles defined in the configuration object.

<App
  name="Tutorial"
  logo="custom-logo">
  <AppHeader>
    <H2>Using Resources Tutorial</H2>
  </AppHeader>  
  <Image src="resource:breakfastImg" />
</App>

A number of things to note here:

• Icons need to be prefixed with icon. in order for the framework to correctly identify them (as in the case of "icon.empty-folder").
• When setting a source for an Image component and the source is a resource with a handle, the handle name needs to be prefixed with resource: in order to resolve the file location
• The App component automatically loads resources identified by the logo and logo-dark handles, thus setting its logo property is optional.

Themes and Resources

Resources can be defined in different scopes: either they are global or are scoped to a specific theme. Themes can have their own resources in their respective theme files.

See the article discussing Theme object structuring to find out more.

Overriding Existing Icons

The XMLUI framework has a built-in icon library that can be accessed via the Icon component. These icons ship with the framwork but it is possible to replace predefined icons as you see fit.

In the example below, an icon with the name home already exists in the icon library but is overridden by the new home.svg file.

{
  "name": "Tutorial",
  "version": "1.0.0",
  "resources": {
    "icon.home": "resources/home.svg"
  }
}

<App>
  <Icon name="home" />
</App>

Loading Fonts

It is also possible to load different kinds of font families in the configuration file and theme files. There are two ways to go about loading and using fonts.

If you need more information on working with themes before continuing, see this article.

Loading from Folder

The first method is placing font files into the resources folder and referencing those fonts. Fonts contained in font files are automatically added to the project, so you only need to reference them in the config file or theme file.

You may have a font file called "my-font.woff2" in the resources folder like so:

This file contains the "My Font Family" font family, which can be referenced in a theme file:

export const myTheme: ThemeDefinition = {
  name: "My Theme",
  id: "myTheme",
  resources: {
    "font.myFont": {
      fontFamily: "My Font Family",
      fontWeight: "400",
      src: "resources/my-font.woff2",
    },
  },
  themeVars: {
    // ...
    "fontFamily": '"My Font Family", "Helvetica Neue", Arial, Verdana, sans-serif',
    // ...
  }
}

Loading from a CDN

The second method of working with font resources is to load them from a CDN. In this case, you have to specify the CDN URL from where to fetch the fonts in the configuration file:

export const myTheme: ThemeDefinition = {
  name: "My Theme",
  id: "myTheme",
  resources: {
    "font.roboto": "https://fonts.googleapis.com/css2?family=Roboto&display=swap"
  },
  themeVars: {
    // ...
    "fontFamily": 'Roboto, Helvetica, Arial, sans-serif',
    // ...
  }
}