Scripting for biExport for SAC
Today's blog post is rather technical. It shall give SAC Application developers an overview of the script methods that are available with the biExport Custom Widget. Read Using Events with biExport for SAC for an overview of supported events.
For better clarity, the script methods are divided in:
- General Export methods: Start the export, set "complex" properties such as Custom Texts and Selected Widgets
- Briefing Book methods: Realize "Briefing Book" scenarios with these "special" methods
- Property Setters: Set the current state of a "simple" string or boolean property
- Property Getters: Get the current state of a "simple" string or boolean property
- Display Control methods: Dynamically change the standard export button and dialogues
In general, all properties that you can set statically in the Additional Properties pane can alo be set dynamically via scripting using the Setters and Getters. As SAC currently does not support complex javascript objects in the script method interfaces, some properties (see General Export methods and Briefing Book methods) currently can only be set via special script methods, not via static properties or Setters / Getters.
For each method we describe the usage scenario and - if available - the parameters. Two parameters are used in multiple method interfaces, though, and therefore described already here:
- format: The export format: "PDF", "PPT", "DOC", "XLS"
- value: A string / boolean that shall be set by the Setter
General Export Methods
The usage of these methods is also described with the help of examples in separate blog posts.
Script Method
Usage
Script Method
doExport(format)
Usage
Triggers the export process into the given format.
Script Method
scheduleExport(format, schedule, user)
Usage
Creates a job in the biExport Scheduler.
Script Method
addSelectedWidget (format, widget, isSelected)
Usage
Add a widget to be exported.
- format
- PPT, XLS, DOC, PDF
or tables (to enable/disable retrieve additional data). - widget
- The name of the Widget.
- isSelected
- Set to true to select, set to false to exclude
Script Method
clearSelectedWidgets(format)
Usage
Clears all applications to be exported during background execution.
Script Method
addCustomText(name, value)
Usage
Add a Custom Text to replace a placeholder in the export.
- name
- The name of the placeholder in the Export Template.
- value
- The text to be displayed for the placeholder.
Script Method
clearCustomTexts()
Usage
Clears all Custom Texts.
Script Method
getScriptMessages()
Usage
Access the messages returned from the Export Service.
Briefing Book Methods
The usage of these methods is also described with the help of examples in a series of Briefing Book related posts.
Script Method
Usage
Script Method
addExportApplication(id)
Usage
Add an application to be exported during background execution.
- id
- The id of the application.
Script Method
addExportStory(id)
Usage
Add a story to be exported during background execution.
- id
- The id of the story.
Script Method
clearExportApplications()
Usage
Clears all applications to be exported during background execution.
Script Method
addURLParameter (name, values[], iterative, applicationIds[])
Usage
Add an URL parameter and value which is used during background execution.
- name
- The name of the URL parameter.
- values
- The values for the URL parameter.
- iterative
- Whether the URL parameter values should be iterated over.
- applicationIds
- The applications for which the URL parameter will be used, if empty the URL parameter is used for all applications.
Script Method
clearURLParameters()
Usage
Clears all URLs parameters which are used during background execution.
Script Method
addExportTemplateSection (format, template, pageBreakAfter, placeholderRedefinitions[], placeholderValues[])
Usage
Add a new section to a Dynamic Template Definition for the given format.
- template
- The PowerPoint, Word or Excel Export Template which shall be used for this particular section.
- pageBreakAfter
- Set to "true" for now
- placeholderRedefinitions (optional)
- With this Array of {"name": "myPlaceholder", "value": "myNewPlaceholder"} strings you can replace placeholders in the Export Template with specific Widget placeholders for this section.
- placeholderValues (optional)
- With this Array of {"name": "myPlaceholder", "value": "textToReplace"} strings you can replace placeholders in the Export Template with a static value.
Script Method
clearExportTemplateSections (format)
Usage
Clears the Dynamic Template Definition for the given format.
Script Method
addPdfSection (name, header, footer, content, orientation, iterative)
Usage
Add a new HTML-formatted section for a complex PDF export with changing page orientations or headers / footers. You can even create simple title pages. If you want to create more complex layouts, use addExportTemplateSection instead.
- name
- The name of the section
- header
- The header of the PDF section in HTML format with optional placeholders
- footer
- The footer of the PDF section in HTML format with optional placeholders
- content
- The content of the PDF section in HTML format with placeholders
- orientation
- "P"ortrait or "L"andscape.
- iterative
- true: If multiple views are collected (addURLParameter) this section will be cloned for each view
Script Method
clearPdfSections
Usage
Clears the PDF Template Definition for the given format.
Script Method
addBriefingBookDefinition (parameters[], index, filename, template, customTexts, selectedWidgets, applicationIds)
Usage
Add a Briefing Book Definition which is used during background execution.
- parameters
- The url parameters to be passed to the application in JSON notation {"name": "myUrlParameter", "value": "itsValue"}
- index
- Ordinal of the execution.
- filename (optional)
- The filename to which the results of the application shall be added.
- template (optional)
- The Export Template which shall be used for this particular execution.
- customTexts (optional)
- The custom texts to be replaced in the Export Template for this particular execution {"name": "myPlaceholder", "value": "textToReplace"}
- selectedWidgets (optional)
- The widgets to be added into the export document.
- applicationIds (optional)
- The applications for which the URL parameter will be used.
Script Method
clearBriefingBookDefinitions()
Usage
Clears all Briefing Book Definitions which are used during background execution.
Script Method
setStaticWidth(value)
Usage
Set the width for the background execution browser to get an export of the application as designed (integer).
Script Method
setStaticHeight(value)
Usage
Set the height for the background execution browser to get an export of the application as designed (integer).
Script Method
getStaticWidth(value)
Usage
Get the width for the background execution browser (integer).
Script Method
getStaticHeight(value)
Usage
Get the height for the background execution browser (integer).
Property Setters
Script Method
Usage
Script Method
setExportTemplate(format, value)
Usage
Set the Export Template (String) for a given Export format.
Script Method
setServerUrl(value)
Usage
Set the Url of the biExport service if you are not using the biExport Cloud service (String).
Script Method
setLicenseKey(value)
Usage
Set the License Key if you are using the biExport Cloud service (String).
Script Method
setFilename(value)
Usage
Set the filename for the document that is returned (String).
Script Method
setExportLanguage(value)
Usage
Set the language that is used for the export (String). This is used for Excel exports or for background executions.
Script Method
setParseCss(value)
Usage
Enable the Parse Css logic (boolean), which should be used if icons or images are missing in the Export document.
Script Method
setBiAnalyticsDocument(value)
Usage
Set whether a biAnalyticsDocument document with native tables, texts and charts (true) or a static document with images (false) shall be created.
Script Method
setPublishMode(value)
Usage
Set the Publish Mode (String), i.e. how the Export document is delivered: ONLINE, MAIL, FILE, SHAREPOINT, custom targets.
Script Method
setPublishSync(value)
Usage
Set whteher the export process runs synchronuously even if the file shall not be returned to the user (true) or asynchronously.
Script Method
setMailFrom(value)
Usage
Set the mail sender (String) for Publish Mode MAIL.
Script Method
setMailTo(value)
Usage
Set the mail recipient(s) (String) for Publish Mode MAIL.
Script Method
setMailSubject(value)
Usage
Set the mail subject (String) for Publish Mode MAIL.
Script Method
setMailBody(value)
Usage
Set the mail body (String) for Publish Mode MAIL.
Property Getters
Script Method
Usage
Script Method
getExportTemplate(format)
Usage
Get the Export Template (String) for a given Export format.
Script Method
getLicenseKey()
Usage
Get the License Key (String).
Script Method
getServerUrl()
Usage
Get the Url of the biExport service (String).
Script Method
getFilename()
Usage
Get the filename for the document that is returned (String).
Script Method
getExportLanguage()
Usage
Get the language that is used for the export (String).
Script Method
getParseCss()
Usage
Get the setting for the Parse Css property (boolean).
Script Method
getBiAnalyticsDocument()
Usage
Get the biAnalyticsDocument property (boolean).
Script Method
getPublishMode()
Usage
Get the Publish Mode (String).
Script Method
getPublishSync()
Usage
Get the Publish Sync property (boolean).
Script Method
getMailFrom()
Usage
Get the mail sender (String).
Script Method
getMailTo()
Usage
Get the mail recipient(s) (String).
Script Method
getMailSubject()
Usage
Get the mail subject (String).
Script Method
getMailBody()
Usage
Get the mail body (String).
Display Control Methods
For best user experience, we recommend to include the export with the doExport(format) method on an onClick event of a toolbar icon or similar UI element. In this scenario, you would deactivate all UI elements statically in the biExport Widgets properties. However, you can also dynamically control rendering of the standard export button.
Script Method
Usage
Script Method
setButtonIconVisible(value)
Usage
Set the visibility of the button icon (boolean)
Script Method
setButtonTextVisible(value)
Usage
Set the visibility of the button text (boolean)
Script Method
setCsvButtonVisible(value)
Usage
Set the visibility of the CSV export button (boolean)
Script Method
setDocButtonVisible(value)
Usage
Set the visibility of the Word export button (boolean)
Script Method
setPdfButtonVisible(value)
Usage
Set the visibility of the PDF export button (boolean)
Script Method
setPptButtonVisible(value)
Usage
Set the visibility of the PowerPoint export button (boolean)
Script Method
setXlsButtonVisible(value)
Usage
Set the visibility of the Excel export button (boolean)
Script Method
setPngButtonVisible(value)
Usage
Set the visibility of the Image export button (boolean)
Script Method
setViewSelectorVisible(value)
Usage
Set the visibility of the View Selector (boolean)
Script Method
setWidgetSelectorVisible(value)
Usage
Set the visibility of the Widget Selector (boolean)
Script Method
getButtonIconVisible()
Usage
Get the visibility of the button icon (boolean)
Script Method
getButtonTextVisible()
Usage
Get the visibility of the button text (boolean)
Script Method
getCsvButtonVisible()
Usage
Get the visibility of the CSV export button (boolean)
Script Method
getDocButtonVisible()
Usage
Get the visibility of the Word export button (boolean)
Script Method
getPdfButtonVisible()
Usage
Get the visibility of the PDF export button (boolean)
Script Method
getPptButtonVisible()
Usage
# Get the visibility of the PowerPoint export button (boolean)
Script Method
getXlsButtonVisible()
Usage
Get the visibility of the Excel export button (boolean)
Script Method
getPngButtonVisible()
Usage
Get the visibility of the Image export button (boolean)
Script Method
getViewSelectorVisible()
Usage
Get the visibility of the View Selector (boolean)
Script Method
getWidgetSelectorVisible()
Usage
Get the visibility of the Widget Selector (boolean)
