# Bundle and Component Descriptors
The Entando Component Manager reads the descriptor.yaml
file from the root of the bundle package and uses it to install any components and resources included in the bundle.
The different component types are shown below:
Here is the basic bundle structure:
. ├ descriptor.yaml ├ resources/ │ └ ... └ ... (folders reported in descriptor.yaml file)
Copied!
# Bundle Conventions
The bundle descriptor file must be named
descriptor.yaml
or the bundle will not be recognized.Static resources should be placed in a
resources
folder. They are not explicitly referenced in thedescriptor.yaml
file itself.
# Bundle Descriptor
The bundle descriptor YAML file aggregates all included components and has the structure shown below. Note that the Page Template feature is pageModels
and the Content Template feature is contentModels
.
Warning
The bundle descriptor file must be named
descriptor.yaml
descriptor.yaml
code: survey_bundle # The bundle ID description: This is the survey bundle # The description of the bundle components: # All components are listed here. # Optional. Use if the component requires deployment plugins: - folder/you/want/your_plugin_descriptor.yaml - folder/you/want/another_plugin_descriptor.yaml # To create Widgets, add references to the descriptor files widgets: - widgets/your_widget_descriptor.yaml - widgets/another_widget_descriptor.yaml # To create Fragments, add references to the descriptor files fragments: - fragments/your_fragment.yaml # To create Page Templates, add references to the descriptor files pageModels: - pageModels/your_page_model_descriptor.yaml - pageModels/another_page_model_descriptor.yaml # To create and publish Pages, add references to the descriptor files pages: - page/your_page_descriptor.yaml - page/another_page_descriptor.yaml # To create a CMS Asset, add a reference to the descriptor file in the same location # as the image or file you want to upload assets: - assets/your-asset/your_asset_descriptor.yaml - assets/your-asset/your_image.jpg # To create Content Types, add references to the descriptor files contentTypes: - contentTypes/your_content_type_descriptor.yaml # To create Content Templates, add references to the descriptor files contentModels: - contentModels/your_content_model_descriptor.yaml - contentModels/another_content_model_descriptor.yaml # To create and publish Contents, add references to the descriptor files contents: - contents/your_content_descriptor.yaml - contents/another_content_descriptor.yaml # To create Categories, add references to the descriptor files categories: - categories/your_categories.yaml # To create Groups, add references to the descriptor files groups: - groups/your_groups.yaml # To create Labels, add references to the descriptor files labels: - labels/your_labels.yaml # To enable Languages, add references to the descriptor files languages: - languages/languages.yaml
Copied!
# Plugin
Here is an example of a plugin descriptor:
Plugin descriptor.yaml
# Descriptor version field added in v3 and later. # To take advantage of the environment variables below, v4 will need to be specified. descriptorVersion: "v4" # The Docker image used to create the plugin image: "entando/your-image:1.0.0" # The base name to assign to pods that have to be created in Kubernetes deploymentBaseName: "yourplugin" # The DBMS the plugin will use dbms: "postgresql" # The roles the plugin will expose in Keycloak roles: - "task-list" - "task-get" - "connection-list" - "connection-get" - "connection-create" - "connection-delete" - "connection-edit" # The health check path that Kubernetes will use to check the status # of the plugin deployment healthCheckPath: "/actuator/health" # The ingress path to assign to the plugin deployment ingressPath: "/your-plugin-path" # A list of Keycloak clientIds/roles to bind to one another permissions: - clientId: realm-management role: manage-users - clientId: realm-management role: view-users # A set of environment variables that can be set inline or # referenced as Secrets in the namespace. Supported as of descriptorVersion v4. environmentVariables: - name: SIMPLE_VAR # directly injects the value value: yourSimpleValue - name: SECRET_VAR # leverages a secret value valueFrom: secretKeyRef: name: YOUR-BUNDLE-ID-your-secret key: yourSecretKey
Copied!
TIP
Entando uses the healthCheckPath
to monitor the health of the plugin. A plugin in an Entando Bundle can use any technology, as long as it provides a health check service configured via the healthCheckPath
. This path must be specified in the descriptor file and return an HTTP 200 or success status. This can be implemented by a Java service included with the Entando Blueprint in the Spring Boot application. You can also use a Node.js service as shown here (opens new window).
TIP
See the Plugin Environment Variables tutorial to setup environment variables, either inline or based on Kubernetes Secrets.
# Permissions
The permissions
property specifies a list of coupled clientIds
and roles that will be bound in Keycloak. To find them, open the Keycloak console and navigate to clients
→ awesomeplugin-server
→ Service Account Roles
.
# Widget
Here is an example of a Widget descriptor:
Widget descriptor.yaml
code: another_todomvc_widget # The Widget identification titles: # Widget's Titles en: TODO MVC Widget # Title in English it: TODO MVC Widget # Title in Italian group: free # The owner group of the Widget # Optional. The UI Path, where the widget.ftl file will have the customUi content customUiPath: widget.ftl # Optional. The Custom UI customUi: >- <h1>Your Custom Widget UI</h1> # Optional. The ConfigUI configUi: customElement: todomvc-config # The name of the custom element used to render the configUI resources: - <bundleid>/static/js/main.js # The resources necessary for the custom element to render the configUI, like the code
Copied!
# Fragment
Here is an example of a Fragment descriptor:
Fragment descriptor.yaml
code: your_fragment # The unique ID # Optional. The Fragment content guiCode: >- "<div>Here is the content</div>" # Optional. A path to a FreeMarker file containing the Fragment content guiCodePath: fragment.ftl
Copied!
# Page Template
Here is an example of a Page Template descriptor:
Page Template descriptor.yaml
code: todomvc_page_template # The Page Template identification description: TODO MVC basic page template # The Page Template description titles: # Page Template's Titles en: TODO MVC PageTemplate # Title in English it: TODO MVC PageTemplate # Title in Italian # The Page Template configuration configuration: frames: # All frames - pos: 0 # Frame position description: Header # Frame description sketch: # Frame sketch configuration x1: 0 y1: 0 x2: 11 y2: 1 defaultWidget: code: your-widget # the Widget code to apply when using the button "apply default widgets" in the page configuration UI # A simplified way to define a Frame - pos: 1 description: Breadcrumb sketch: { x1: 0, y1: 0, x2: 11, y2: 1 } # Optional. Define the Page Template in a separate file or inside the descriptor file with `template` templatePath: page.ftl # Optional. Define the Page Template as below or in a separate file with `templatePath` template: >- <#assign wp=JspTaglibs[\"/aps-core\"]> <!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\"> <html> <head> <title><@wp.currentPage param=\"title\" /></title> </head> <body> <h1><@wp.currentPage param=\"title\" /></h1> <a href=\"<@wp.url page=\"homepage\"/>\">Home</a><br> <div> <h1>Bundle 1 Page Template</h1> <@wp.show frame=0 /> </div> </body> </html>
Copied!
# Page
This descriptor enables a page to be created and published via a bundle. Page status can be published
or draft
. The Widget section can be used to fully configure a page layout.
Groups in a page descriptor are configured by ownerGroup
and joinGroups
. The ownerGroup
property specifies the group of users who can manage the entity in the AppBuilder. The joinGroups
property specifies who can view or access the page. For example, setting ownerGroup
to "free" means anyone with access to the AppBuilder can manage the page, whereas setting joinGroup
to "free" means any end user can view the page in the application.
Page descriptor.yaml
code: dashboard parentCode: homepage titles: en: your dashboard it: La mia Dashboard pageModel: dashboard ownerGroup: free joinGroups: [] displayedInMenu: true seo: false charset: utf-8 # ECR will publish the page according to this property status: published|draft # Page Configuration widgets: - code: Brand-Logo config: null pos: 0 - code: Login_buttons config: null pos: 2 - code: seeds_card config: cardname: creditcard pos: 6 - code: list_item config: icon: managealerts count: '0' title: Alerts pos: 7 - code: list_item config: icon: viewstatements count: '0' title: View Statements pos: 11 - code: seedscard-transaction-table config: null pos: 13
Copied!
# CMS Asset
This descriptor contains the metadata required for uploading and updating a CMS Asset.
Asset descriptor.yaml
correlationCode: 'your-reference-code' type: image # This file should be placed in the same folder as the descriptor.yaml name: 113f4437cac3b3f3d4db7229f12287a4_d3.png description: 113f4437cac3b3f3d4db7229f12287a4_d3.png group: free categories: []
Copied!
# Content Template
Here is an example of a Content Template descriptor:
Content-template descriptor.yaml
id: 8880003 contentType: CNG description: Demo Content Template # Optional. Define the Content Template Shape in a separate file or inside the descriptor file with `contentShape` contentShapePath: # Optional. Define the Content Template Shape as below or in a separate file with `contentShapePath` contentShape: >- <article> <h1>$content.Title.text</h1> <h2>Demo content template</h2> #if ( $content.MainBody.text != "" ) $content.MainBody.text #end </article> widgets: - code: Brand-Logo config: null pos: 0 - code: Login_buttons config: null pos: 2 - code: seeds_card config: cardname: creditcard pos: 6 - code: list_item config: icon: managealerts count: '0' title: Alerts pos: 7 - code: list_item config: icon: viewstatements count: '0' title: View Statements pos: 11 - code: seedscard-transaction-table config: null pos: 13
Copied!
# Content Type
For more details on Content Type properties, refer to the Content Type documentation.
Content-type descriptor.yaml
code: CNG name: Demo status: 0 attributes: - code: title type: Text name: Title roles: - code: jacms:title descr: The main title of a Content disablingCodes: [] mandatory: true listFilter: false indexable: false enumeratorStaticItems: string enumeratorStaticItemsSeparator: string enumeratorExtractorBean: string validationRules: minLength: 0 maxLength: 100 regex: string rangeStartString: string rangeEndString: string rangeStartStringAttribute: string rangeEndStringAttribute: string equalString: string equalStringAttribute: string rangeStartDate: string rangeEndDate: string rangeStartDateAttribute: string rangeEndDateAttribute: string equalDate: string equalDateAttribute: string rangeStartNumber: 0 rangeStartNumberAttribute: string rangeEndNumber: 0 rangeEndNumberAttribute: string equalNumber: 0 equalNumberAttribute: ognlValidation: applyOnlyToFilledAttr: false errorMessage: Something keyForErrorMessage: some keyForHelpMessage: thing ognlExpression: string
Copied!
# Content
This descriptor enables content to be created and optionally published via a bundle, according to the status
property. The content ID is optional and enables linking from other components, like Content Widget. It can be autogenerated or explicitly declared.
Groups in a content descriptor are configured by the owner group mainGroup
and the join group groups
. The owner group consists of users who can manage the content within AppBuilder, while the join group consists of users who can view the content.
Content descriptor.yaml
id: NWS650 typeCode: NWS description: Dealing with a financial emergency mainGroup: free groups: - free status: PUBLIC attributes: - code: date value: '2020-04-23 00:00:00' # the date should be in ISO-8601 format - code: title values: en: Dealing with a financial emergency - code: subtitle values: en: | <p>How to tackle financial stress</p> - code: body values: en: | <p>For many Americans, financial concerns are their number-one stress point. Here are 6 ways to help reduce your money stress and get motivated to take control of your finances.</p> - code: img values: en: correlationCode: '651' name: bank_750xx684385064_d0.jpg - code: links elements: - code: links value: symbolicDestination: '#!U;http://www.yoursite.com/!#' destType: 1 urlDest: 'http://www.yoursite.com/' pageDest: null contentDest: null resourceDest: null values: en: vostro sito - code: links value: symbolicDestination: '#!U;http://www.yoursite.com/!#' destType: 1 urlDest: 'http://www.yoursite.com/' values: en: vostro sito 2 - code: attaches elements: - code: attaches values: en: correlationCode: '205' name: Entando_Admin_Console_Overview_4.3.3_EN.pdf
Copied!
# Categories
This descriptor contains a list of Categories:
Category descriptor.yaml
- code: new-category # Identifies the Category parentCode: home # The parent Category; home is the base category titles: it: "Una nuova categoria" # Category name in Italian en: "New category" # Category name in English
Copied!
# Groups
This descriptor contains a list of Groups:
Group descriptor.yaml
- code: your_group # Identifies the Group name: "Your group" # The name of the Group
Copied!
# Labels
This descriptor contains a list of Labels:
Label descriptor.yaml
- key: YOUR-FIRST-LABEL # Identifies the Label titles: # The titles on the Label it: Vostro Titolo # The title in Italian en: Your Title # The title in English
Copied!
# Languages
This descriptor contains a list of Languages to enable during the installation process:
Language descriptor.yaml
- code: en description: English - code: it description: Italian
Copied!
# Static Resources
In order to upload static files, you will need to create a folder called resources
. All files inside this folder will be uploaded into Entando with the same folder structure.
resources/ ├ css/ │ └ styles.css ├ js/ │ └ script.js ├ images/ │ ├ favicon.ico │ └ logo.png └ page.html
Copied!
Using the structure above, the resultant files in the Entando architecture will be:
your-bundle-id/ ├ css/ │ └ styles.css ├ js/ │ └ script.js ├ images/ │ ├ favicon.ico │ └ logo.png └ page.html
Copied!
Important
The
code
propertyyour-bundle-id
is insidedescriptor.yaml
.
To use static files in a Widget or Page Template, use the FTL tag <@wp.resourceURL />
:
<img src="<@wp.resourceURL />your-bundle-id/images/logo.png"> <link rel="stylesheet" href="<@wp.resourceURL />your-bundle-id/css/styles.css"> <link rel="shortcut icon" href="<@wp.resourceURL />your-bundle-id/images/favicon.ico" type="image/x-icon"/> <script type="application/javascript" src="<@wp.resourceURL />your-bundle-id/js/script.js"></script>
Copied!