CSS & JavaScript

Custom CSS and JavaScript files will be loaded automatically, following a browser refresh, if you place them under either:

• SWARM_ROOT/public/custom/*.(css|js)

or

• SWARM_ROOT/public/custom/sub-folder/*.(css|js)

Sample JavaScript extensions

The following is an example JavaScript customization that you might wish to apply to your Swarm installation. JavaScript customizations can be implemented separately, but ideally, you would apply the JavaScript customizations in a single file to reduce the number of web requests required.

Add text to the Log in dialog

This customization can only be used if require_login is set to true, see Require login.

// Custom js to put text into the login box
$(function() {
    setTimeout(function () {
            if ($('.login-form')) {
                $('.form-body') 
                    .prepend("<b style='padding-bottom: 20px; display: inline-block'>Please use your Helix Core Server login credentials.</b>");
                $('.form-body button').html('Login with Helix Core Server credentials');
            }
        },
        800);
});

Replace the Please use your Helix Core Server login credentials with the text you want to add to the top of the Swarm log in dialog.

Save this line in a file, perhaps customize-login-text.js, within the SWARM_ROOT/public/custom. Swarm automatically includes the JavaScript file, adding the text to the top of the log in dialog immediately for subsequent log ins.

Sample CSS customizations

The following are example CSS customizations that you might wish to apply to your Swarm installation. Each example can be implemented separately. Ideally, you would apply the CSS customizations in a single file to reduce the number of web requests required.

Adjust the default tab size

body {
   tab-size: 4;
}

Replace the 4 with the tab size you prefer.

Save these lines in a file, perhaps tab-size.css, within the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, adjusting the tab size immediately for subsequent page views.

Apply a custom background to the login screen

.session-container .modal-overlay.login::after {
    background-image: url('/custom/login_background.jpg');
    background-position: top center;
    background-size: 100%;
}

Replace the /custom/login_background.jpg URL fragment with the image you want to use. If you do not specify a full URL, the image you specify must exist within the SWARM_ROOT/public folder, preferably within the SWARM_ROOT/public/custom folder.

Save these lines in a file, perhaps login-background.css, within the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, immediately replacing the login screen's background for subsequent page views.

Replace Swarm's logo in the main navigation bar

#react-swarm-app-container .primary.navigation .swarmLogo a svg{
    display:none;
}
#react-swarm-app-container .primary.navigation .swarmLogo a  {
    background-repeat: no-repeat;
    background-image: url('/custom/navbar_logo.jpg');
    background-size: 116px 25px;
    background-position: 15px center;
    background-clip: content-box;
}

Replace the /custom/navbar_logo.jpg URL fragment with the image you want to use. If you do not specify a full URL, the image you specify must exist within the SWARM_ROOT/public folder, preferably within the SWARM_ROOT/public/custom folder.

Save these lines in a file, perhaps navbar-logo.css, within the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, immediately replacing the Swarm logo for subsequent page views.

Adjust the appearance of avatars

The Swarm UI is changing and moving toward using React, currently there is a mix of React and legacy PHP controlling the UI. This means that there are currently two methods of rendering avatars and you need to customize both.

• For avatars rendered by Swarm using PHP, see Adjust avatar appearance when rendered by PHP

• For avatars rendered by Swarm using React, see Adjust avatar appearance when rendered by React

For instructions on adding custom avatars, see Add custom avatars

Adjust avatar appearance when rendered by PHP

img.avatar {
    border: 2px dashed red;
    border-radius: 10%;
}

You can make a number of adjustments to the way Swarm presents avatars rendered by PHP, such as adding a border and adjusting the border radius, as the example above demonstrates. You should avoid attempting to set specific sizes because Swarm uses different sizes depending on where the avatar is displayed.

Save these lines in a file, perhaps avatars.css, within the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, immediately changing the appearance of avatars for subsequent page views.

Adjust avatar appearance when rendered by React

#react-swarm-app-container .userAvatar img{
    border: 2px dashed red;
    border-radius: 10%;
}

You can make a number of adjustments to the way Swarm presents avatars rendered by React, such as adding a border and adjusting the border radius, as the example above demonstrates. You should avoid attempting to set specific sizes because Swarm uses different sizes depending on where the avatar is displayed.

Save these lines in a file, perhaps avatars-react.css, within the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, immediately changing the appearance of avatars for subsequent page views.

Add custom avatars

Custom avatars for individual users or groups are added to Swarm using custom CSS. Custom avatars are intended for use with system users and groups.

To add a custom avatar for a user:

img.avatar[data-user="<userid>"], .userAvatar img[alt="<user name>"]{
    content: url(<path to avatar>);
}

To add a custom avatar for a group:

img.avatar[data-user="<groupid>"], .userAvatar img[alt="<group name>"]{
    content: url(<path to avatar>);
}

Save these lines in a file, perhaps avatars-custom.css, within the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, immediately using your custom avatars for subsequent page views.

Add a custom icon to a menu item

When you create a custom menu item in the menu_helpers configuration block, you can specify the menu icon to use in the Swarm CSS.

Add some custom CSS to Swarm to replace the default icon with a custom icon for the menu item. For example, the CSS below replaces the default icon with the double-speech-bubbles.svg icon for the custom01 menu item by modifying the svg.svgIcon.custom01MenuIcon and .menuItem-custom01 classes:

.swarmMenu .menuItem.menuItem-tests .svgIcon{
    display:none;
}.swarmMenu .menuItem.menuItem-tests a::before{
    content: '';
    background-image: url('/swarm/img/icons/line/double-speech-bubbles.svg');
    background-size: 16px;
    background-repeat: no-repeat;
    padding-left: 20px;
        padding-right: 4px;
        margin-left: 20px;
}

Save these lines in a file, perhaps menu_custom01.css in a folder called custom_menus, in the SWARM_ROOT/public/custom folder. Swarm automatically includes the CSS file, immediately using your custom menus for subsequent page views. If you are using your own custom images, we recommend you store them in the same folder as your custom css.

CSS customization when Swarm is connected to multiple Helix Core Server instances

If Swarm is configured to connect to more than one Helix Core Server instance, Swarm can be customized for each of the Helix Core Server instances it is connected to. This gives users an simple visual prompt as to which Helix Core Server instance they are currently viewing in Swarm. All of the customizations described in the section above are available for multiple Helix Core Server instances.

To customize Swarm for a Helix Core Server instance, include the [data-server-id="<server-name>"] data attribute in the CSS selector you are customizing. Replace <server-name> with the Helix Core Server name the customization is for.

See the examples below to see how the data attribute is used to customize Swarm for the individual Helix Core Server instances. As with the customization of Swarm when it is connected to a single Helix Core Server, you should ideally apply the CSS customizations in a single file to reduce the number of web requests required.

Apply a custom background color to the navigation bar of each of the Helix Core Server instances

body[data-server-id="serverA"] #react-swarm-app-container .swarm-navigation {
    background-color: #d21544;
}
body[data-server-id="serverB"] #react-swarm-app-container .swarm-navigation {
    background-color: pink;
}

Apply custom background images to the login screen of each of the Helix Core Server instances

body.route-login[data-server-id="serverA"] .session-container .modal-overlay.login::after {
    background-position: top center;
    background-size: 100%;
    background-image: url(/custom/login_background_A.jpg);
}
body.route-login[data-server-id="serverB"] .session-container .modal-overlay.login::after {
    background-position: top center;
    background-size: 100%;
    background-image: url(/custom/login_background_B.jpg);
}