The Cubbles IFrame API
Purpose
Cubbles supports the integration of any component into a webpage using the HTML iframe element.
This is a useful option if:
You are not allowed to place any
<script>element into the page.The component's integration via the Cubbles Tag API has side-effects onto the embedding page:
styling side-effects - e.g. if CSS declarations within the component are not consequently defined within their own namespace.
functional side-effects - e.g. if JavaScript dependencies used by the component are in conflict with javascript dependencies of the embedding page.
The RTE contains a html-resource:
that can be referenced using the src-attribute of an
iframeelement,with parameters to
define the component to be loaded
initialize the component with proper values
add dependencies
The following sections present a demo to show the proper use of the Cubbles iframe functionality.
Demo
Prerequisites
The
webpackageIdof the component to be embedded is known (e.g. my-webpackage@1.0.0-SNAPSHOT).The
artifactIdof the component to be embedded is known (e.g. my-component).
Sample case
Let's say you want to show a line chart presenting the sales behavior of your store during the first 4 months of the current year. To aim that, you can use the line-chart component. Let's assume that your sales behavior was as shown in the following table:
Month
Sold Units of Product A
Sold Units of Product B
January
1000
300
February
500
400
April
1100
500
March
1500
700
Using iframe app
The iframe app allows users to visualize a component within any web page using the html iframe element. To aim that, the webpackageId and the artifactId of the component should be provided as url parameters. Additionally, the initial values of the component's slots and additional dependencies can be provided using JSON format as url parameters.
The iframe app is available at https://cubbles.world/sandbox/cubx.core.rte@3.0.0-SNAPSHOT/iframe. Therefore, to use it you should provide the url as THE src attribute of an iframe element as follows:
<iframe src="https://cubbles.world/sandbox/cubx.core.rte@3.0.0-SNAPSHOT/iframe"></iframe>Note that the app itself loads nothing, first it should be initialized. The following sections present this process in detail.
Component initialization (Mandatory)
To initialize the iframe, you should provide the following data of the component:
webpackageId: in this case it is com.incowia.lib.chart-library@1.0.0
artifactId: in this it is case line-chart
To provide those ids you should use the webpackge-id and the artifact-id url parameters as shown below:
<iframe src="https://cubbles.world/sandbox/cubx.core.rte@3.0.0-SNAPSHOT/iframe/index.html?webpackage-id=com.incowia.lib.chart-library@1.0.0&artifact-id=line-chart&dependencies=[]"></iframe>Note: although single quotes are not JSON valid, you can use them to denote a string since double quotes are used to enclose HTML attributes values.
Result of component initialization
The result of the code above may look as follows:
Check this demo to see the result running online.
Component's slots initialization (Optional)
Until now the line chart is empty so you need to provide initial values for the line-chart component. We should use the inits parameter, which accepts the slots values in JSON format, i.e., {"slot1Name": slot1Value, "slot2Name": slot2Value}.
In our case we need to initialize the component as follows:
Slot name
Slot value
dataColumns
[["Product A", 1000, 500, 1500, 1100],["Product B", 300, 400, 700, 500]]
xLabels
["January", "February", "March", "April"]
The iframe should look as follows:
<iframe src="https://cubbles.world/sandbox/ cubx.core.rte@3.0.0-SNAPSHOT/iframe/index.html?webpackage-id=com.incowia.lib.chart-library@1.0.0&artifact-id=line-chart&inits={'dataColumns':[['Product A',1000,500,1500,1100],['Product B',300,400,700,500]],'xLabels':['January','February','March','April']}&dependencies=[]"></iframe>Result of inits initialization
The result of the code above may look as follows:
Check this demo to see the result running online.
Adding dependencies (Optional)
You can also add Cubbles dependencies to the component using the dependencies parameter, which accepts an array (JSON format) containing the dependencies like this: [{ "webpackage-id" : "valueX", "artifact-id" : "valueY"}, ...].
For instance if you want to add our bootstrap utility as dependency the code should look as shown below:
<iframe src="https://cubbles.world/sandbox/ cubx.core.rte@3.0.0-SNAPSHOT/iframe/index.html?webpackage-id=com.incowia.lib ... &dependencies=[{'webpackage-id':'bootstrap-3.3.5@1.4.0','artifact-id':'bootstrap'}]"></iframe>You might want the Cubbles
iframeto be resized to adjust to its content. Then, check the The Cubbles IFrame Resizer API to know how to do it.
Last updated