| Table of Contents | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Prerequisites
All the bullet points below have to be respected if you want to use the new feature on your project
Portal & Engine version 2024.4 (or after)
New structures
portal
wkfpkgportal
wkfpkgportalaction
portaldownload
homewidgetelttype
Updates on existing structures :
Creation or updates of/on instances for :
wkfpkgportal =>
Status colour Green title creation wkfpkgportalaction =>
Status colour Green title creation homewidgetelttype =>
Status colour Green title creation vueapphomewidgettype =>
Status colour Purple title UPDATE pkgroletemplate =>
Status colour Purple title UPDATE
Plugins :
PACKAGED_Portals => activated
Portal’s configuration :
portals config domain added
named action actions and named displays added in common
features config has a new entry called portals, it should be set to true, if you want to use the creative workflow portals and it is by default activated
1/ Install on existing projects
...
| Info |
|---|
It is possible to check if objects related to the portal have the recommended structure by using the link |
1/ Install on existing projects
Steps to follow for installing portals on existing projects, after fulfilling the prerequisites.
...
To have correct permissions on portals we also recommend to update pkgroletemplate instances (steps to update below).
If you need can afford to reset your permissions from the nar, don’t forget to call the update (admin) endpoint given by PACKAGED_Security.
A touch on the users may also be needed to ensure that users, roles and roles role templates are correctly synchronized.
| Info |
|---|
For the portals to be fully functionnal, and to benefit from the “share” feature fully, the “update” endpoint will add a new instances in pkgsecugroup & pkgsecupermission, to allow users to access public portals and their assets without being logged in (direct access by link). |
If you can’t reset your permissions, you must modify them . You can do this by using wedia-config’s role template menu. For each role template, you will edit it’s “ Global permissions ” permissions.
For the “Administrator role type” the permissions should be configured this way :
Create portals => checked ✅
Administering portals => checked ✅
For the “Contributor role type” the permissions should be configured this way :
Create portals => checked ✅
Administering portals => not checked 🟩
For the “Userrole type” the permissions should be configured this way :
Create portals => not checked 🟩
Administering portals => not checked 🟩
1.2/ Front app
You will also need to upgrade your portal to retrieve all the new components and configs to benefit from the portals
1.3/ Asset Libraries
For all your library structures, which are containing assets that you want to use in portals, you will need to update them by adding a new prop called portals, the same way it’s present on asset structure (tags too).
| Info |
|---|
All asset libraries created from wedia-config will be prepared to work with the portals, and will have a portals prop |
1.4/ Front app home widgets
We’ve added the possibility to link portals to a vueapphomewidget instance, and therefore display them on the front’s home page as widgets, the same way boards are displayed.
To benefit from this feature, you have to update your vueapphomewidget structure, retrieve the new structure called homewidgetelttype and it’s instances (from the nar) and update your current vueapphomewidgettype instances. vueapphomewiget received new props and a significant number of faces (facet/ “facettes”). More details here : https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3299180556/Portals+feature+explained#Home-widgets
After updating your structure, we recommend updating any existing instances and selecting the element type "Board" when it's displayed as "None." This update won't affect the front-end rendering, but it will ensure your data remains more consistent.
...
2/ Install on projects starting on 2024.4
In this case, you will only have to respect the Prerequisites. And the feature is coming by default with the 2024.4.
Don’t forget to call the manually, to do this, you will have to check the differences (diffs) in the new role templates, which can be found in the upgrade guide linked here. => https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3181936642/Upgrading+to+2024.4#pkgroletemplate
You can modify the role templates through wedia-config, and if you do this, you will correctly update portals permissions* for Contributor role type and Administrator role type by following https://crossmedia.atlassian.net/wiki/spaces/WD/pages/edit-v2/3298787349#4.4%2F-Permissions
But for User role type, portals permissions can not be updated trough wedia-config, because it’s a setting of empty permissions, it’s better to do it manually
Even if you update the permissions through wedia-config, be sure to verify the upgrade guide. There may be additional updates to the role templates' permission values, which you'll need to retrieve for the app to function properly.
* The instance permissions value will be the same as the one deliverd with the 2024.4.0 on @portal.editorial~wkfpkgportal level
After this, call the update endpoint to retrieve the new pkgsecugroup and pkgsecupermission instances.
| Note |
|---|
If you have modified pkgsecugroup instances previously retrieved by an |
1.2/ Front app
You will also need to upgrade your portal to retrieve all the new components and configs to benefit from the portals
1.3/ Asset Libraries
For all your library structures, which are containing assets that you want to use in portals, you will need to update them by adding a new prop called portals, the same way it’s present on the asset structure (tags too).
| Info |
|---|
All asset libraries created from wedia-config will be prepared to work with the portals, and will have a portals prop with the needed tags. |
1.4/ Front app home widgets
We’ve added the possibility to link portals to a vueapphomewidget instance, and therefore display them on the front’s home page as widgets, the same way boards are displayed.
To benefit from this feature, you have to update your vueapphomewidget structure, retrieve the new structure called homewidgetelttype and its instances (from the nar), and update your current vueapphomewidgettype instances. vueapphomewiget received new props and a significant number of faces (facet/ “facettes”). More details here : https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3299180556/Portals+feature+explained#Home-widgets
After updating your structure, we recommend updating any existing instances and selecting the element type "Board" when it's displayed as "None." This update won't affect the front-end rendering, but it will ensure your data remains more consistent.
...
2/ Install on projects starting on 2024.4
In this case, you will only have to respect the Prerequisites. And the feature is coming by default with the 2024.4.
Don’t forget to call the update (admin) endpoint given by PACKAGED_Security.
...
If you are updating your app to the version 2024.4 and you don’t want to benefit from or use the new feature, here are the steps to follow :
...
4/ Configuration possibilites
4.1/ Portals list filters
4.1.1/ Portal list filters configuration
Portals list filters are configured in Below are the configuration options for the feature.
Some of these configurations are applied through updates to the delivered portal structure.
Please take a quick look at the paragraph linked below, which explains how to extend the delivered structure and which facets to use =>https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3299180556/Portals+feature+explained#Adding-metadata-to-the-portal-object
4.1/ Portals list filters
4.1.1/ Portal list filters configuration
Portals list filters are configured in this file : starter-kit\portals\explore\filters\default-cursor-config\default-resource-config.json
The configuration is set up and behaves in the same way as it does for the dam domain.
...
You can see on the cursor definition above that the query param’s value is quite large. It is actually containing all the default activated constraints. The key of this implementation is to make sure that the same constraint keys are used on filter’s definition and on cursor’s query param.
Constraint The constraint filter’s component(s) have also been updated to allow new UI (selected values on dropdown label, checkbox inline filter)
...
4.1.2/ Example of configuration
This filters filter configuration can be edited, to add or remove some filters. The configuration system follows principles that are used on the entire front app. Here you can find an example of a possible customization
...
By default, portals feature comes with filters on the portal’s detail view. These filters are allowing user allow users to filter displayed assets. The filter config used and displayed here , is the same one which that is used on the new univers universe creation.
It means that you can modify it, but the next created universe will be created by default with the updated filters config.
file File path : starter-kit\dam\explore\filters\default-cursor-config\default-resource-config.json
...
After this update, the user will only be able to see portals that share the same organization as their own.
4.4/ Permissions
As explained above (https://crossmedia.atlassian.net/wiki/spaces/WD/pages/edit-v2/3298787349#1.1%2F-Permissions) you can edit You can edit the portal’s feature permissions from wedia-config under the “Global permissions” menu.
4.5/ Public Sharing Activation/Deactivation
4.6/ Searching for a Portal through the DAM
...
A configuration option for the displayed portals is available. By configuring a cursor dedicated to the portals displayed in the DAM, you can either filter based on a specific property to meet a particular need or deliberately ensure that no portal instances are retrieved, thereby preventing the portals result section from being displayed in the DAM.
Config file : starter-kit\portals\cursors\portals-dam-explore.json
Example of config, to put on the cursor, to hide portals results on the dam
...
For each role template, you will edit its “Global permissions” permissions, here you'll find the settings that are set by default.
For the “Administrator role type” the permissions should be configured this way :
Create portals => checked ✅
Administering portals => checked ✅
For the “Contributor role type” the permissions should be configured this way :
Create portals => checked ✅
Administering portals => not checked 🟩
For the “User role type” the permissions should be configured this way :
Create portals => not checked 🟩
Administering portals => not checked 🟩
4.5/ Share privacies configuration
It is possible to configure the different types of visibilities that will be displayed inside the Share Portal modal.
...
That configuration can be specified via the configuration entry point: starter-kit/portals/share-options[].
For example, to remove the ability to set a portal as Public in the front-end, the visibility entry that has the type “public“ can be deleted from the base configuration array $.portals.shareOptions[].
This selection will control the value of the property visibility and the portal instance will be updated accordingly (See the https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3299180556/Portals+feature+explained#Visibility for more details).
4.6/ Searching for a Portal through the DAM
...
When a fulltext search is made, if the portals featureis activated and if results are found, a new section will be displayed on the top of the assets results. This section will contain portals based on the performed search
A configuration option for the displayed portals is available. By configuring a cursor dedicated to the portals displayed in the DAM, you can either filter based on a specific property to meet a particular need or deliberately ensure that no portal instances are retrieved, thereby preventing the portals' result section from being displayed in the DAM.
Configuration file: starter-kit\portals\cursors\portals-dam-explore.json
Example of config, to put on the cursor, to hide portals results on the dam
| Code Block |
|---|
"staticQuery": {
"id": {
"eq": 0
}
} |
4.7/ Portal’s section configurations
Portal’s sections are configurable through files under src\wedia-portal-apps-configs\starter-kit\portals\sections\templates[]
By default (for now) we are delivering two section types: assets & editorial.
The type assets is for the sections that can be populated with media and editorial is for sections that can only contain text. See the following functional documentation for more details about portal organization https://crossmedia.atlassian.net/wiki/spaces/WD/pages/3253272588/2.+Create+and+Organize+a+Portal#Add-sections.
For each of these section types, you will have a configuration file where you can find multiple configuration points
| Code Block | ||
|---|---|---|
| ||
{
"enabled": true, // Activate or Deactivate the section on the menu inside the portal edition
"type": "editorial", // Type of section : editorial/assets
"component": "CwLpContentTextSection", // Default component that will be used to display section content
"name": { // Configuration of the default section names in their languages
"": "Text",
"fr": "Texte",
"de": "Text"
},
"iconClasses": ["fa-text"] // Icon used in the portal edition screen next to the section type label
} |
We do not recommend to edit the type and the component.
Please note that the default component depends on multiple child components. Therefore, if you need to configure a specific component, ensure that you first review the component architecture and adhere to it.