This document includes the following information:
Below you will find a step-by-step guide on how to perform various actions with this API.
Report Designer, File-View and Report Viewer are separate components.
In the table below you can find which folders/files are mandatory.
| Module | Is Mandatory | Folders/Files |
|---|---|---|
| Base Server API | yes | baseServerApi.js |
| Designer | yes | /icons, /logos, /vendor, designer.js, designer.css, designer.css.map |
| File-View | no | fileview.js, fileview.css, fileview.css.map |
| Viewer | no | viewer.js, viewer.css, viewer.css.map |
The snippet below illustrates the idea how Designer, File-View and Viewer are set up.
<link rel="stylesheet" href="./fileview.css" type="text/css"/>
<link rel="stylesheet" href="./viewer.css" type="text/css"/>
<link rel="stylesheet" href="./designer.css" type="text/css"/>
<script src="./baseServerApi.js"></script>
<script src="./fileview.js"></script>
<script src="./viewer.js"></script>
<script src="./designer.js"></script>
<div id="file-view-id" style="display: none;"></div>
<div id="report-viewer-id" style="display: none;"></div>
<div id="designer-id"></div>
<script>
// ... declaring auxiliary variables/functions
var designerElementId = 'designer-id';
var designerOptions = // ...
designer.renderApplication(designerElementId, designerOptions);
</script>
The designer module exports renderApplication() function which has two parameters:
The idea of how designerOptions are passed to renderApplication() function:
designer.renderApplication(designerElementId, {
serverApi: baseServerApi,
/* File-View */
openFileView: function(fileViewBaseOptions: FileViewBaseOptions) {
// ... hiding designer
// ... showing file-view
var fileViewOptions = mergeOptions(fileViewBaseOptions, {
serverApi: baseServerApi,
createReport: designer.api.createReport,
openReport: designer.api.openReport,
saveReport: designer.api.saveReport,
onClose: function() {
// ... hiding file-view
// ... showing designer
},
});
fileview.renderFileView(fileViewElementId, fileViewOptions);
},
/* Viewer */
openViewer: function(viewerBaseOptions: ViewerBaseOptions) {
// ... hiding designer
// ... showing viewer
var viewerOptions = mergeOptions(viewerBaseOptions, {
onClose: function() {
// ... hiding viewer
// ... showing designer
},
});
viewer.renderViewer(viewerElementId, viewerOptions);
},
});
In the sections below you will find more information on FileViewBaseOptions and ViewerBaseOptions objects as well as on designer.api functions.
Please pay your attention to the fact that File-View and Viewer are optional and replaceable. I.e., it is possible to plug-in your own File-View/Viewer instead of the predefined ones.
Designer uses AuthToken value from the cookies in order to authenticate while making REST API calls. Therefore, it is required to have AuthToken in the cookies for Designer operation.
The module baseServerApi.js exports baseServerApi object that contains login() and checkAuthToken() functions which return Promise-like objects. These functions can be used to perform authentication before Designer is rendered.
In the example below an external CDN dependency to js-cookie library is used for simplicity:
<script src="https://cdnjs.cloudflare.com/ajax/libs/js-cookie/2.2.0/js.cookie.min.js"></script>
<script src="./baseServerApi.js"></script>
<script src="./designer.js"></script>
<div id="designer-id" style="width: 100%; height: 100%;"></div>
<script>
var AuthTokenKey = 'AuthToken';
var userName = 'your-user-name';
var password = 'your-password';
function renderDesigner() {
designer.renderApplication('designer-id', { serverApi: baseServerApi });
}
function onSuccessfulLogin(response) {
var token = response && response.Token;
// Set the AuthToken cookie
Cookies.set(AuthTokenKey, token, { path: '/' });
renderDesigner();
}
function onError(ex) { /* Process error here... */ }
function performLogin() {
baseServerApi.login(userName, password)
.done(onSuccessfulLogin)
.fail(onError);
}
function onSuccessfulCheckAuthToken(response) {
var isAuthTokenValid = response && response.Valid || false;
if (isAuthTokenValid) renderDesigner();
else performLogin();
}
// Get the AuthToken cookie
var cookieAuthToken = Cookies.get(AuthTokenKey);
if (cookieAuthToken) {
baseServerApi.checkAuthToken(cookieAuthToken)
.done(onSuccessfulCheckAuthToken)
.fail(onError);
}
else performLogin();
</script>
As a result, login-related routines are performed silently so Designer user doesn't have to perform login manually.
File-View is an optional component, i.e., if openFileView() function is not passed to designerOptions, File tab disappears from Web Report Designer.
You can implement your own File-View and set up its rendering within openFileView() function.
Designer passes FileViewBaseOptions object to openFileView() function. Before passing this object directly to fileview.renderFileView() function, you could customize it by overwriting certain properties.
For example, properties aboutInfo and helpInfos can be overwritten - please see the corresponding examples - overwrite File-View About info and overwrite File-View Help infos.
Viewer is an optional component, i.e., if openViewer() function is not passed to designerOptions, Preview button disappears from Web Report Designer.
You can implement your own Viewer and set up its rendering within openViewer() function.
Designer passes ViewerBaseOptions object to openViewer() function.
The designer.api provides the ability to create a report using the designer.api.createReport() function. This function expects a single mandatory argument – CreateReportOptions object – having this structure:
type CreateReportOptions = {
templateInfo?: TemplateInfo,
// Either models or dataSets can be defined.
// If models are defined, models array may contain only one model.
models?: Array<ModelInfo>,
dataSets?: Array<DataSetInfo>,
// These functions can be used for making UI changes
// (e.g. drawing overlays or switching current view)
// while report is getting created.
onStart?: { (): void },
onFinish?: { (): void },
}
The mentioned objects TemplateInfo, ModelInfo and DataSetInfo can be found in the appendix.
The designer.api provides the ability to open a report using the designer.api.openReport() function. This function expects a single mandatory argument – OpenReportOptions object – having this structure:
type OpenReportOptions = {
reportInfo: OpenReportInfo,
// These functions can be used for making UI changes
// (e.g. drawing overlays or switching current view)
// while report is getting opened.
onStart?: { (): void },
onFinish?: { (): void },
}
Please find more details about OpenReportInfo object in the appendix.
The designer.api provides the ability to save a report using the designer.api.saveReport() function. This function expects a single mandatory argument – SaveReportOptions object – having this structure:
type SaveReportOptions = {
reportInfo: SaveReportInfo,
// These functions can be used for making UI changes
// (e.g. drawing overlays or switching current view)
// while report is getting saved.
onStart?: { (): void },
onFinish?: { (): void },
}
Please find more details about SaveReportInfo object in the appendix.
The designer.api provides the ability to get information about the currently edited report using these functions:
// If an existing report is edited, id is defined.
// Otherwise, if a new report is edited, id is null.
type CurrentReportInfo = {
id: string,
name: string,
isTemplate: boolean,
permissions: Array<string>,
}
The designer allows getting general information about Designer using these functions:
Both functions are intended for customizing information shown in File-View in the corresponding areas - About and Help respectively - which are managed by aboutInfo and helpInfos properties of FileViewBaseOptions object. The corresponding examples are overwrite File-View About info and overwrite File-View Help infos.
In this example it is shown how to set up Designer so it wouldn't have File tab and Preview button.
<div id="designer-id" style="width: 100%; height: 100%;"></div>
<script>
designer.renderApplication('designer-id', {
serverApi: baseServerApi,
});
</script>
With such custom Designer it is only possible to create a new report, edit an existing report by opening it from Report Portal and save changes using the built-in dialogs that open on clicking Save and Save As buttons.
Both Designer and File-View have serverApi property. By default the complete baseServerApi object (exported by baseServerApi.js) is assigned to serverApi. However, it is possible to "turn-off" certain functionality provided by baseServerApi.
In this example getting server data-sources and server data-sets is "turned-off". As a result, Designer "becomes" a Semantic Report Designer because in this case only semantic models are allowed as data resources.
<div id="file-view-id" style="width: 100%; height: 100%; display: none;"></div>
<div id="report-viewer-id" style="width: 100%; height: 100%; display: none;"></div>
<div id="designer-id" style="width: 100%; height: 100%;"></div>
<script>
// ... declaring auxiliary variables/functions
var makeOptions = function(baseOptions, additionalOptions) {
return $.extend({}, baseOptions || {}, additionalOptions || {});
}
designer.renderApplication('designer-id', {
serverApi: makeOptions(baseServerApi, {
/* Required if Templates are available */
// getTemplatesList: null,
/* Required for using Semantic Models */
// getSemanticModelsList: null, getSemanticModelContent: null, getSemanticModelSummary: null,
/* Required for creating/editing embedded Data-Sets based on server Data-Sources */
getDataSourcesList: null, validateDataSetQuery: null, getDataSetQueryStoredProcedureParameters: null, getDataSetQuerySchema: null,
/* Required for using server Data-Sets */
getDataSetsList: null, getDataSetContent: null,
/* Required for using server Styles */
// getStylesList: null, getStyleContent: null,
}),
/* File-View */
openFileView: function(options) {
showFileView();
var fileViewOptions = makeOptions(options, {
serverApi: makeOptions(baseServerApi, {
/* Required if Templates are available */
// getTemplatesList: null, getTemplateThumbnailUrl: null,
/* Required for using Semantic Models */
// getSemanticModelsList: null,
/* Required for using server Data-Sets */
getDataSetsList: null,
}),
createReport: designer.api.createReport,
openReport: designer.api.openReport,
saveReport: designer.api.saveReport,
onClose: function() {
showDesigner();
},
});
fileview.renderFileView('file-view-id', fileViewOptions);
},
/* Report Viewer */
openViewer: function(options) {
showViewer();
var viewerOptions = makeOptions(options, {
onClose: function() {
showDesigner();
},
});
viewer.renderViewer('report-viewer-id', viewerOptions);
},
});
</script>
Therefore, if certain functionality from the serverApi properties of Designer and File-View is not needed, you can simply uncomment the related line to set the corresponding functions to null.
Here we re-use code from the Exact-Purpose Designer example and modify only making fileViewOptions variable:
var fileViewOptions = makeOptions(options, {
serverApi: baseServerApi,
createReport: designer.api.createReport,
openReport: designer.api.openReport,
saveReport: designer.api.saveReport,
aboutInfo: makeOptions(designer.getAboutInfo(), {
applicationTitle: 'GrapeCity Web Report Designer',
}),
// aboutInfo: null,
onClose: function() {
showDesigner();
},
});
If you open Designer and click File, you will see that now application title has changed. Other properties from AboutInfo object can be overwritten in the same way.
Also it is possible to hide About tab completely by setting aboutInfo property to null.
Similar to the Overwrite File-View About Info example, we just modify making fileViewOptions variable:
var fileViewOptions = makeOptions(options, {
serverApi: baseServerApi,
createReport: designer.api.createReport,
openReport: designer.api.openReport,
saveReport: designer.api.saveReport,
helpInfos: designer.getHelpInfos().concat([
{
title: 'ActiveReports 12 User Guide',
link: 'http://help.grapecity.com/activereports/webhelp/AR12/webframe.html#ActiveReports.html',
},
]),
// helpInfos: null,
onClose: function() {
showDesigner();
},
});
If you open Designer and click File, you will see that now Help tab contains more information - an additional link - see HelpInfo object for reference.
Same as for About tab, it is possible to hide Help tab completely by setting helpInfos property to null.
type DesignerOptions = {
// Specifies server-api calls for getting server resources,
// e.g. reports, themes, data-sources, etc.
serverApi: object,
// If the locale value is not specified explicitly here,
// the locale corresponding to the browser preferences is used
locale?: string, // Designer supports en/zh/ja locales
// Specifies whether 'Save' button needs to be shown.
// This button is shown by default.
saveButton?: object {
hide?: boolean,
},
// Specifies whether 'Save As' button needs to be shown.
// This button is shown by default.
saveAsButton?: object {
hide?: boolean,
},
// Specifies custom About info - shouldn't be documented.
// That is useful for white-label Designer.
aboutInfo?: AboutInfo,
// Specifies custom Help infos - shouldn't be documented.
// That is useful for white-label Designer.
helpInfos?: Array<HelpInfo>,
// Determines whether File-View is available and
// how File-View is rendered. The function is optional.
openFileView?: { (fileViewBaseOptions: object): void },
// Determines whether Viewer is available and
// how Viewer is rendered. The function is optional.
openViewer?: { (viewerBaseOptions: object): void },
}
type AboutInfo = {
// Application title replaces 'ActiveReports Web Designer'
// in all the places where it is used by default.
applicationTitle?: string,
// Compact application title is used in places
// where there is not enough space for a full title.
applicationTitleCompact?: string,
// By default the product title correlates with the back-end.
// However, it is possible to overwrite it.
productTitle?: string,
// The same is applicable for the product version - by default
// it is taken from the back-end but can be overwritten.
productVersion?: string,
}
type HelpInfo = {
// Help page title
title?: string,
// Help page url
link: string,
}
type FileViewBaseOptions = {
token: string, // Authentication token
serverApi: object, // Specifies server-api calls for getting server resources
locale: string, // Designer supports en/zh/ja locales
mode: string, // Designer supports new/open/save/saveAs modes
// 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>,
}
type FileViewReportInfo = {
id?: string,
name: string,
permissions: Array<string>,
isTemplate?: boolean,
}
type ViewerBaseOptions = {
token: string, // Authentication token
serviceUri?: string, // Base URI for Viewer REST API calls
locale?: string, // Designer supports en/zh/ja locales
// Information about the report to-be-previewed
reportInfo: ViewerReportInfo,
}
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,
}
// If templateInfo is specified for report creation,
// either id or content needs to be defined.
type TemplateInfo = {
name: string,
id?: string,
// Template content in JSON format that can be useful
// in case you would like to create a non-empty new report
content?: object,
}
type ModelInfo = {
//
id: string,
// If version is not specified explicitly,
// then the latest model version will be used.
version?: number|string,
}
type DataSetInfo = {
// Please pay your attention
// to the underscore in _id.
_id: string,
}
// For report opening either id or content has to be defined.
type OpenReportInfo = {
name: string,
id?: string,
// Report content in JSON format
content?: object,
permissions: Array<string>,
isTemplate?: boolean,
}
type SaveReportInfo = {
// The correct name needs to be always specified explicitly.
name: string,
// If an existing report is to be overwritten on saving,
// the correct id should be specified explicitly.
id?: string,
// Specifies whether report should be saved as template.
isTemplate?: boolean,
// If description shouldn't be changed,
// null value should be passed explicitly.
description?: string,
// Here you can specify changes made
// within this report revision.
comment?: string,
}