Media WebUI

Prerequisites

Build Steps

The NPM package manager requires node to be installed first. You will need Node 18.x or later. The latest version can be downloaded here Node Download

NPM is installed by the Node installer. This will install the latest NPM globally. For more information see NPM installation docs here NPM Installation

Now you are ready to set up the WebUI project. Start by downloading and unpacking the latest WebUI version or fork the WebUI GitHub repository to your chosen project folder. You can download the latest version of WebUI here WebUI Latest

Open a command prompt and navigate to the project folder where you unpacked the WebUI project files.

Type the following and wait for dependencies to be installed.

npm install

This will install all packages listed in the package.json file, including WebUI.

To build the project for development, type the following:

npm run dev

To build the project for production, type the following:

npm run build

Build Dependencies

WebUI currently uses NPM as the package manager. Webpack 5 is used as the file bundler, and requires a number of plugins for the build process. Developers who are familiar with Webpack may want to swap out some of these plugins and create their own build configuration, but care should be taken when combining SASS and JavaScript files.

Build Dependencies

Build dependencies (Webpack + plugins). There are no dependencies for the WebUI framework in production.

NOTE: Some of these versions may get updated from time to time.

Dependency Version
compression-webpack-plugin ^10.0.0
css-loader ^6.8.1
mini-css-extract-plugin ^2.7.6
remove-files-webpack-plugin ^1.5.0
sass ^1.69.3
sass-loader ^13.3.2
style-loader ^3.3.3
webpack ^5.89.0
webpack-cli ^5.1.4
webpack-concat-files-plugin ^0.5.2
webpack-messages ^2.0.4

Building the Source Files

SASS Files

There are 6 SASS files that import different sets of SASS base and component files.

SASS File Imported SASS Files
webui-all.scss

(Compiled to -> webui-all.css)
settings (Required)
mixins (Required)
theme-hsl (*Required)

mixins-layout (Layout)
layout (Layout)
layout-properties (Layout)

flexbox-layout (Flexbox)
flexbox-properties (Flexbox)

grid-layout (Grid)
grid-properties (Grid)

column-layout (Column)
column-properties (Column)

positioning
main (Required)
color (Required)
color-extra
transitions
responsive
responsive-extra
print
webui-standard.scss

(Compiled to -> webui-standard.css)
settings (Required)
mixins (Required)
theme-hsl (*Required)

mixins-layout (Layout)
layout (Layout)
layout-properties (Layout)

flexbox-layout (Flexbox)
flexbox-properties (Flexbox)

grid-layout (Grid)
grid-properties (Grid)

column-layout (Column)
column-properties (Column)

positioning
main (Required)
color (Required)
transitions
responsive
print
webui-basic.scss

(Compiled to -> webui-basic.css)
settings (Required)
mixins (Required)
theme-hsl (*Required)
main (Required)
color (Required)
print
webui-components-all.scss

(Compiled to -> webui-components-all.css)
settings (Required)
mixins (Required)
theme-hsl (*Required)

mixins-layout (Layout)
layout (Layout)
layout-properties (Layout)

flexbox-layout (Flexbox)
flexbox-properties (Flexbox)

grid-layout (Grid)
grid-properties (Grid)

column-layout (Column)
column-properties (Column)

carousel
menu
navbar
nav-button
nav-indicator
modals
tabs
alerts
tooltips
upload
radial
toast
focus-trap
shapes
positioning
main (Required)
color (Required)
color-extra
transitions
responsive
responsive-extra
print
webui-components-standard.scss

(Compiled to -> webui-components-standard.css)
settings (Required)
mixins (Required)
theme-hsl (*Required)

mixins-layout (Layout)
layout (Layout)
layout-properties (Layout)

flexbox-layout (Flexbox)
flexbox-properties (Flexbox)

grid-layout (Grid)
grid-properties (Grid)

column-layout (Column)
column-properties (Column)

carousel
menu
navbar
nav-button
nav-indicator
modals
tabs
alerts
tooltips
upload
radial
toast
focus-trap
shapes
positioning
main (Required)
color (Required)
transitions
responsive
print
webui-components-basic.scss

(Compiled to -> webui-components-basic.css)
settings (Required)
mixins (Required)
theme-hsl (*Required)
carousel
menu
navbar
nav-button
nav-indicator
modals
tabs
alerts
tooltips
upload
radial
toast
focus-trap
shapes
main (Required)
color (Required)
print

SASS files labeled as (required) are required in all build scenarios, as many components depend on them. Some other files are grouped indicating that they should be imported together if required.

* A theme file is required. This can be one of the standard themes or a custom theme.

The following Webpack entry point in webpack.dev.js and webpack.prod.js specifies which SASS files are transformed to produce the final CSS output files.

module.exports = {

  entry: {'webui-components-all': ['./src/scss/webui-components-all.scss'],
          'webui-components-standard': ['./src/scss/webui-components-standard.scss'],
          'webui-components-basic': ['./src/scss/webui-components-basic.scss'],
          'webui-all': ['./src/scss/webui-all.scss'],         
          'webui-standard': ['./src/scss/webui-standard.scss'],
          'webui-basic': ['./src/scss/webui-basic.scss']
  },

  ...
}
JS

JavaScript Files

Two JavaScript files are generated as part of the build using Webpack plugins. See below for the output files and separate input files concatenated to produce them.

JavaScript File Input Files
webui.js
_settings.js (Required)
main.js (Required)
webui-components.js
_alerts.js
_animation.js
_carousel.js
_focusTrap.js
_menu.js
_modals.js
_navbar.js
_navbutton.js
_navIndicator.js
_radial.js
_scrollspy.js
_settings.js (Required)
_shapes.js
_tabs.js
_toast.js
_tooltips.js
_upload.js
_validation.js
_zoom.js
main.js (Required)

JavaScript files labeled as (required) are required in all build scenarios. All other files are optional components.

The following Webpack plugin configurations in webpack.dev.js specify which JavaScript files are concatenated to produce the final output. webpack.prod.js is similar, except that the output files are minified for production.

plugins: [
  new WebpackConcatPlugin({
    bundles: [
      {
        dest: './dist/js/webui-components.js',
        src: './src/js/*.js'       
    }]
  }),
  new WebpackConcatPlugin({
    bundles: [
      {
        dest: './dist/js/webui.js',
        src: './src/js/main.js'
      }]
  }),
  ...
]
JS

Changing SASS Theme Files

Theme Files

Most of the theme colors are used throughout the framework and have been carefully grouped in theme sets. Any colors can be chosen, but contrast and accessibility should be kept in mind. WebUI provides an HSL theme file and an RGB alternative which can be used instead if required.

Currently, the HSL theme file is used in the build by default. To change the theme to RGB, rename "theme-hsl" to "theme" in the SASS import files, then build the project using the instructions above.

When the project is built the theme colors will be converted to HEX during the minification process, but the un-minified versions will retain either HSL or RGB color values.

For more information on themes see the Colors section.

Changing breakpoint settings

Breakpoints

Breakpoint settings are found in 2 separate files that must match in terms of the breakpoint sizes. The 2 files are _settings.scss and _settings.js. For example, the SASS setting $settings_bp_1_under: 29.99rem; corresponds with the JS setting webui.bp_1_under = "29.99rem";.

NOTE: The "under" and "over" values for each breakpoint pair must be as close to each other as possible because not all browsers round to the nearest whole pixel. A difference of 0.01rem or 0.2px is normally sufficient and will avoid any gaps occuring in the media queries.

Breakpoints

The WebUI framework does not support changing the total number of breakpoints at this time.

For more information on breakpoints see the Breakpoints section.