This webpackage contains certain artifacts representing the Cubbles Runtime Environment (RTE):
- Webpackage cubx.core.rte
The CRC-Loader is responsible for getting the Client Runtime Container (CRC). To integrate the Cubbles runtime into your web app you need to include the CRC-Loader via script tag:
<head>
...
<!--
Replace "https://cubbles.world/core" with the url of the Cubbles Base Store you would like to use.
Include webcomopnents polyfill. This is needed to enable HTML5 Features in IE11 and Firefox.
-->
<script src="https://cubbles.world/core/cubx.core.rte@4.0.0-SNAPSHOT/webcomponents/webcomponents.bundle.js"></script>
<script src="https://cubbles.world/core/cubx.core.rte@4.0.0-SNAPSHOT/crc-loader/crc-loader.bundle.js"></script>
...
</head>There are several options for configuring the CRC-Loader respectively the loaded CRC:
If true the CIF is loaded. Set this to false to prevent CRC from loading the CIF. This can be set using attribute data-crcinit-loadcif="true|false" on the <script> tag of the CRC-Loader.
Alternatively you can use global window.cubx.CRCInit object:
<script>
window.cubx = {
CRCInit: {
loadCIF: true|false
}
}
</script>Declare the runtimeMode that is used. Each artifact can have an arbitrary number of resources defined (JS, HTML Imports, CSS). Each of those resources can have properties dev and prod holding the filename
used for the corresponding runtime mode. If runtime mode is set to prod the file given from property prod is used. If runtime mode is set to dev the file given for property dev is used instead.
Set runtime mode using URL-Search parameter ?runtimeMode=dev|prod or global window.cubx.CRCInit object:
<script>
window.cubx = {
CRCInit: {
runtimeMode: "dev|prod"
}
}
</script>If set to true it is possible to use absolute urls for resources. Set it using allow-absolute-resource-urls="true|false" on the <script> tag of the CRC-Loader.
Alternatively, you can use global window.cubx.CRCInit object:
<script>
window.cubx = {
CRCInit: {
allowAbsoluteResourceUrls: true|false
}
}
</script>Set a custom event name to trigger RTE bootstrap process using data-cubx-startevent="[eventName]" on the <script> tag of the CRC-Loader. The listener for this event will be attached to document.
Set dependencies which should be resolved by CRC during bootstrap. Use global window.cubx.CRCInit.rootDependencies array to set.
<script>
window.cubx = {
CRCInit: {
rootDependencies: [
{
artifactId: 'first-demo-component'
webpackageId: 'demo-package@1.0',
// optional properties
endpointId: 'main-endpoint', // needed when referenced webpackage uses modelVersion < 9
manifest: {
//.... Put your manifest here. Note: this needs to be a full valid webpackage.manifest regarding to document api
// for more details see: https://github.com/cubbles/cubx-webpackage-document-api/wiki
}
}
]
}
}
</script>This will add artifact first-demo-component from webpackage demo-package@1.0.
Set dependencies which should be excluded during the dependency resolution process. Use global window.cubx.CRCInit.rootDepenencyExcludes array to set.
<script>
window.cubx = {
CRCInit: {
rootDependencyExcludes: [
{
artifactId: 'first-demo-component',
webpackageId: 'demo-package@1.0'
}
]
}
}
</script>This will exclude artifact first-demo-component from webpackage demo-package@1.0.
The Client Runtime Container provides the basic runtime for Cubbles components including:
- identify Cubbles components used in the web app
- resolving the resources needed for instantiating the used components
- make your browser download the needed resources (JS, CSS, HTML Imports, etc.)
The Component Interaction Framework takes care of rendering Cubbles components at runtime inside the DOM tree and establishing and managing data propagation between these Cubbles components based on their declared connections. Furthermore, the CIF provides the Cubbles TAG API.
Enable the CIF inside your web app by including the crc-loader script with attribute data-crcinit-loadcif="true".
A detailed description of the Cubbles TAG API can be found in our Cubbles Docs.
Instantiate a Cubble Component by adding a custom html tag where the tag name is equal to the name of the component (so-called artifactId of the component). The mandatory attribute cubx-webpackage-id points to the webpackage in which the component resides.
Note: The webpackage you are requesting the component from using cubx-webpackage-id needs to be located in the same store like the one where the RTE is requested from.
<body>
...
<first-demo-component cubx-webpackage-id="demo-package@1.0"></first-demo-component>
...
</body>If you want to create a Cubble that is located in a webpackage with webpackage.modelVersion < 9 you additionally need to provide an endpointId:
<first-demo-component cubx-webpackage-id="demo-package@1.0" cubx-endpoint-id="main"></first-demo-component>The corresponding dependency needed for instantiating the first-demo-component will be automatically added to window.cubx.CRCInit.rootDependencies array (if it is not already there).
In many cases, you want to set initial values for the input slots the created Cubble provides. This can be done using the <cubx-core-init> and <cubx-core-slot-init> tags.
Note: Setting style="display:none;" on the <cubx-core-init> tag prevents the browser from displaying the innerHtml values of each <cubx-core-slot-init> before CIF is loaded and bootstraped.
<first-demo-component cubx-webpackage-id="demo-package@1.0">
<cubx-core-init style="display:none;">
<cubx-core-slot-init slot="message">"Hello World!"</cubx-core-slot-init>
<cubx-core-slot-init slot="count">5</cubx-core-slot-init>
<cubx-core-slot-init slot="on">true</cubx-core-slot-init>
<cubx-core-slot-init slot="config">{"label":"Name","value":"John Doe"}</cubx-core-slot-init>
</cubx-core-init>
</first-demo-component>Each <cubx-core-slot-init> needs to have the attribute slot holding the name of the slot for which to set the value. The inner html inside the <cubx-core-slot-init> tag is the value which should be set. This value needs to be valid JSON.
Depending on the type of value the slot expects you can set boolean, string, number or object values. The slot initializations are proceeded by the CIF in the same order there where declared inside the <cubx.core.init> tag.
If you create more then one Cubbles inside your web page it is possible to define connections between them (respectively their provided slots). This can be done using the <cubx-core-connections> and <cubx-core-connection> tags.
<first-demo-component cubx-webpackage-id="demo-package@1.0">
<cubx-core-init style="display:none;">
<cubx-core-slot-init slot="message">"Hello World!"<cubx-core-slot-init>
</cubx-core-init>
<cubx-core-connections>
<cubx-core-connection connection-id="connection1" source="message" destination="second:textInput"></cubx-core-connection>
</cubx-core-connections>
</first-demo-component>
...
<second-demo-component id="second" cubx-webpackage-id="demo-package@1.0"></second-demo-component>Each <cubx-core-connection> needs attributes
connection-idfor setting a unique connection idsourcefor setting the output slot name acting as a source for this connectiondestinationfor setting the target of this connection using[id-of-target]:[name-of-input-slot]
The above example establishes a connection between output slot message of Cubble <first-demo-component> and input slot textInput of Cubble <second-demo-component> with id=second.
Each time the value of slot message changes the CIF takes care of propagating the new value to slot textInput. Assuming slot message is an output and input slot after initialization the value "Hello Wolrd! is immediately propagated
to slot textInput.
There are additional options available for each <cubx-core-connection>:
In case the value of an output slot is renewed without changing the value itself the value ist NOT propagated to the connected slots. This is the default behavior.
If attribute repeated-value is set to true the connection is propagated each time the value for source slot is set also when the value itself is unchanged.
<cubx-core-connection ... repeated-value="true"></cubx-core-connection>By default, the destination slot of a connection will receive a copy of the propagated value. This isolates the models of different Cubbles of each other. In most cases, this is the expected behavior.
If attribute copy-value is set to false the propagated value is not copied. This only is useful if the propagated value is of type object. Depending on the size of the propagated object it is much faster to not copy the value.
<cubx-core-connection ... copy-value="false"></cubx-core-connection>It's possible to declare a hook function that is called with propagated value each time the connection triggers. This can be useful if you need to do some data transformation to fit the target slots expected structure. The hook function will be called with the propagated value and a next callback. The continue the propagation of the connection you have to call the next callback with the value the propagation should be continued:
function (value, next) {
// do your data transformation based on value
var newValue = value * 2;
// call next callback with transformed value
next(newValue);
}To apply such a hook function to a connection just add the hook-function attribute as follows:
Either provide the function string inline :
<cubx-core-connection ... hook-function="function (value, next){ var newValue = value; next(newValue); }"></cubx-core-connection>or provide the name of a function available in the global window scope
<cubx-core-connection ... hook-function="myHookFunction"></cubx-core-connection>Use the <cubx-dependencies> and <cubx-dependency> tags to add additional dependencies. This can be useful if you have only permission to edit certain parts of the DOM tree e.g. when you are a page editor using a CMS like Wordpress
and want to add dependencies. Otherwise, it's also possible to add dependencies using the global window.cubx.CRCInit.rootDependencies property (see rootDependencies).
<first-demo-component cubx-webpackage-id="demo-package@1.0">
<cubx-dependencies>
<cubx-dependency artifact-id="third-party-utility" webpackage-id="third-party-pkg@1.0"></cubx-dependency>
</cubx-dependencies>
</first-demo-component>Each <cubx-dependencies> tag can have an arbitrary number of <cubx-dependency> children. Each <cubx-dependency> tag needs attributes
artifact-idsets the artifactId (= component name) of the dependency to addwebpackage-id(optional) sets the webpackage-id in which the given artifact should is located. If this attribute is omitted the artifact will be searched in the same webpackage as the parent Cubble.endpoint-id(optional) sets the endpoint-id of the dependency to add. This is only needed if you reference a webpackage withwebpackage.modelVersion < 9
Analogous to adding dependencies it is also possible to exclude certain dependencies. Use the <cubx-dependency-excludes> and <cubx-dependency-exclude> tags to do so.
<first-demo-component cubx-webpackage-id="demo-package@1.0">
<cubx-dependency-excludes>
<cubx-dependency-exclude artifact-id="third-party-utility" webpackage-id="third-party-pkg@1.0"></cubx-dependency-exclude>
</cubx-dependency-excludes>
</first-demo-component>Each <cubx-dependency-excludes> tag can have an arbitrary number of <cubx-dependency-excludes> children. Each <cubx-dependency-exclude> tag needs attributes
artifact-idsets the artifactId (= component name) of the dependency to excludewebpackage-id(optional) sets the webpackage-id in which the given artifact is located. If this attribute is omitted the artifact will be searched in the same webpackage as the parent Cubble.endpoint-id(optional) sets the endpoint-id of the dependency to exclude. This is only needed if you reference a webpackage withwebpackage.modelVersion < 9
Note: When you exclude a dependency that is needed by other Cubbles in your DOM tree this exclude will be ignored. In such a case you have to make sure to exclude this specific dependency for each Cubble that uses the dependency.
To make sure a dependency is always excluded you can add it to the global window.cubx.CRCInit.rootDependencyExclucdes array (see rootDependencyExcludes).
A collection of instance methods which each Cubble provides no matter if it is a compound Cubble or an elementary Cubble.
Provides the global CubxComponent() function used for registering a new Cubble component. This is necessary to implement elementary Cubbles components.
Some helpers for DOM tree manipulation.
A set of instance methods which each Cubble provides for handling dynamic connections.
Polyfill to get global Promise support in IE. For more details see es6-promise.
Small utility for generation a guid.
A small app artifact which you can use to render an arbitrary component given by url search parameter inside an iframe. This can be useful if you want to include a Cubble inside your web app but there is no RTE available on the page. For example, if you are only allowed to add standard html when editing a page in a CMS like Wordpress.
Include component first-demo-component from webpackage demo-package@1.0 into your page using iframe:
<iframe src="https://cubbles.world/sandbox/cubx.core.rte@4.0.0-SNAPSHOT/iframe/index.html?webpackage-id=demo-package@1.0&artifact-id=first-demo-component"></iframe>You can also init slots of the component rendered within the iframe:
<iframe src="https://cubbles.world/sandbox/cubx.core.rte@4.0.0-SNAPSHOT/iframe/index.html?webpackage-id=demo-package@1.0&artifact-id=first-demo-component&inits={'message':'Hello World!','config':{'label':'Name','value':'John Doe'}}"></iframe>And finally add additional dependencies:
<iframe src="https://cubbles.world/sandbox/cubx.core.rte@4.0.0-SNAPSHOT/iframe/index.html?webpackage-id=demo-package@1.0&artifact-id=first-demo-component&inits={'message':'Hello World!','config':{'label':'Name','value':'John Doe'}}&dependencies=[{'webpackage-id':'third-party-pkg@1.0','artifact-id':'third-party-utility'}]"></iframe>The purpose of the iframe-resizer is to resize the iframe that displays a Cubbles component automatically according to its content. The width of the iframe will always be 100% while the height is set to the content's height.
To enable resize support for your iframe you need to include resize.js script in the iframe's parent page
<head>
<script src="https://cubbles.world/core/cubx.core.rte@4.0.0-SNAPSHOT/iframe-resizer/resize.js"></script>
</head>and set the iframe's id value which needs to be provided in the src using the iframe-id url search parameter.
<body>
<iframe id="myIframe" src="https://cubbles.world/core/rte@2.1.0/iframe/index.html?iframe-id=myIframe&webpackage-id=demo-package@1.0&artifact-id=first-demo-component"></iframe>
</body>Webcomponents polyfill. This needs to be included before the crc-loader script. It is sufficient to use webcompents-lite.
Webcomponents polyfill. This needs to be included before the crc-loader script (see crc-loader section). For more details see webcomponents.org.