Smart Doc Editor Utils
Last updated
Was this helpful?
Last updated
Was this helpful?
Contents
Servoy ships a component for rich in-app document editing. To compliment this component, we introduced this svyUtils$documentEditor
module as part of the SvyUtils
offering. This module provides additional utilities to manage custom tag libraries, document merge and PDF export.
Install the component via the Servoy Package Manager (SPM), if you have not already. Help > Download Install with SPM
This is a required dependency.
Then install the svyUtils$documentEditor
module, also via the SPM. (Choose the "Modules" tab.) The module should be added as a dependency to your project, and the API will be available to you. You're ready to begin coding.
This module provides methods to embed custom data-bound tag libraries in the component with a simple API. The tags allow end users do design custom documents which can easily be . This gives the best experience for end-users, who won't need to understand anything about your database or your code.
For more info on tag libs and how to set tags at design-time, please see the wiki topic on mention feeds.
Basic Example
The list of available field tags is shown in a type-ahead selector whenever the #
key is pressed. The result could look something like this:
Customize Tag Display Value
Each tag has a displayValue
, which is what the user will see.
The result could look something like this:
Showing Related Data
The result could look something like this:
Formatting Data
Ignore dataprovider validation
In the given sample there will be no validation done for the field CURRENT_DATE on the selected datasource.
Repeater Tags
The list of available repeater tags is shown in a type-ahead selector whenever the $
key is pressed. For example:
The result could look something like this:
You can see that a $startRepeater
tag was automatically generated for the quantity
field. This is ideal, because we know that each order can have many order detail lines. But also notice that no repeater tags were created for the productname
field. This is because the (3rd) repeats
parameter was explicitly set to false
, as we know that order_details_to_products
is a 1:1 relation.
When the document is merged, the tags will be replaced with record data. For example:
The result could look something like this:
Overwrites
THe merge function supports also overwrites That means that each tag or repeat or if tag can be validated.
As you can see we have 3 extra functions defined in the mergeTags call. Each function will be called for each tag or item that it finds.
ifParser function
In this case the function is called when it is given to the mergeTags function.
The sample code is checking if the realValue of the ifTag matches the value. When it is doing that it is returning false, in the merge this will result in a complete remove of the block. While true will only remove the if tags.
mentionOverwrite function
In this case the function is called when it is given to the mergeTags function.
The sample code is checking if the realValue of the mention matches the value. This can overwrite every value.. and when there is a format set it will also format that value. When you return null it will hide the tag value
repeatOverwrite function
In this case the function is called when it is given to the mergeTags function.
The sample code is checking if the realValue of the mention matches the value. This is almost the same as an ifTag so you can really use it to filter data.
Here's a quick example:
Export Options
API Key
Converting rich HTML documents to PDF is no small task and Servoy delivers this functionality as a commercial-strength cloud service, greatly reducing the distribution footprint and developer requirements needed. All you need is an API key and a few lines of code to turn documents into PDFs.
Obtain an API Key
Register your key
There are two ways to register your key:
By Configuration: Open your properties configuration file <SERVOY_HOME>/application_server/servoy.properties
and set the following property: svyDocumentEditorAPIKey=<your-secret-key>
. This is the preferred approach for deployments. Note: that should only edit the properties file when the Servoy Developer or App Server instance is stopped.
Unlimited Printing
A top-level scope svyDocEditor
which contains a simple object-oriented API to extend the Smart Docs Editor component.
Class Summary
An simple object to wrap a document editor component instance, exposing basic methods
Used to build tag libraries to a bound editor instance
Used to generate document exports (PDF)
Field Summary
ORIENTATION
PAGE_SZE
Method Summary
Gets a new doc editor instance.
Gets an exporter to configure and export documents
Merges a document template with data, returning the merged content.
None
Registers/overrides API key for document export service
Method Details
getInstance
Gets an instance of document editor for the specified component.
Params:
editor
The real doc editor component
required
Example:
getExporter
Gets an exporter to configure and export documents
Params: None
Example:
mergeTags
Merges a document template with data, executing repeater tags, replacing field tags and returning the merged content.
Params:
content
The document template to be merged
required
data
The data which will be merged
required
Example:
registerAPIKey
Params:
apiKey
Your private API key
required
Returns: None
Example:
An simple class to wrap a document editor component instance, exposing basic methods.
Method Summary
Gets a tag builder instance bound to this editor
Gets the HTML content from this editor object, with options to inline CSS and filter style sheet.
Merges this editor's content with data, includes options to inline CSS and filter style sheet.
Method Details
tagBuilder
Gets a tag builder instance bound to this editor.
Params:
dataSource
The data source to use for building tags. Can be the name or the actual data source object.
required
Example:
getContent
Gets this editor's content, optionally with inline CSS and filtered stylesheet. Ideal to save or export the content.
Params:
Boolean
withInlineCSS
Option to also inline the CSS when merging. This is recommend if the result will be exported. Note: There is a performance impact, so this parameter should be ignored if the result will be rendered in the component anyway.
optional: default is false
filterStyleSheetName
The style sheet name to filter. Only this style sheet will be inline. This is ideal for a custom style to be used, say in an email template. Note: The path and .css extension should be skipped.
optional
Example:
mergeTags
Params:
data
The data which will be merged
required
Boolean
withInlineCSS
Option to also inline the CSS when merging. This is recommend if the result will be exported. Note: There is a performance impact, so this parameter should be ignored if the result will be rendered in the component anyway.
optional: default is false
filterStyleSheetName
The style sheet name to filter. Only this style sheet will be inline. This is ideal for a custom style to be used, say in an email template. Note: The path and .css extension should be skipped.
optional
Example:
TagBuilder
Method Summary
Add a specified data provider as a field tag
none
Applies the tag lib to the document editor component
Returns the field tags as data set, ideally used in a value list in a custom toolbar item.
Method Details
addField
Params:
dataProviderID
The data provider, relative the builder's data source. Can be a column, calculation, aggregate or related data provider.
Required
displayTag
Optional
Boolean
repeats
An optional flag to specify if a related data provider should generate repeater tags. Ideally, this is used to omit 1:1 relations.
Optional, default is true
Example:
build
Applies the tag lib to the bound document editor component.
Params: None
Returns: None
Example:
getFields
Returns this builder's field tags as data set, ideally used in a value list
Params: None
Example:
Exporter
An object to configure and generate document exports (PDF)
Method Summary
Adds additional head tags to the exported content
Array<byte>
Exports the content to PDF.
Sets the content to be exported
Set/Override the css in the exporter
Sets the image URL
Sets the page margins
Sets the page orientation
Sets the page size
Method Details
addHeadTag
Adds additional head tags to the exported content. Head tags can carry additional metadata and style info to the exported PDF.
Params:
headTag
The head tag to be added
Required
Example:
exportToPDF
Exports to PDF with
Params: None
Returns: Array<byte> The PDF file bytes
Example:
setContent
Sets the content to be exported.
Params:
content
The content to exported
Required
Example:
setCSS
Sets the CSS to be use in the export. In this way, CSS can be inlined and the PDF is self-contained.
Params:
css
The CSS to be used
Required
Example:
setMargin
Sets the page margins
Params:
top
The top margin
Required
right
The right margin
Required
bottom
The bottom margin
Required
left
The left margin
Required
Example:
setOrientation
Sets the page orientation
Params:
orientation
Required
Example:
setPageSize
Sets the page size
Params:
pageSize
Required
Example:
As you can see, a object was created and bound to the runtime component. Then a object was then requested and bound to a specific data source datasources.db.example_data.orders
. The tag builder can then generate field tags, using the method. Each field can be a primary or related DataProvider
in the context of the tag builder's data source.
By default, the will generate a default value based on the data provider. If it's a real column in the tag builder's data source, the property is used. If the title property is empty, or the data provider is derived (i.e. calculated or aggregated), then the builder will prettify the name, with capital casing and spaces. For example, product_description
would become Product Description
. When this property starts with i18n:
it will translate the value.
Custom display values can be specified with the method as an optional parameter displayValue
. For example:
The can generate data-bound tags for any path in your data model, as long as it is traversable from the data source. Simply add the full path of the related data provider as a String
. For example:
The supports also formats, in that case when replacing the tags the format will be applied to the given data.
In the given sample the format dd-MM-yyyy
will be applied when the document is done
The also supports fields that are not real fields. This can be used in combination with
Because tag libraries are data-bound, they can be used to generate repeating content. This happens automatically when is specified in the method. The TagBuilder assumed a related could have many records. Therefore any related data provider will also generate a repeat tag, unless the boolean repeats
argument is set to false
.
When the document is , all the content between the $startRepeater
tag and the $endRepeater
will be repeated for each record in the repeater tag's related .
A document editor component can be initialized to have embedded in it. Each tag contains a display value (what the user will see) and a real value (what the application will see). There are also , that specify where content will be repeated.
Here, the instance method . was called and the selected record a form's foundset was used for the data source. The merged document is returned as a string, and in this case, it is set back into the content
data provider to which the editor component is bound. The editor will render the merged document (like a print preview!).
As you can see the #
field tags were replaced with the actual record data from the orders
table. And the from the order_details
and products
tables were also merged. The $
repeater tags were applied to the 3 records in the related orders_to_order_details
foundset. (You may also notice that the table header was intuitively skipped.)
If you have made it this far, then you probably want to print, email or archive a merged document. Fortunately this module provides support for PDF export. Content from the Smart Docs Editor maybe converted to PDF format using a simple .
Here the method was used to return an object, which has methods to set content, among other options.
The supports various options, such as page size, orientation and margins to name a few. Here is an example of exporting with additional options:
You can obtain a FREE key from the . From the navigation choose "Add-Ons", and under "Document Printing", click "Generate Key". Your secret key will be displayed. Copy it to your clipboard.
At Runtime: Use the method to set the key dynamically. This is ideal for testing in development. It will override any configuration.
The PDF export service is FREE and subject to daily quotas and limitations. It is ideal for testing purposes and low-volume production scenarios. to unlimited printing for high-volume production scenarios and a dedicated document server.
Enum<>
An enum which describes export options for the property, including PORTRAIT
and LANDSCAPE
.
Enum<>
An enum which describes export options for the property. Currently, only A4
is supported.
<SmartDocumentEditor>
Returns:
Returns:
Returns: The content which
Registers/overrides for document export service, ideally for development/testing. It should be called before using the . The key can also be set in the servoy.properties
file using the property name svyDocumentEditorAPIKey
, ideally for production/deployment.
|
Returns: which can generate tags for this editor
Returns: The content from this editor, with optional inline CSS and filtered stylesheet.
Merges this editor's current content with data, executing repeater tags, replacing field tags and returning the merged content. (This is a convenience method to combine scope-level method with this editor's .)
Returns: The merged content
A class used to build for a bound component.
Add a specified data provider as a field tag. If the data provider is a , then this tag builder may also generate for the relation.
An optional display value for the tag. If none specified, then property is used for a real column. If the title property is empty, or the data provider is derived (calculated or aggregated), then the builder will prettify the name, with capital casing and spaces.
Returns: for call chaining.
Returns: The field tags, which can be used in a value list.
Returns: for call chaining.
Returns: for call chaining.
See Also: .
Returns: for call chaining.
Returns: for call chaining.
The page orientation, must be one of enum
Returns: for call chaining.
See Also:
Page size, must be one of enum
Returns: for call chaining.
See Also: