![Magnolia](https://img.shields.io/static/v1?label=UI&message=Magnolia&color=brightgreen) Magnolia:connect is a Magnolia extension which allows you to embed assets from CELUM DAM directly into your Magnolia CMS pages. ## 1. Installation ### CELUM + Make sure the REST API (CORA) is installed and activated + For v2 of the module at least v2.3 of CORA is required + Create a new REST authentication profile for Magnolia in CELUM CMA + Install and configure [DirectDownload](/celum_extensions/direct_download) ### Magnolia + Add the brix external Maven Repository to your Magnolia Maven project: ``` brix.external brix external repository https://maven.brix.ch ``` + Add your credentials for the brix external Maven Repository (delivered by brix IT Solutions) to the server section of your Maven settings.xml: ``` ... brix.external your-username your-password ... ``` + Add the celum-dam-connector module as a dependency in your Magnolia Maven project: ``` ch.brix.magnolia celum-dam-connector 2.2.1-5.6 ``` + Build your Magnolia webapp with Maven and deploy it ## 2. Configuration Configure the following properties in Magnolia: #### /modules/celum-dam-connector/config/license/licenseKey > Your license key for the module (provided by brix) #### /modules/celum-dam-connector/config/apiKey > The API key of the CORA authentication profile #### /modules/celum-dam-connector/config/nodeTypeId > The Node Type ID you want to use with Magnolia:Connect #### /modules/celum-dam-connector/config/nodeLocale > The code of the locale to use for the node hierarchy #### /modules/celum-dam-connector/config/includedInformationFields > A comma separated list of IDs of the information fields which should be loaded with the asset ## 3. Usage > Note: The provided component *celum-simple-image* is only an example, it is strongly recommended to implement your own custom component. + Add a new component somewhere on your page + Choose *CELUM simple image* as component type ![magnolia:connect-add-component](addComponent.png) + Click *Select new...* + Browse the tree or use the full text search to find the desired asset, then select it and click *Choose* ![magnolia:connect-select-asset](selectAssetNew.png) + Confirm your selection by clicking on *Save* ![magnolia:connect-save-selection](saveSelectionNew.png) ### 3.1. Asset Metadata Since version 2.2.x it is possible to load and display CELUM information field values in your Magnolia components. First of all you have to configure which information fields should be loaded with the asset with the property `/modules/celum-dam-connector/config/includedInformationFields` (see [Configuration section](#2-configuration) for details). You can now call the method `getInformationFieldValue(long informationFieldId)` on the `ch.brix.magnolia.celum.integration.model.CelumAsset` instance, which should be available in your component model. This will return an instance of type `ch.brix.magnolia.celum.integration.model.informationfield.value.CelumInformationFieldValue` or `null` if the requested information field value is not available on the asset. ![magnolia:connect-CelumInformationFieldValue](CelumInformationFieldValue.png) The type of the `value` property depends on the type of the information field in CELUM: * `number` => `java.lang.Long` * `double` => `java.lang.Double` * `checkbox` => `java.lang.Boolean` * `date` => `java.util.Calendar` * `text` / `textarea` => `java.lang.String` * `localizedtext` / `localizedtextarea` => `ch.brix.magnolia.celum.integration.model.informationfield.value.LocalizedValue` ![magnolia:connect-LocalizedValue](LocalizedValue.png) * `dropdown` => `ch.brix.magnolia.celum.integration.model.informationfield.value.DropDownValue` ![magnolia:connect-DropDownValue](DropDownValue.png) * `nodereference` => `java.util.Set` ![magnolia:connect-NodeReference](NodeReference.png) Instead of working with the typed `value` property you can also use the convenience methods `getValueAsString()` and `getLocalizedValue(String localeCode)` / `getLocalizedValue(Locale locale)`. The `getValueAsString()` method will return a best-effort String representation of the value, while the `getLocalizedValue()` methods try to return the value in the specified locale – for unlocalized types (`number`, `double`, `checkbox`, `date`, `text`, `textarea`) they will return the same result as `getValueAsString()`. ## Compatibility Matrix | CELUM ContentHub | Magnolia | Magnolia Connect | :----- | :----- | :----- | 18.12+ | 5.6 | 2.2.2-5.6 | 18.12+ | 5.7 | 2.2.2-5.7 | 18.12+ | 6.1 | 2.3.0-6.1 ## Release Notes #### 1.2 - Added button to clear the asset selection #### 2.0 - Implemented full text search #### 2.1 - The module now requires a license - Added tracking (notifies CELUM when a asset is selected) #### 2.2 - Added support to load asset metadata (information field values) #### 2.3 - Established compatibility with Magnolia 6.1