Kestros is currently in beta, all documentation is subject to change. Additional documentation will be added in subsequent releases. Beta releases are not recommended for production use.

Create a New Vendor Library

As the building blocks that make up UI Frameworks, Vendor Libraries are the first thing you should look at when creating a new design.

To create a new Vendor Library create a new folder under frontend/src/content/jcr_root/etc/vendor-libraries/. For now, lets name this folder my-first-library.

Create the Vendor Library Resource

Inside your new vendor library folder, create a file named .content.xml with the following configuration:

<?xml version="1.0" encoding="UTF-8"?>\n<jcr:root\n    xmlns:jcr="http://www.jcp.org/jcr/1.0"\n    jcr:primaryType="kes:VendorLibrary"\n    jcr:title="My First Vendor Library"\n    description="My first Vendor Library description."\n    documentationUrl=""/>

Add CSS and JS

Inside your vendor library folder, create two new folders, css and js. Inside of both folders, create a .content.xml file with the following configuration:

<?xml version="1.0" encoding="UTF-8"?>\n<jcr:root\n    xmlns:sling="http://sling.apache.org/jcr/sling/1.0"\n    xmlns:jcr="http://www.jcp.org/jcr/1.0"\n    jcr:primaryType="sling:OrderedFolder"\n    include="[]"/>

Now let's add a new css file under css named button.less and give it some button styles:

button {\n    background-color: white;\n}

After your stylesheet(s) has been created, add the filename to the include array under the css/.content.xml property. Additional stylesheets can be referenced by separating their filenames with a comma.

Your css/.content.xml file should now look like:

<?xml version="1.0" encoding="UTF-8"?>\n<jcr:root\n    xmlns:sling="http://sling.apache.org/jcr/sling/1.0"\n    xmlns:jcr="http://www.jcp.org/jcr/1.0"\n    jcr:primaryType="sling:OrderedFolder"\n    include="[button.less]"/>

Create a New UI Framework

UI Frameworks provide the backbone for rendering sites in Kestros by:

  • Determining which component view will render
  • Compiling CSS and JS from Vendor Libraries and component views

To create a new UI Framework create a new folder under frontend/src/content/jcr_root/etc/ui-frameworks/. For now, lets name this folder my-first-ui-framework.

Create the UI Framework Resource

Inside your new UI Framework folder, create a file named .content.xml with the following configuration:

<?xml version="1.0" encoding="UTF-8"?>\n<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"\n    xmlns:jcr="http://www.jcp.org/jcr/1.0"\n    xmlns:kes="http://kestros.io/kes/1.0"\n    jcr:primaryType="kes:UiFramework"\n    jcr:title="My First UI Framework"\n    kes:uiFrameworkCode=""\n    kes:vendorLibraries="[]"/>

Add A Framework Code

In order to map your UI Framework to component views, a kes:uiFrameworkCode should be provided. This is generally a shorthand of the UI Framework name. For our example we'll use my-view

<?xml version="1.0" encoding="UTF-8"?>\n<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"\n    xmlns:jcr="http://www.jcp.org/jcr/1.0"\n    xmlns:kes="http://kestros.io/kes/1.0"\n    jcr:primaryType="kes:UiFramework"\n    jcr:title="My First UI Framework"\n    kes:uiFrameworkCode="my-view"\n    kes:vendorLibraries="[]"/>

Reference Your Vendor Library

Vendor Libraries can be referenced in the kes:vendorLibraries property. Referenced Vendor Libraries will be compiled into the UI Frameworks CSS and JS output. Let's add the Vendor Library we created earlier:

<?xml version="1.0" encoding="UTF-8"?>\n<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"\n    xmlns:jcr="http://www.jcp.org/jcr/1.0"\n    xmlns:kes="http://kestros.io/kes/1.0"\n    jcr:primaryType="kes:UiFramework"\n    jcr:title="My First UI Framework"\n    kes:uiFrameworkCode="my-view"\n    kes:vendorLibraries="[my-first-library]"/>

To add custom CSS and JS to a UI Framework, follow the same steps for adding CSS and JS to a Vendor Library.

Add Themes

Themes provide a way to create design variations within a UI Framework. All UI Frameworks must have at least a default

Before creating any Themes, we will need to create a themes folder under your UI Framework's directory.

Add a Default Theme

Under the themes folder, create a new folder named default.

Under the default theme folder, create a .content.xml file with the following configuration:

<?xml version="1.0" encoding="UTF-8"?>\n<jcr:root\n    xmlns:jcr="http://www.jcp.org/jcr/1.0"\n    jcr:primaryType="kes:Theme"\n    jcr:title="Default Theme">\n</jcr:root>

To add overridding CSS and JS to a theme, follow the same steps for adding CSS and JS to a Vendor Library.

Additional Themes can be created in the same way, but are not required.

Set Your Site's Theme

The final step in building a new design is to your new Vendor Library and UI Framework to content package filters, so that they can be installed to Kestros. Add the following lines to frontend/src/content/META-INF/vault/filter.xml to add them to your build:

<filter root="/etc/vendor-libraries/my-first-library"/>\n<filter root="/etc/ui-frameworks/my-first-ui-framework"/>

Your filter.xml file should now look something like:

<?xml version="1.0" encoding="UTF-8"?>\n<workspaceFilter version="1.0">\n    <filter root="/apps/my-site"/>\n    <filter root="/apps/my-site/install" mode="update">\n        <include pattern=".*my-site-core-bundle.*.jar"/>\n    </filter>\n    <filter root="/etc/ui-frameworks/my-site-framework"/>\n    <filter root="/etc/ui-frameworks/my-first-ui-framework"/>\n    \n    <filter root="/etc/vendor-libraries/my-site-vendor-library"/>\n    <filter root="/etc/vendor-libraries/my-first-library"/>\n</workspaceFilter>

Set Your Site's Theme

To use your new UI Framework on your generated site, update the kes:theme value on your site's root configuration to your new default Theme path. Your site's configuration can be found at content/src/content/jcr_root/content/sites/my-site/.content.xml.

The updated configuration should look like:

<?xml version="1.0" encoding="UTF-8"?>\n<jcr:root\n    xmlns:sling="http://sling.apache.org/jcr/sling/1.0"\n    xmlns:jcr="http://www.jcp.org/jcr/1.0"\n    xmlns:nt="http://www.jcp.org/jcr/nt/1.0"\n    xmlns:kes="http://kestros.io/kes/1.0"\n    jcr:primaryType="kes:Site">\n    <jcr:content\n        jcr:primaryType="nt:unstructured"\n        sling:resourceType="my-site/components/pages/my-site-base-page"\n        kes:theme="/etc/ui-frameworks/my-first-ui-framework/themes/default"\n        jcr:title="My Site">\n    </jcr:content>\n</jcr:root>