ActiveReports 13
Web Designer Plug-ins API
ActiveReports 13 > ActiveReports User Guide > Concepts > ActiveReports Web Designer > Web Designer Plug-ins API

It is possible to plug-in certain external components to Designer by means of DesignerOptions object.

Copy Code
{
    // Determines whether File View is available and
    // how File View is rendered. The function is optional.
    openFileView?: { (fileViewBaseOptions: FileViewBaseOptions): void },
    // Determines whether Viewer is available and
    // how Viewer is rendered. The function is optional.
    openViewer?: { (viewerBaseOptions: ViewerBaseOptions): void },
    // Determines what happens when report save procedure is initiated.
    // For example, 'silent' save could be performed here for an existing report.
    onSave?: { (saveBaseOptions: SaveBaseOptions): void },
    // Determines what happens when report save as procedure is initiated.
    // For example, save as dialog could be opened here for a new report.
    onSaveAs?: { (saveBaseOptions: SaveBaseOptions): void },
    dataSetPicker: {
        // If mode is 'Panel', then data set picker is rendered within 'Data Tab'.
        // Otherwise, it is up to user to manage how data set picker is rendered.
        mode: string,
        // Specifies what happens on opening data set picker.
        open?: { (openDataSetPickerBaseOptions: OpenDataSetPickerBaseOptions): void },
        // Specifies what happens on closing data set picker.
        close?: { (): void },
    },
}

The details of plug-in components are as follows:

File View

You can plug-in File View component by providing openFileView() function implementation to DesignerOptions object.
When openFileView() is implemented and passed to DesignerOptions, File Tab appears in Designer application bar.

Parameters 
openFileView(fileViewBaseOptions: FileViewBaseOptions) 

Return Value
void

File View Base Options Object

Copy Code
type FileViewBaseOptions = {
    locale: 'en' | 'ja' | 'zh', // Designer passes its locale.
    mode: 'new' | 'open' | 'saveAs', // Designer requests File View to be opened in the specified mode.
    // Information about the currently edited report
    reportInfo: FileViewReportInfo,
    // About info is either passed from Designer,
    // or can be explicitly overwritten for File View.
    aboutInfo?: AboutInfo,
    // Help infos are either passed from Designer,
    // or can be explicitly overwritten for File View.
    helpInfos?: Array<HelpInfo>,
}

You can find information about objects FileViewReportInfo, AboutInfo and HelpInfo below.

File View Report Info Object
Copy Code
type FileViewReportInfo = {
    id?: string,
    name: string,
    permissions: Array<string>,
    isTemplate?: boolean, // Reserved for future use.
}

Example

In sample code below you will see that several Designer Server API functions and Designer Reporting API functions are used while plugging-in some custom File View to Designer.

Copy Code
<link rel="stylesheet" href="sample-file-view.css" />
<!-- ... -->
< script src="sample-file-view.js"></script>
<!-- ... -->
< div id="sample-file-view-id" style="width: 100%; height: 100%; display: none;"></div>
<script>
  function openFileViewImpl(fileViewBaseOptions) {
    // ... hide Designer and show File View
    function addOptions(baseOptions, additionalOptions) {
      return $.extend({}, baseOptions || {}, additionalOptions || {});
    }
    var fileViewOptions = addOptions(fileViewBaseOptions, {
      onClose: function () {
        // ... hide File View and show Designer
      },
      serverApi: {
        getReportsList: baseServerApi.getReportsList,
        getReportRevisions: baseServerApi.getReportRevisions,
        getDataSetsList: baseServerApi.getDataSetsList,
        getTemplatesList: baseServerApi.getTemplatesList,
        getTemplateThumbnail: baseServerApi.getTemplateThumbnail,
      },
      createReport: GrapeCity.ActiveReports.WebDesigner.api.createReport,
      openReport: GrapeCity.ActiveReports.WebDesigner.api.openReport,
      saveReport: GrapeCity.ActiveReports.WebDesigner.api.saveReport,
    });
    sampleFileView.render('sample-file-view-id', fileViewOptions);
  }
  // ... create designer options
  designerOptions.openFileView = openFileViewImpl;
  // ... render designer application
</script>

Report Viewer

You can plug-in Report Viewer component by providing openViewer() function implementation to DesignerOptions object.
When openViewer() is implemented and passed to DesignerOptions, Preview button appears in Designer application bar.

Parameters 
openViewer(viewerBaseOptions: ViewerBaseOptions) 

Return Value
void

Viewer Base Options Object

Copy Code
type ViewerBaseOptions = {
 locale: 'en' | 'ja' | 'zh', // Designer passes its locale.
 // Information about the report to-be-previewed
 reportInfo: ViewerReportInfo,
}

You can find information about ViewerReportInfo object below.
Viewer Report Info Object
Copy Code
type ViewerReportInfo = {
    id?: string,
    // Report content in JSON format that can be useful
    // for report viewers with in-browser rendering
    content?: object,
    name: string,
    // Specifies whether the report to-be-previewed
    // is an existing report saved on server.
    isTemporary?: boolean,
}

Example:

In sample code below you will see how some custom Report Viewer can be plugged-in to Designer.

Copy Code
<link rel="stylesheet" href="sample-viewer.css" />
<!-- ... -->
< script src="sample-viewer.js"></script>
<!-- ... -->
< div id="sample-viewer-id" style="width: 100%; height: 100%; display: none;"></div>
<script>
  function openViewerImpl(viewerBaseOptions) {
    // ... hide Designer and show Report Viewer
    function addOptions(baseOptions, additionalOptions) {
      return $.extend({}, baseOptions || {}, additionalOptions || {});
    }
    var viewerOptions = addOptions(viewerBaseOptions, {
      onClose: function () {
        // ... hide Report Viewer and show Designer
      },
    });
    sampleViewer.render('sample-viewer-id', viewerOptions);
  }
  // ... create designer options
  designerOptions.openViewer = openViewerImpl;
  // ... render designer application
</script>

Behavior On Save / Save As

You can specify behavior for Save / Save As scenarios by providing onSave() / onSaveAs() functions implementations to DesignerOptions object.

Parameters Return Value

onSave(saveBaseOptions: SaveBaseOptions)

void

onSaveAs(saveBaseOptions: SaveBaseOptions)

void

 Save Base Options Object

Copy Code
type SaveBaseOptions = {
    locale: 'en' | 'ja' | 'zh', // Designer passes its locale.
    reportInfo: SaveReportInfo,
    onSuccess: { (): void },
}

 You can find information about SaveReportInfo object below.

Save Report Info Object
Copy Code
type SaveReportInfo = {
 name: string,
 id?: string,
 // Report content in JSON format.
 content?: object,
}

Example:

In sample code below you will see how some custom Save / Save As behavior can be plugged-in to Designer.
Several Designer Server API functions and Designer Reporting API functions are used here.

Copy Code
<link rel="stylesheet" href="sample-save-as-dialog.css" />
<!-- ... -->
< script src="sample-save-as-dialog.js"></script>
<!-- ... -->
< div id="sample-save-as-dialog-id" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; display: none; z-index: 9999;"></div>
<script>
  function onSaveImpl(saveBaseOptions) {
    // An existing report is saved silently,
    // i.e. no dialogs appear.
    GrapeCity.ActiveReports.WebDesigner.api.saveReport({
      reportInfo: {
        id: saveBaseOptions.reportInfo.id,
        name: saveBaseOptions.reportInfo.name,
      },
    });
  }
  function onSaveAsImpl(saveBaseOptions) {
    // ... show Save As dialog
    function addOptions(baseOptions, additionalOptions) {
      return $.extend({}, baseOptions || {}, additionalOptions || {});
    }
    var saveOptions = addOptions(saveBaseOptions, {
      onClose: function () {
        // ... hide Save As dialog
        GrapeCity.ActiveReports.WebDesigner.focus();
      },
      serverApi: {
        getReportsList: baseServerApi.getReportsList,
      },
      saveReport: GrapeCity.ActiveReports.WebDesigner.api.saveReport,
    });
    sampleSaveAsDialog.render('sample-save-as-dialog-id', saveOptions);
  }
 
  // ... create designer options
  designerOptions.saveButton.visible = true;
  designerOptions.onSave = onSaveImpl;
  designerOptions.saveAsButton.visible = true;
  designerOptions.onSaveAs = onSaveAsImpl;
  // ... render designer application
</script>

Data Set Picker

You can specify behavior on clicking Add Data Set button from Data tab Data Sets section.

Parameters

Parameters Return Value
dataSetPicker.open(openDataSetPickerBaseOptions: OpenDataSetPickerBaseOptions) void
dataSetPicker.close() void

Open Data Set Picker Base Options Object

Copy Code
type OpenDataSetPickerBaseOptions = {
  locale: 'en' | 'ja' | 'zh', // Designer passes its locale.
 // If mode is 'Panel', data set picker is rendered within 'Data Tab'.
 mode: string,
 // If mode is not 'Panel', data set picker is rendered to element with this id.
 elementId?: string,
 // Data sources from report
 reportDataSources: Array<DataSource>,
 // Data sets from report
 reportDataSets: Array<DataSet>,
 // New data sources and data sets to be added are passed as parameters to this function.
 addDataSourcesAndDataSets: { ({ dataSources: Array<DataSource>, dataSets: Array<DataSet> }): void },
 // Specifies what should happen on closing data set picker.
 onClose: { (): void },
}


Regarding DataSource and DataSet types, see Data Source And Data Set Objects.

Example:

In sample code below you will see how some custom data set picker can be plugged-in to Designer.
Several Designer Server API functions and Designer Reporting API functions are used here.

Copy Code
<link rel="stylesheet" href="sample-data-set-picker.css" />
<!-- ... -->
< script src="sample-data-set-picker.js"></script>
<!-- ... -->
< div id="sample-data-set-picker-dialog-id" style="position: absolute;top: 0;left: 0;width: 100%;height: 100%;display: none;z-index: 9999;"></div>
<script>
  function openDataSetPickerImpl(openDataSetPickerBaseOptions) {
    function addOptions(baseOptions, additionalOptions) {
      return $.extend({}, baseOptions || {}, additionalOptions || {});
    }
    var openInPanel = options.mode === 'Panel';
    var openDataSetPickerOptions = addOptions(openDataSetPickerBaseOptions, {
      onClose: function () {
        options.onClose();
        if (!openInPanel) // ... hide Data Set Picker
        // ... dispose Data Set Picker and show Designer
      },
      serverApi: {
        getDataSetsList: baseServerApi.getDataSetsList,
        getDataSourcesAndDataSets: baseServerApi.getDataSourcesAndDataSets,
      },
    });
    if (!openInPanel) // ... show Data Set Picker
    var dataSetPickerId = openInPanel ? options.elementId : 'sample-data-set-picker-dialog-id';
    sampleDataSetPicker.render(dataSetPickerId, openDataSetPickerOptions);
  }
  function closeDataSetPickerImpl() {
    // ... dispose Data Set Picker and show Designer
  }
  // ... create designer options
  designerOptions.dataTab.dataSets.canModify = true;
  designerOptions.dataSetPicker.mode = 'Panel';
  designerOptions.dataSetPicker.open = openDataSetPickerImpl;
  designerOptions.dataSetPicker.close = closeDataSetPickerImpl;
  // ... render designer application
</script>