Customization

ActiveReportsJS Report Designer component includes various UI elements available to users by default. To customize the user interface, such as hiding certain elements or prohibiting specific actions like modifying data binding configurations, you can utilize the Customization API. This page describes how to apply these customizations.

DesignerConfig object

The report designer UI is configured in the API with the DesignerConfig object that has the following shape:

var designerConfig = {
  // General Settings
  language?: string, 
  units?: "in" | "cm",  
  customInitTemplates?: CustomInitTemplates,
  disableOpenSaveHotkeys?: boolean,
  lockLayout?: boolean,
  storeUserPreferences?: boolean,
  disableSystemClipboard?: boolean,

  editor?: editorSettings,
  appBar?: appBarSettings,
  toolBar?: toolBarSettings,
  menu?: menuSettings,
  data?: dataTabSettings,
  propertyGrid?: propertyGridSettings,
  statusBar?: statusBarSettings,
};

The General settings, editorSettings, appBarSettings, toolBarSettings, menuSettings, dataTabSettings, propertyGridSettings, and statusBarSettings objects described in the following sections.

General settings

The DesignerConfig object includes several properties that influence the overall behavior of the Report Designer:

language: Sets the UI language, you can find more details on the Localization page.
units : Sets the default measurement units for the report items.
customInitTemplates: Overrides the default properties for newly added report items
disableOpenSaveHotkeys: When set to true, this setting disables handling of keyboard shortcuts by the designer component.
lockLayout: When enabled (true), this setting prevents users from adding new items or removing existing items from the report layout. Users are only allowed to modify the properties of the items already present in the report.
storeUserPreferences: If enabled (true), the designer saves its configuration settings, such as Grid Size, to the browser storage. These settings are then automatically restored, unless they are explicitly defined in a subsequent session.
disableSystemClipboard: When set to true, this setting disables the ability to use the system clipboard for copying and pasting report items between different instances of the designer.

Editor Settings

The editor property within the DesignerConfig object provides options to configure the appearance and behavior of the report editor, including rulers, grid, and visual guides for aligning report items:

const editorSettings = {
  rulers: {
    visible: true, // Show rulers by default
    snapStep: {
      in: 0.25, // Set snapping step for inches
      cm: 0.5, // Set snapping step for centimeters
    },
  },
  gridSize: "0.5cm", // Set default grid size in centimeters
  showGrid: true, // Show grid by default
  snapToGrid: true, // Enable snap to grid by default
  snapToGuides: false, // Disable snap to guides by default
};

var designerConfig = {
  editor: editorSettings,
};

The appBar property within the DesignerConfig object is used to configure the Application Bar of the designer component. This topmost bar includes action buttons like Undo, Redo, and Save, and provides access to various tabs such as Home or Parameters. The toolbar resides beneath the application bar and contains action buttons depending on the currently selected tab.

The following example demonstrates how to set up the Application Bar and the Toolbar:

const appBarSettings = {
  visible: true, // Show the app bar
  homeTab: {
    visible: true, // Show the home tab
  },
  contextActionsTab: {
    visible: false, // Hide the context actions tab
  },
  parametersTab: {
    visible: true, // Show the parameters tab
   },
};

const toolBarSettings = {
  visible: false, // Hide the toolbar
};

var designerConfig = {
  appBar: appBarSettings,
  toolBar: toolBarSettings
};

The menu property within the DesignerConfig object is designed to configure the appearance of elements in the sidebar of the designer. This sidebar expands and collapses via the Hamburger menu icon, located at the top-right side of the designer interface. The following example demonstrates how to configure these menu elements:

const menuSettings = {
  visible: true, // Show the main menu
  toolBox: {
    visible: true, // Show the Tool Box
  },
  documentExplorer: {
    visible: false, // Hide the Document Explorer
  },
  groupEditor: {
    visible: true, // Show the Group Editor
  },
  layerEditor: {
     visible: true, // Show the Layer Editor
  },
  logo: {
    visible: true, // Show the logo
    custom: {
      type: "css",
      class: "fa-solid fa-user",
    },    
  },
};
var designerConfig = {
  menu: menuSettings ,
};

Data tab Settings

The data property within the DesignerConfig object defines the appearance and behavior of the Data tab:

const dataTabSettings = {
  dataTab: {
    visible: true, // Show the Data tab
  },
  dataSources: {
    visible: true, // Show the Data Sources section
    canModify: false, // Do not allow modification of data sources
  },
  dataSets: {
    visible: true, // Show the Data Sets section
    canModify: true, // Allow modification of data sets
  },
  parameters: {
    visible: true, // Show the Parameters section
    canModify: true, // Allow modification of parameters
  },
  commonValues: {
    visible: true, // Show the Common Values section
  },
};
var designerConfig = {
  data: dataTabSettings,
};

Property Grid Settings

The propertyGrid property within the DesignerConfig object configures the appearance and behavior of the Property grid:

const propertyGridSettings = {
  propertiesTab: {
    visible: true, // Show the Properties tab
  },
  mode: "Advanced", // Set the Property Grid mode to "Advanced" or "Basic"
  collapsibleCategories: {
    enabled: true, // Enable collapsible categories
  },
  saveExpandEditorsState: {
    enabled: true, // Remember the expanded/collapsed states of editors
  },
};
var designerConfig = {
  propertyGrid: propertyGridSettings ,
};

Status Bar Settings

The statusBar property within the DesignerConfig object is designed to configure the appearance of elements in the status bar of the designer. This status bar located on the bottom-right side of the designer interface:

const statusBarSettings = {
  visible: true, // Show the status bar
  toggleUnitsButton: {
    visible: true, // Show the units toggle button
  },
  toggleGridButton: {
    visible: false, // Hide the grid toggle button
  },
  gridSizeEditor: {
    visible: true, // Show the grid size editor
  },
  rulersButton: {
    visible: true, // Show the rulers toggle
  },
  propertiesModeButton: {
    visible: false, // Hide the properties mode button
  },
};
var designerConfig = {
  statusBar: statusBarSettings ,
};

Using Designer Config

The DesignerConfig object described above can be passed into the Report Designer component during the initialization.

Pure JS Applications

The constructor of the Report Designer component for PureJS applications accepts a DesignerConfig object as an argument.

var designer = new GC.ActiveReports.ReportDesigner.Designer(
  "#designer-host",
  designerConfig
);

React Applications

The React Report Designer component exposes the optional onInit property that should resolve to a function that retrieves the DesignerConfig object, for example:

import React from "react";
import { Designer } from "@grapecity/activereports-react";

function onInit() {
  return {
      appBar: {visible: false},
  };
}

function App() {
  return (
      <Designer onInit={onInit} />
  );
}

Angular Applications

The Angular Report Designer component exposes the optional onInit input property that should resolve to a function that retrieves the DesignerConfig object, for example:

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template:
    '<div id="designer-host"><gc-activereports-designer [onInit]="onInit"> </gc-activereports-designer></div>'
})
export class AppComponent {
  onInit = function onInit() {
    const editorSettings = {
      rulers: {
        visible: false, 
      },
    }; 
    return {
      editor: editorSettings,
    };
  }  
}

Vue Applications

Similarly, the Vue Report Designer accepts the reference to the onInit function:

<template>
  <div id="designer-host">
    <ReportDesigner
      :onInit="onInit"
    ></ReportDesigner>
  </div>
</template>

<script lang="ts">
import { Designer } from "@grapecity/activereports-vue";

export default {
  name: "App",
  components: {
    ReportDesigner: Designer,
  },
  methods: {
    onInit() {
      return {
        appBar: { visible: false },
      };
    },
  },
};
</script>

Svelte Applications

The Svelte Report Designer exposes the onInit property that should resolve to a function that returns the DesignerConfig object:

<script lang="ts">
    import {Designer} from "@grapecity/activereports-svelte";
    function onInit() {
        return {
            appBar: { visible: false }
        }
    }    
</script>

<div id="designer-host">
    <Designer bind:this={designerInst} onInit={onInit}></Designer>
</div>