Web > Styling

Managing Styles

This page contains details on user customization and style options for 3forge.

Overview

3forge ships with a variety of layout themes or "Styles." These are stored as JSON files in the amione/data/styles directory by default. These style sheets apply a visual theme to dashboards and their associated elements.

It is possible to edit existing styles to create your own or create your own from scratch.

Style Sheet Information

Each style sheet has an associated JSON. You can view the JSON representation of a style by going to Dashboard -> Style Manager and right-clicking on "Export Style".

Each style sheet has the following:

• "id": The unique ID of the style.

• "pt": The parent of the style sheet, e.g: if the style sheet has inherited from a specific style family.

• "lb": The displayed name of the style within 3forge.

For example, for the Classic style:

[
    {
        "id":"DEFAULT",
        "pt":"",
        "lb":"Classic",
    }
]

Any user-created styles will also require this information.

There are a number of places where styling effects can be applied:

• Style Manager:

  • In Dashboard -> Style Manager
  • You can edit and customize visual elements of a given layout in the "Styles" drop-down menu

• HTML Field Elements:

  • For any HTML field element (button, upload field, etc), you can edit the way it appears in the "Field Style" menu
  • Some elements have help popups. Customize this text in the "Help" tab

• Window Configuration:

  • In any 3forge window, clicking the "Configure Window" cog will pull up a drop-down menu including "Style (All Windows)"
  • This is equivalent to doing Dashboard -> Style Manager and using the "Styles" drop-down menu to select "Dashboard"

Stylistic changes can then be exported for use across different dashboards and user sessions.

Note

3forge by default ships with 3 style families: Nova, Halloween, and Porcelain. We have a number of other style options, if you would like them, please reach out to support@3forge.com.

Readonly Styles

Style sheets are titled as <SOME_STYLE>.amistyle.json. The default readonly 3forge style sheets are JSON formatted files saved in the amione/data/styles directory of your installation.

To add new style sheets, ensure they are titled in the same <SOME_STYLE>.amistyle.json format, then add the file to the amione/data/styles directory.

Example

To add a downloaded style sheet titled DARKMATTER.amistyle.json:

1. Navigate to the styles directory and place the JSON file there.

2. Restart 3forge then navigate to Dashboard -> Style Manager. The new style "Dark Matter" will now be in the list of readonly styles:

   ![](./images/dark-matter.png)
   

   To select the style, either:

   1. Within the Style Manager, right-click on "Layout Default" and set the inherit defaults to inherit from "Dark Matter":

      ![](./images/style-picker.png)
      

      Or:

   2. Go to Dashboard -> Dashboard Style and select "Dark Matter" from the "Inherit From" drop-down menu:

      ![](./images/dashboard-style.png)
      

Creating Styles

To customize and create a style from the basic default layout:

1. Navigate to the Style Manager in Dashboard -> Style Manager.

2. Select "Layout Default" on the upper box of the left hand navigation menu.

3. Open up the sub-menu in the right box of the left hand navigation menu and select "Styles" then "Dashboard."

   

4. Set the colors and other style options. When done, export the JSON of the new Layout Default by right-clicking on "Layout Default" and selecting "Export Style".

5. Copy the JSON and change the "id" and "lb" tags to identifiers for your style.

Copying Styles

To copy an existing dashboard style to use in another layout or customize, use the "Import Style" and "Export Style" functions in the Style Manager.

From an existing pre-styled dashboard such as the following:

You can copy the style by doing the following steps:

1. Navigate to Dashboard -> Style Manager.

2. Locate the style in the left-hand side. Right-click the style name and click Export Style. Copy the ouput:

   

3. Next, open the dashboard where you want to use this style. Go to Dashboard -> Style Manager and select "Import Style". Paste the copied layout and give the imported layout new "id" and "lb" fields (in this case, CopiedStyle):

   

4. Finally, under "Layout Default", select CopiedStyle to inherit from. This will update the style of the entire dashboard to this style.

   

User Style Selection

You might want your dashboard to have different or selectable themes, e.g: a light and dark mode.

You can make use of user preferences in 3forge to switch between themes on a per-user basis.

The guide below shows how to switch themes for a given user with a drop-down list and how to save that theme in their preferences.

Requirements

User preferences need to be enabled. See the guide on setting up user preferences and namespaces.

Set Theme with a Custom Method

This example uses a custom method to store the logic for changing the theme. This can then be called in the layout directly in any field that takes AmiScript, e.g: through a Select field.

Navigate to Dashboard -> Custom Methods and create a new method called setTheme():

Boolean setTheme(String theme){
    if (theme == null || theme == "") return false;
    StyleSet layoutDefault = session.getStyleSet("LAYOUT_DEFAULT");
    layoutDefault.setParent(theme);
    return true;
  };

Note

This assumes all panels/dividers/etc. are inheriting from LAYOUT_DEFAULT or a child of LAYOUT_DEFAULT.

If it has a different parent, you will need to update the session.getStyleSet("LAYOUT_DEFAULT") field accordingly.

Theme Select Button

In an HTML panel, create a Select field with each selectable option as the ID of the styles. This will be the drop-down menu called from within the 3forge layout.

Scroll down the Settings tab of the Select field and populate the key-value pairs. For this example, we will use the classic layout and the "Porcelain" style sheet.

Now, navigate to the AmiScript tab of the Select field to the onChange() callback and add the following:

String theme = this.getValue();
setTheme(theme);
session.putCustomPreference("theme", theme);
session.saveUserPreferences(); // optional, force saves the user's preferences

This does 3 things:

1. Calls the custom method and sets the theme based on the ID of the user's selection from the drop-down menu
2. Adds that theme to the user session's custom preferences
3. Saves this to the user's preferences

Now, to ensure the user's preferences are saved and loaded, the theme needs to be applied in the onUserPrefsLoaded() callback:

String theme = session.getCustomPreference("theme");
setTheme(theme);

This gets invoked whenever a user loads the dashboard.

Save and rebuild 3forge by going to File->Rebuild. You can now set your layout theme which will then be saved and recorded to your user preferences.