Skip to main content

Extending Web Styles

Workings of web-styles expansion-resource​

The web-styles introduces an additional expansion step which copies directories packaged in the web-styles to a directory in the expanded application.

There are 2 distinct directory types which are included:

  • web-resource: Contains basic web resources, such as js and html files. They are included in every application
  • layout-resource: Contains css and html files, necessary to create a specific layout. They are only included if the application has been configured with a layout-style with the same name.

These directories have been packaged together with the web-styles jar, but external expansion-resources can add additional web and layout-resources.

Configuration​

The resource directories are registered in xml files. The configuration of the web-styles looks as follows:

src/
  main/
    resources/
      web/
        meta/
          webstyles/
            _data.xml
            layoutResources.xml
            webResources.xml

The _data.xml file is a data-resource file, which adds the layoutResources.xml and webResources.xml file as data-resources:

<dataResources>
  <dataResource>
    <path>web/meta/webstyles/layoutResources.xml</path>
    <elementTypeCanonicalName>net.democritus.expander.webstyles.resource.LayoutResource</elementTypeCanonicalName>
  </dataResource>
  <dataResource>
    <path>web/meta/webstyles/webResources.xml</path>
    <elementTypeCanonicalName>net.democritus.expander.webstyles.resource.WebResource</elementTypeCanonicalName>
  </dataResource>
</dataResources>

Note that these paths are relative to the src/main/resources/ directory. This is because they represent classpath locations. By adding them to the resources directory, we make sure they are packaged in the jar.

The layoutResources.xml and webResources.xml files contain the data that points towards the different resource directories:

<!-- webResources.xml -->
<webResources>
  <webResource name="common">
    <path>web/common</path>
  </webResource>
</webResources>

<!-- layoutResources.xml -->
<layoutResources>
  <layoutResource name="nsxbootstrap">
    <path>web/layout/nsxbootstrap</path>
  </layoutResource>
  <layoutResource name="nsxskeleton">
    <path>web/layout/nsxskeleton</path>
  </layoutResource>
  <layoutResource name="primeRadiant">
    <path>web/layout/primeRadiant</path>
  </layoutResource>
</layoutResources>

This means that if an application specifies nsxbootstrap as layoutStyle (which is the default settings), the expansion step will copy the content of web/common and web/layout/nsxbootstrap. (These are paths relative to the root of the jar)

Structure of a web or layout-resource directory​

Each resource directory in the web-styles has the structure <resource-root>/<technology>/<html|js|...>/<file> E.g. the common web-resource directory:

src/
  main/
    resources/
      web/
        common/
          knockout/
            html/
            js/
            images/
            ...

The expansion step will copy the content of each technology directory that is relevant. E.g. if there were files for angular, this would only be copied if the angular technology was added to the application.

Files that should be copied regardless of technology can be added to the 'technology' common.

Adding custom web or layout-resources​

Let's say we want to construct our own layout-style called fancy.

First we create a new maven project with the expanders-maven-plugin to generate the expansionResource.xml. We also add a dependency on web-styles to make sure the style is used with the correct web-styles version:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <artifactId>fancy-layout</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <dependencies>
    <dependency>
      <groupId>net.democritus</groupId>
      <artifactId>web-styles</artifactId>
      <version>2024.8.0</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>net.democritus</groupId>
        <artifactId>expanders-maven-plugin</artifactId>
        <version>2024.7.0</version>
        <executions>
          <execution>
            <id>expansionResource</id>
            <goals>
              <goal>expansionResource</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Next, we add the necessary configuration to the resources directory. By adding it to resources, we make sure the configuration files are packaged into the jar file.

src/
  main/
    resources/
      web/
        meta/
          fancy/
            _data.xml
            layoutResources.xml
<!-- _data.xml -->
<dataResources>
  <dataResource>
    <path>web/meta/fancy/layoutResources.xml</path>
    <elementTypeCanonicalName>net.democritus.expander.webstyles.resource.LayoutResource</elementTypeCanonicalName>
  </dataResource>
</dataResources>

<!-- layoutResources.xml -->
<layoutResources>
  <layoutResource name="fancy">
    <path>web/layout/fancy</path>
  </layoutResource>
</layoutResources>

We can then add source files to the registered directory:

src/
  main/
    resources/
      web/
        layout/
          fancy/
            common/
              html/
              css/

These source files will then be copied to the struts directory in the expanded application folder when expanding.