diff --git a/vuepress/docs/next/docs/curate/bundle-component-details.md b/vuepress/docs/next/docs/curate/bundle-component-details.md index e72a06b928..3b9e12b494 100644 --- a/vuepress/docs/next/docs/curate/bundle-component-details.md +++ b/vuepress/docs/next/docs/curate/bundle-component-details.md @@ -240,7 +240,7 @@ For some more details, refer to the [Content Types Tutorial](../../tutorials/com ognlExpression: string ## Fragments -See an example of [how to use a fragment](../../tutorials/compose/widgets-fragments.md#create-a-new-fragment). +See an example of [how to use a fragment](../../tutorials/compose/widgets-fragments.md#create-and-update-a-ux-fragment). **fragments-descriptor.yaml** diff --git a/vuepress/docs/next/tutorials/compose/content-attributes.md b/vuepress/docs/next/tutorials/compose/content-attributes.md index c36f209a20..6eb5fcf797 100644 --- a/vuepress/docs/next/tutorials/compose/content-attributes.md +++ b/vuepress/docs/next/tutorials/compose/content-attributes.md @@ -1,50 +1,56 @@ +--- +sidebarDepth: 2 +--- # Content Attributes -An attribute is a well-defined property characterized by an attribute type and a set of applicable parameters. One or more attributes establish the definition of a content type comprise the information provided by content. This section describes the different attribute types supported by Entando. +On Entando, content type is defined by a collection of attributes. These attributes can be further broken down into their types, each with a list of parameters that carry the information inside the content. In other words, Attributes make it easier to categorize and find content and content types. + +This section describes the different attribute types supported by Entando. ## Attribute Types -Attribute types can be broken into two categories: simple and composed. A simple attribute type consists of a single piece of information, e.g. an image. A composed attribute type is a collection of simple attribute types, e.g. a set of images. +Attribute types can be organized into two categories: simple and composed. A simple attribute type consists of a single piece of information, e.g., an image. A composed attribute type is a collection of simple attribute types, e.g., a set of images. + ### Simple Attribute Types **Attach** - Represents a file attached to the content - Consists of the URL of the file in the system’s resources and a text entry containing the file name or description -- Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select a file from the system's Digital Assets attachment list. +- Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select a file from the system's digital assets attachment list. **Boolean** - Represents a boolean value which can be either true or false -- Rendered as a ***radio button*** with options labeled “Yes” and “No” -- Alternative to the **check box** attribute +- Rendered as a ***radio button*** with options labeled `Yes` and `No` +- Alternative to the **check box** attribute type **Check box** - Represents a boolean value which can be either true or false -- Rendered as a ***check box*** labeled “Yes” or “No” +- Rendered as a ***check box*** labeled `Yes` or `No` - Alternative to the **boolean** attribute **Date** - Represents a date - Provides time tracking capabilities -- Often used to filter content by publication date, etc. +- Often used to filter content by publication date - Rendered as a ***datepicker*** **Timestamp** - A specialized instance of the **date** attribute - The hour, minute and second can be specified -- Rendered as a ***datepicker*** for the date and a ***select*** for hours, minutes and seconds +- Rendered as ***datepicker*** for the date and ***select*** for hours, minutes and seconds **Enumerator** - Represents textual information using a predefined set of options - Defined by: - Mandatory elements declaring the set of available options - - An optional separator declaring the character to separate the enumerator arguments. The default separator is a comma. + - An optional separator declaring the character to separate the enumerator arguments. The default is a comma. - An ExtractorBean parameter naming the Spring bean that processes the enumerator. The value of ExtractorBean must exactly match the bean ID as defined in the Spring configuration file. - Rendered as a ***select list*** @@ -62,42 +68,42 @@ Attribute types can be broken into two categories: simple and composed. A simple - Retains a single value for all languages - Rendered as a ***text area*** on the page to edit content -> Notes: It is best practice to only enter meaningful HTML tags. Avoid those which are decorative or add graphics. If the CKEditor is active, additional functionalities are accessible from a dedicated editor’s toolbar (e.g.table insertion, table manipulation, special character insertion, string formatting, links creation). +> Note: It is best practice to only enter meaningful HTML tags. Avoid those which add graphics or are decorative. If the CKEditor is active, additional functionalities are accessible from a dedicated editor’s toolbar (e.g., table insertion, table manipulation, special character insertion, string formatting, & links creation). **Image** - Binds an image resource to the content - The user must specify a description to accompany the image - Images are rarely indexed or used to filter content -- Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select an image from the Digital Assets image list. -- Selecting an image presents the user with a thumbnail preview and parameters: - - Text (mandatory) that defaults to the name of the selected image +- Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select an image from the digital assets image list. +- Selecting an image presents the user with a thumbnail preview and these parameters: + - Text (required) defaults to the name of the selected image - Legend (optional) - - Alt tag (optional) + - Alt tag (optional but recommended) - Description (optional) - Title (optional) **Link** -- Represents an hypertext link +- Represents a hypertext link - Normally used to include a link within content - It is possible to define up to three different types of links: 1. External link: Points to a location external to the Entando instance - 2. Page link: Points to a page of the Entando instance + 2. Page link: Points to a page within the Entando instance 3. Content link: Points to other content within the Entando instance - Rendered as a ***button*** called `Add`. Clicking `Add` opens a modal window from which the user can select the link type. **Longtext** - Represents simple unformatted text -- Supports several languages and the optional parameters of minimum length, maximum length and regular expressions +- Supports several languages and the optional parameters of minimum and maximum length and regular expressions - Normally used for a brief description when a short string is insufficient - Rendered as a ***text area*** **Monotext** - Represents information in textual form -- Supports only one language and the optional parameters of minimum length, maximum length and regular expressions +- Supports only one language and the optional parameters of minimum and maximum length and regular expressions - Used for fields that do not require localization - Rendered as a ***text field*** @@ -105,43 +111,43 @@ Attribute types can be broken into two categories: simple and composed. A simple - Holds an integer number - Retains a single value for all languages -- Supports the optional parameters "From," "To" and "Equal to" +- Supports the optional parameters `From`, `To` and `Equal to` - Rendered as a ***text field*** **Text** - Holds a string - Retains a single value for all languages -- Supports minimum length, maximum length and regular expressions as optional parameters +- Supports minimum and maximum length and regular expressions as optional parameters - Rendered as a ***text field*** **ThreeState** -- Conceptually similar to the **boolean** attribute, with "Both" as a third status option -- Rendered as a ***radio button*** with options labeled “Yes," "No” and "Both" +- Conceptually similar to the **boolean** attribute, with `Both` as a third status option +- Rendered as a ***radio button*** with options labeled `Yes`, `No` and `Both` ### Composed Attribute Types -Simple attributes types can only retain a single type of information, whereas composed attribute types aggregate -different types of information into one attribute. +Simple attributes can only retain a single type of information, whereas composed attributes retain +many different types of information in one attribute. -It is functionally legal to build a content type where all attributes are specified back-to-back: Although formally complete, this is logically insufficient, as attributes would appear mutually unrelated and their relationships to one another would not be explicitly defined. +Though it is functionally acceptable to build composed attributes with back-to-back types, it is not recommended as the parameters would appear unrelated and their relationship to one another could not be defined. Entando offers three types of composed attributes: List, Monolist, and Composite. **List** -- Represents a set of independent and homogeneous elementary attribute types -- Each attribute type is associated with only one of the languages defined in the system, limiting the **list** attribute to mono-language attributes +- Represents a set of independent and homogeneous elementary attribute types. +- Each attribute type is associated with only one of the languages defined in the system, limiting the **list** attribute to mono-language attributes. - Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select or define the single elements which compose the list. **Monolist** -- Represents a list that is common to all of the languages defined in the system, allowing the **monolist** attribute to handle both mono-language and multi-language attributes +- Represents a list that is common to all of the languages defined in the system, allowing the **monolist** attribute to handle both mono-language and multi-language attributes. - Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select or define the single elements which compose the monolist. **Composite** -- Represents an aggregate of different, non-homogeneous, simple attributes types -- The aggregation of different types is treated as a single unit -- Rendered as a combination of the elementary attribute types, where each attribute type presents the proper rendering +- Represents an aggregate of different, non-homogeneous, simple attribute types. +- The aggregation of different types is treated as a single unit. +- Rendered as a combination of the elementary attribute types, where each attribute type presents the proper rendering. diff --git a/vuepress/docs/next/tutorials/compose/content-templates-tutorial.md b/vuepress/docs/next/tutorials/compose/content-templates-tutorial.md index bd69d74396..9c33084282 100644 --- a/vuepress/docs/next/tutorials/compose/content-templates-tutorial.md +++ b/vuepress/docs/next/tutorials/compose/content-templates-tutorial.md @@ -1,32 +1,34 @@ # Content Templates -Content Templates define how information is displayed when content is published. They provide the styling and layout for Content Types and enable different representations of the same content. +Content templates define how information is displayed when content is published. They provide the styling and layout parameters for Content Types and enable different representations of the same content. + +Note that the terms "templates" and "models" are used interchangeably. ## Create a Content Template -Content templates are managed by the Entando Web Content Management System (WCMS), through a user interface accessible from the [App Builder](../../docs/getting-started/concepts-overview.md#entando-app-builder). Follow the steps below to create and configure a content template. +Content templates are managed by the Entando Web Content Management System (WCMS) in the [App Builder](../../docs/getting-started/concepts-overview.md#entando-app-builder). Follow the steps below to create and configure a content template. -**1. From the left menu of the App Builder, go to `Content` → `Templates`** +**1.** From the left menu in the App Builder, go to `Content` → `Templates` -**2. Click the `Add` button above the list of existing templates** +**2.** Click the `Add` button above the list of existing models ![createContentTemplate](./img/content_template1.png) -**3. Define the characteristics of the content template** +**3.** Define the characteristics of the content model ![defineContentTemplate](./img/content_template2.png) -- `Type`: Choose a content type from the drop-down list. Click the `Set` button to input your selection. +- `Type`: Choose a content type from the drop-down list. Click `Set` to complete the selection. -- `Code`: Enter a sequence of up to 10 numbers to uniquely identify the content template. This field is mandatory. +- `Code`: Enter a sequence of up to 10 numbers to uniquely identify the content template. This field is required. -- `Name`: Enter a name or description for the content template. This field is mandatory and supports a string of 50 characters or less and should consist of one or more of the following: uppercase letters, lowercase letters, numbers and/or special characters. +- `Name`: Enter a name or description for the content template. This field is mandatory and supports a string of 50 characters or less and should consist of one or more of the following: uppercase and lowercase letters, numbers, and/or special characters. -- `Model`: Enter HTML to model the content template with Velocity language. This field is mandatory. +- `Model`: Enter HTML to model the content template with Velocity language. This field is required. - `Style Sheet`: (Optional) Enter the CSS to be applied to the HTML `Model`. -**4. Click the `Save` button** +**4.** Click `Save` -This adds the content template to the content type. +Now the content template/model is available to the content type. diff --git a/vuepress/docs/next/tutorials/compose/content-tutorial.md b/vuepress/docs/next/tutorials/compose/content-tutorial.md index fb513668e1..344321cfef 100644 --- a/vuepress/docs/next/tutorials/compose/content-tutorial.md +++ b/vuepress/docs/next/tutorials/compose/content-tutorial.md @@ -4,34 +4,34 @@ sidebarDepth: 2 # Create and Manage Content -This tutorial describes how to create, edit and publish content in an application from the [App Builder](../../docs/compose/app-builder.md) using the Entando Web Content Management System (WCMS). +This tutorial describes how to create, edit and publish content in an application from the [App Builder](../../docs/compose/app-builder.md). ## Create Content -1. Log into your App Builder -2. From the left sidebar, go to `Content` → `Management`. All existing content is displayed in a table. +1. Log in to your App Builder +2. From the left sidebar, go to `Content` → `Management`. Existing content is displayed in the table. ![image](./img/content-management.png) -3. Click the `Add` button on the right side of page and select the desired content type from the drop-down list. This loads a form to further define the content. See [Content Type](./content-types-tutorial.md) for how to add new types. +3. To create new content, click the `Add` button on the right and select the desired type from the drop-down list. This loads a form to add details about the content. See [Content Type tutorial](./content-types-tutorial.md) to add new types. ![image](./img/content-add.png) 4. Provide the following information: * `Info` * `Content description`: Enter the content name or description. This field is required. * `Groups` - * `Owner Group`: From the drop-down list, choose an available user group to manage the content, then click `Set group`. This field is required and can be amended in the App Builder's `Users` section under `Groups`. - * `View Only Groups`: Provide groups with viewing access to content by highlighting an available group and clicking `+` to add it. This field is required. - * `Categories`: If categories have been added, you can select a category and click `+` under `Join` to include the content in that category for searching and sorting. This field is not required. + * `Owner Group`: From the drop-down list, choose an available user group to manage the content, then click `Set group`. This field is mandatory and can be amended in the App Builder's `Users` section under `Groups`. + * `View Only Groups`: Add groups to provide viewing access by highlighting an available group and clicking `+` to add it. This field is required. + * `Categories`: If categories have been added, you can select a category and click `+` under `Join` to include it in that category for searching and sorting. This field is not required. * `Content attributes`: You are required to enter a title for the content type in the `Title` field. Populate the remaining optional fields as needed. - > Note: `History` displays the iterations of the saved content. You can view the content details or revert to a previous version. + > Note: `History` displays the iterations of the content previously saved. You can view the details or revert to a previous version. -5. Determine the status of the content to inform how it should be saved: - * `Draft`: The content is in the development stage and not ready for approval or publication. The `Save` or `Save and Continue` buttons establish `Draft` status for the content. +5. Determine the status of the content: + * `Draft`: The content is in the development stage and not ready for approval and publication. `Save` or `Save and Continue` keeps it in `Draft` mode. * `Ready`: The content is ready for review, but has not been approved or published. Content with this status can be approved later or published immediately. -6. Choose from the options to save the content: - * `Save`: Save the content as work in progress without approving it +6. Choose from these options to save the content: + * `Save`: Save the content as a work in progress without approving it * `Save and Continue`: Save the content as a draft and continue editing it * `Save and Approve`: The content is saved, approved, and ready to use in an application @@ -40,16 +40,16 @@ This tutorial describes how to create, edit and publish content in an applicatio ### Find Content -From `Content` → `Management` you can use the `Advanced Filters` feature to search for content by type, category, group or status. +From `Content` → `Management` of the left navigation menu, you can use the `Advanced Filters` to search for content by type, category, group, or status. ![Content Filters](./img/content-filters.png) -In the resultant table, a set of parameters identifies matching content. Any parameter can be deleted from view by unchecking it in the `Additions to the table of results` drop-down menu. +In the resultant table, a set of parameters identifies the matching content. The parameters can be deleted from view by unchecking it from the `Additions to the table of results` drop-down menu. ![Content Table List View](./img/content-table-view.png) ### Content Actions -For all content shown in the table, the Actions menu provides the following options: +For each content listed in the table, the `Actions` menu provides the following options: * `Copy/Paste`: Replicate the content * `Draft version`: Edit the unpublished draft version * `Published version`: Edit the published content or revert to a previous version @@ -74,7 +74,7 @@ Content Settings provide a method for managing aspects of your assets, letting t ![image](./img/content-setting.png) ### Solr Configuration -* In a multitenant application, when Solr is enabled and the `advancedSearch` environment variable is set to `true`, the Solr configuration page is accessible as the last item under `Content` in the App Builder navigation sidebar. +* In a multitenant application, when Solr is enabled and the `advancedSearch` environment variable is set to `true`, the Solr configuration page is accessible as the last item under `Content` in the App Builder left sidebar. * The Solr Configuration page allows you to monitor and update the schema of the fields required by the content types, which the search is dependent on. diff --git a/vuepress/docs/next/tutorials/compose/content-types-tutorial.md b/vuepress/docs/next/tutorials/compose/content-types-tutorial.md index 86d71b095d..35f8a8ce40 100644 --- a/vuepress/docs/next/tutorials/compose/content-types-tutorial.md +++ b/vuepress/docs/next/tutorials/compose/content-types-tutorial.md @@ -4,66 +4,65 @@ sidebarDepth: 2 # Content Types -Content is a specific instance of a content type. A content type provides a template to specify and represent content. +On Entando, content refers to a specific instance of a content type. A content type provides the template to specify and represent content. Content types are characterized by [attributes](./content-attributes.md). Each attribute is a specialized instance of an attribute type and defined by the parameters available to that attribute type. + ## Create a Content Type -Content types are managed by the Entando Web Content Management System (WCMS), through a user interface accessible from the [App Builder](../../docs/getting-started/concepts-overview.md#entando-app-builder). Follow the steps below to create and configure a content type. +Content types are managed by the Entando Web Content Management System (WCMS) in the [App Builder](../../docs/getting-started/concepts-overview.md#entando-app-builder). Follow the steps below to create and configure a content type. -**1. From the left menu of the App Builder, go to `Content` → `Types`** +**1.** From the left menu of the App Builder, go to `Content` → `Types` -**2. Click the `Add` button in the upper right corner** +**2.** Click the `Add` button in the upper right corner ![addContentType](./img/content_types1.png) -**3. Configure the content type** +**3.** Configure the content type -- When adding a content type, it is mandatory to enter `Code` and `Name` values consistent with the following: +- Enter these required fields: - `Code`: A unique identifier of the content type consisting of 3 uppercase letters - - `Name`: A string of 50 characters or less consisting of one or more of the following: uppercase letters, lowercase letters, numbers and/or special characters + - `Name`: A string of 50 characters or less consisting of uppercase and lowercase letters, numbers, and/or special characters -- To specify a meaningful content type, you must choose the appropriate attribute type from the `Type` drop-down menu +- To specify a meaningful content type, you must choose the appropriate attribute `Type` from the drop-down menu ![configureContentType](./img/content_types2.png) -**4. Click the `Add` button** - -This launches the configuration of an attribute based on the selected attribute type. +**4.** Click `Add`to configure the details of the selected attribute type -## Attribute Configuration +### Configure the Attribute -Clicking `Add` loads a form to configure the attribute. The `Type` field is pre-filled with the attribute type you selected. +When the configuration form loads, the `Type` field should be auto-filled with what was selected. -**1. Define the characteristics of the attribute** +**1.** Define the parameters of the attribute: ![configureAttributeType](./img/content_types3.png) -- `Code`: It is mandatory to enter a unique name for the attribute. This field supports a string value of 10 characters or less and should consist of one or more of the following: uppercase letters, lowercase letters, numbers and/or special characters. +- `Code`: A unique name mandatory for the attribute. This field supports a string value of 10 characters or less, and should consist of one or more of the following: uppercase & lowercase letters, numbers, and/or special characters. -- `Name`: Enter a description of the attribute. This field supports a string of 50 characters or less and should consist of one or more of the following: uppercase letters, lowercase letters, numbers and/or special characters. +- `Name`: Enter a description of the attribute. This field supports a string of 50 characters or less, and should consist of one or more of the following: uppercase & lowercase letters, numbers, and/or special characters. -- Certain attribute types support the option to declare that the attribute is `Mandatory`, `Searchable` and/or `Can be used as a filter in lists` via toggle buttons. +- Certain attribute types allow you to declare the attribute as `Mandatory`, `Searchable` and/or `Can be used as a filter in lists` via toggle buttons. -- Certain attribute types support the option to choose an attribute `Role`. Be sure to click the `Add` button after making your selection. +- Certain attribute types allow you to choose an attribute `Role`. Be sure to click the `Add` button after making your selection. > Note: Certain attribute types support the `Role` of `jacms:title - The main title of a Content` to inform plugins or services that the attribute is a title, regardless of the value entered for `Code`. A `Code` value of "title" avoids confusion if `jacms:title - The main title of a Content` is selected. -- The remaining fields are not mandatory and may be left empty. +- The remaining fields are not required and may be left empty. -**2. Click the `Continue` button** +**2.** Click `Continue` -This adds the configured attribute to the content type. Complete the additional configuration steps required by your attribute type, if applicable. +This adds the configured attribute to the content type. Complete the additional configuration steps required by your attribute type, as needed. ![modifyContentType](./img/content_types4.png) -**3. (Optional) Add other attributes to your content type, if desired** +**3.** (Optional) Add other attributes to your content type, if desired -Each attribute requires its own configuration. +Each attribute requires its own configurations. -**4. Click the `Save` button** +**4.** Click the `Save` button The content type you created is now displayed in the table. diff --git a/vuepress/docs/next/tutorials/compose/creating-protected-resources.md b/vuepress/docs/next/tutorials/compose/creating-protected-resources.md index f5ffa700ca..5feed408af 100644 --- a/vuepress/docs/next/tutorials/compose/creating-protected-resources.md +++ b/vuepress/docs/next/tutorials/compose/creating-protected-resources.md @@ -1,61 +1,63 @@ # Page and Content Protection -In the Entando Web Content Management System (WCMS) you have the ability to protect pages, content, and digital assets (images and files) by assigning groups that have the authorization to view those assets. If users without the correct authorization attempt to view those assets the platform will return an error. You can handle those errors as required for your application with dedicated error pages or by adding logic to your widgets or freemarker templates. +On Entando's Web Content Management System (WCMS), you can protect pages, content, and other digital assets by assigning groups that have the authority to view those assets. If users without the correct authorization attempt to view them, the platform will return an error. You can manage these errors for your application with dedicated error pages or by adding logic to your widgets or FreeMarker templates. + +For content with no restrictions, the default setting is `Free Access` for group ownership. ## Create a Group -Protected pages, content, and digital assets in the WCMS are protected by assigning groups to the resource that is being created. You can add new groups in the Entando App Builder as follows: +Pages, content, and digital assets (images and files) are protected with group assignments. You can add new groups in the Entando App Builder as follows: -1. Go to `Users → Groups` from the left navigation +1. Go to `Users` → `Groups` from the left navigation 1. Select `Add` 1. Enter a `Name` and a `Code` for your group` +1. Go to `Users`→`Management` in the left navigation menu to create `Users` and assign them to the new group. -The groups you create here can be utilized to protect pages, content, images, and attachments in the CMS. Groups can be assigned to individual users in the `Users` section of the app builder or as part of a customization of your entando-core-app using APIs or custom code. +An `Owner Group` is assigned when pages, content, and assets are created. The `Owner Group` indicates the team who owns the item and can make modifications. Additional groups can be given viewing access to the item via the `Join Group` field. -Pages and Content have settings for an `Owner Group` as well as a set of optional `Join Groups`. The `Owner Group` indicates the team within the `App Builder` who owns and can modify the page. Additional groups can be given access to the item via the `Join Group` setting. Note: the default App Builder configuration prevents the `Owner Group` from being changed after the item is created. +>Note: The `Owner Group` can not be changed after an item is created. ## Protect a Page -1. Select `Pages → Management` from the left navigation -1. Create a new page. Assign values as you see fit -1. To protect a page, assign the `Owner Group` to any group other than `Free Access` -1. (Optional) Add groups via `Join Group` -1. Finish configuring the page and select `Save` +1. Select `Pages` → `Management` from the left navigation. +1. Create a new page. Assign values as needed. +1. Assign an `Owner Group`. +1. (Optional) Add groups via `Join Group` to allow viewing access. +1. Complete configuring the page and select `Save`. -At this point only users assigned to either the `Owner Group` or `Join Group` will have the ability to view that page. They can also manage the Page if they have the appropriate App Builder role. +Now only users assigned to the `Owner Group` or `Join Group` will have the ability to view the page. They can manage and edit the Page if they have the appropriate role within the App Builder and are part of the `Owner Group`. -If you would like to test this, navigate to the page URL in a private or incognito browser window and you will be redirected to the `Sign in to Proceed Further` page of your application. -The `Sign in to Proceed Further` page can be changed by going to `Pages → Settings` and picking the page you would like to render to users who need to sign in. +>To test this, navigate to the new page URL from a private or incognito browser window, and you will be redirected to the default `Sign in to Proceed Further` page of your application. +The `Sign in to Proceed Further` page can be changed by going to `Pages` → `Settings` and picking the page to render for users who need to sign in. ## Protect Content -1. Select `Content → Management` from the left navigation -1. Select the `Add Content` button and pick the content type to be created -1. To protect a content item, assign the `Owner Group` to any group other than `Free Access` -1. (Optional) Add groups via `Join Group` +1. Select `Content` → `Management` +1. Click the `Add` button and choose the type to create from the drop-down list +1. Assign an `Owner Group`. +1. (Optional) Add groups via `Join Group` to allow viewing access. + 1. Finish configuring the page and select `Save` -The content you are creating will only be available to users assigned to the `Owner Group` of `Join Group`. The default WCMS widgets will only return content authorized for a given user. See the [freemarker tags](#freemarker-tags-and-consuming-protected-resources) section below for information on creating custom widgets that utilize protected content. +Only users within the `Owner Group` can view and edit the content. Users assigned to groups listed under the `Join Group` field can view it. See the [FreeMarker tags](#freemarker-tags-and-consuming-protected-resources) section below for information on creating custom widgets that utilize protected content. -::: tip Images and Attachments and Groups +::: tip Access to Images and Attachments -When creating content the `Owner Group` of the content and the `Group` assigned to the digital asset must match. For example, when creating content with an `Owner Group` of `Administrators` the content creator will be unable to select images and attachments that are assigned a different group. The exception to this is assets with a group of `Free Access`. Assets with `Free Access` can be added to protected content. +An item with the `Free Access` assignment offers viewing access to everyone. Items with `Free Access` can be added to protected pages. ::: ## Protect Images and Attachments Images and attachments uploaded to the CMS can be protected by assigning groups. -1. Select `Content → Assets` from the left navigation -2. Upload your file(s) -3. In the provided modal window select the `Group` that you would like to own the asset -4. Only users with the assigned `Group` will have the ability to view the asset you've created - - The asset will only be available to content with the same `Group` unless the attachment or image has been given a group of `Free Access` - - -## Freemarker Tags and Consuming Protected Resources +1. Select `Content` → `Assets` from the left navigation +2. Click `Add` to select and upload your file(s) +3. For the `Group` field, select the owner group to grant viewing and editing privileges +4. Only users within the assigned `Group` will have the ability to view and edit the asset you've created + - The asset is available to content such as pages with the same `Group` assignment unless it has been assigned `Free Access`. -The WCMS provides a set of freemarker tags to assist in consuming protected assets in widgets and pages. The [if-authorized](../../docs/reference/freemarker-tags/freemarker-core-tags.md#tag-ifauthorized) and [tag-nav](../../docs/reference/freemarker-tags/freemarker-core-tags.md#tag-nav) tags can help in rendering page lists and fetching assets. +## FreeMarker Tags and Consuming Protected Resources -The [content](../../docs/reference/freemarker-tags/freemarker-JACMS-tags.md#tag-content) and [content-list](../../docs/reference/freemarker-tags/freemarker-JACMS-tags.md#tag-contentlist) tags also provide the ability to fetch and render protected content and protected lists of content. +Entando supports a set of FreeMarker tags to assist in accessing and using protected assets in widgets and pages. The [if-authorized](../../docs/reference/freemarker-tags/freemarker-core-tags.md#tag-ifauthorized) and [tag-nav](../../docs/reference/freemarker-tags/freemarker-core-tags.md#tag-nav) tags can help in rendering page lists and fetching assets. +The [content](../../docs/reference/freemarker-tags/freemarker-JACMS-tags.md#tag-content) and [content-list](../../docs/reference/freemarker-tags/freemarker-JACMS-tags.md#tag-contentlist) tags also provide the ability to fetch and render protected content and lists of content. -Additionally, the [REST APIs](../../docs/consume/entando-apis.md) allow clients to fetch protected pages and assets by group via query parameters. The content REST APIs also include the ability to filter by group and access level. +Additionally, [REST APIs](../../docs/consume/entando-apis.md) allow clients to fetch protected pages and assets by group via query parameters. The content REST APIs also include the ability to filter by group and access level. diff --git a/vuepress/docs/next/tutorials/compose/digital-assets-tutorial.md b/vuepress/docs/next/tutorials/compose/digital-assets-tutorial.md index 2e07d0c200..9a2d97edb4 100644 --- a/vuepress/docs/next/tutorials/compose/digital-assets-tutorial.md +++ b/vuepress/docs/next/tutorials/compose/digital-assets-tutorial.md @@ -4,10 +4,10 @@ sidebarDepth: 2 # Digital Assets -The Entando Web Content Management System (WCMS) includes capabilities to manage content and digital assets. Digital assets are images, documents and other media files with specific formats. +The Entando Web Content Management System (WCMS) includes capabilities to manage content and digital assets. These can include images, documents and other media files in the following formats. -**Default Supported Document Formats:** `pdf`, `xls`, `doc`, `ppt`, `txt`, `rtf`, `sxw`, `sxc`, `odt`, `ods`, `odp`, `tar`, `gz`, `zip`, `rar`, `flv`, `swf`, `avi`, `wmv`, `ogg`, `mp3`, `wav`, `ogm`, `mov`, `iso`, `nrg`, `docx`, `docm`, `xlsx`, `xlsm`, `xlsb`, `pptx`, `pptm`, `ppsx`, `ppsm`, `sldx`, `sldm` -The Entando WCMS can be configured to allow or exclude any type of file extension. The MIME type of each App Builder asset should be specified. +**Default Supported Document Formats:** `pdf`, `xls`, `doc`, `ppt`, `txt`, `rtf`, `sxw`, `sxc`, `odt`, `ods`, `odp`, `tar`, `gz`, `zip`, `rar`, `flv`, `swf`, `avi`, `wmv`, `ogg`, `mp3`, `wav`, `ogm`, `mov`, `iso`, `nrg`, `docx`, `docm`, `xlsx`, `xlsm`, `xlsb`, `pptx`, `pptm`, `ppsx`, `ppsm`, `sldx`, `sldm` +The WCMS in the App Builder can be configured to allow or exclude any type of file extension. The MIME type of each asset should be specified. **Default Supported Image Formats**: `jpg`, `jpeg`, `png`, `svg`, `svg+xml` @@ -16,62 +16,64 @@ The Entando WCMS can be configured to allow or exclude any type of file extensio 1. Log in to the App Builder 2. From the left sidebar, go to `Content` → `Assets` ![Digital Asset Main Page](./img/assets-manage.png) - * View `Images` or `Attachments` using the links at the top of the page - * Search for assests by Name and/or the parameters of the `Advanced filters` function - * Assets are displayed by Name in alphabetical order. Change the order using the buttons above the list and `Choose View` to toggle between list and grid formats - * Click on the action menu (indicated by three vertical dots) of the resource to edit or delete the asset and preview available sizes + * Select `Images` or `Attachments` in the tabs at the top of the page + * Search for assests by name and/or by using the `Advanced filters` + * Assets are displayed in alphabetical order by name. Organize the results with the `Order by` buttons just above the list. Toggle between list and grid formats with the `Choose View` button. + * Click on the action menu (indicated by three vertical dots) of the item to edit or delete it. ![Digital Asset Information](./img/assets-info.png) ### Add a New Asset -1. From the left sidebar of the App Builder, go to `Content` → `Assets` -2. Click the `Add` button to add a new image or document file +1. From the left sidebar, go to `Content` → `Assets` +2. Click the `Add` button ![Add Digital Assets Window](./img/assets-add.png) -3. Define the asset parameters: - - `Group`: Choose from the drop-down menu. This is a required field and defaults to `Free Access`. Additional groups can be defined in the Users section of the App Builder. - - `Categories`: You have the option to add the asset to a category using the `+` symbol under `Join`. Categorizing an asset expands upon the criteria by which it can be searched and sorted. New categories can be created via `Content` → `Categories`. - - Add your asset by dragging it into the frame or click `browse` to select it from the file system. The file you choose should appear in the Name field, which is a required value. Multiple files can be selected simultaneously. To add files individually, use `Add Another Resource` and `Choose file` (for the first asset selection) or `Select file` (for subsequent assets). -4. (Image only) You have the option to flip, rotate or crop your image per [Edit Assets](#edit-assets) -5. Click `Add` to upload your asset(s) -6. Confirm the list of assets displays the file(s) you uploaded +3. Define the asset's parameters: + - `Group`: Choose from the drop-down menu. This is a required field and defaults to `Free Access` which does not limit access. Additional groups can be defined in the Users section of the App Builder. + - `Categories`: You have the option to add the asset to a category using the `+` button under `Join`. Categorizing an asset expands the criteria by which it can be searched and sorted. New categories can be created via `Content` → `Categories`. + - Add your asset by dragging it into the frame or click `browse` to select it from the file system. The file you choose should appear in the Name field. Use the `Add Another Resource` and `Choose file` buttons to select multiple items simultaneously. +4. (Image only) You have the option to flip, rotate or crop your image by selecting [Edit](#edit-assets) from the kebab drop-down menu of each item. +5. Click `Save` to upload your asset(s). +6. Confirm the list of images or attachments displayed in the table. ## Edit Assets -1. From the left sidebar of the App Builder, go to `Content` → `Assets` -2. Click on the action menu (indicated by three vertical dots) of the resource +1. From the left sidebar, go to `Content` → `Assets` +2. Click on the action menu (indicated by three vertical dots) next to the item 3. Select `Edit` to modify the asset: - Edit the asset name via the text field - Edit the asset's category using the `+` button under `Join` - To edit an image: 1. Click on the actions menu to the right of the image and select `Edit` ![Add Digital Assets Window](./img/assets-edit-image.png) - 2. Use the arrows to flip, rotate or recenter your image - 3. Click the `Crop` check button to resize your image. Click `Free` to remove resizing ratio restrictions. - 4. (Optional) repeat this process to create additional modified instances of the image - 5. Click `Done` - 6. Click `Add` to save all image versions - > Note: Only newly uploaded images can be flipped, rotated or cropped -4. Click the `Add` button to save your edits + 2. Use the arrows to flip, rotate, zoom or recenter your image. Use the select window to resize. Click `Free` to remove the resizing ratio restrictions. + 3. Click the check button after all changes are made. + 4. Click `Close` when all changes are done + +4. Click the `Save` button to save your edits ::: tip To organize or download assets, go to `Administration` → `File browser` and navigate to `/public/cms` ::: ## Embed an Image on a Page -An image can be embedded on a page using FreeMarker code following the format of **<@wp.resourceUrl>cms/images/YOUR-ASSET.jpg**. Go to `Administration` → `File Browser` in the App Builder to see the list of uploaded images. +An image can be embedded on a page using FreeMarker code like this: +```html +<@wp.resourceUrl>cms/images/YOUR-ASSET.jpg +``` +Go to `Administration` → `File Browser` and navigate to `/public/cms` to see the list of uploaded images. ![File Browser](./img/assets-filebrowser.png) ## Include an Asset in Content -The asset can be added to a content type that has an `Attach` or `Image` attribute. Refer to the [Content Type tutorial](./content-types-tutorial.md) for a detailed set of instructions. +The asset can be added to a content type that has an `Attach` or `Image` attribute. Refer to the [Content Type tutorial](./content-types-tutorial.md) for detailed instructions. ## Configure File Extensions for Upload -The file types that can be uploaded to an Entando Application are defined on the server side of the App Builder, e.g. in `entando-de-app` of a quickstart application. +The file types that can be uploaded to an Entando Application are defined on the server side of the App Builder, in the `entando-de-app` of a quickstart application. Two properties in `src/main/conf/systemParams.properties` specify the supported file types via comma delimitted lists: * `jacms.imageResource.allowedExtensions=` * `jacms.attachResource.allowedExtensions=` -For example, `jacms.imageResource.allowedExtensions=jpg,jpeg,png,svg,svg+xml`, where `svg+xml` is the MIME type for an SVG image. The MIME type of an asset is checked by APIs that support resources and should be defined in addition to the asset's file extensions. +For example, `jacms.imageResource.allowedExtensions=jpg,jpeg,png,svg,svg+xml`, where `svg+xml` is the MIME type for an SVG image. The MIME type of an asset is checked by APIs that support them and should be defined in addition to the asset's file extension. The `systemParams.properties` file is bundled into the WAR, so an image must be created and deployed to reflect changes to these properties. diff --git a/vuepress/docs/next/tutorials/compose/img/Publish1.png b/vuepress/docs/next/tutorials/compose/img/Publish1.png deleted file mode 100644 index c7899436e2..0000000000 Binary files a/vuepress/docs/next/tutorials/compose/img/Publish1.png and /dev/null differ diff --git a/vuepress/docs/next/tutorials/compose/img/Publish2.png b/vuepress/docs/next/tutorials/compose/img/Publish2.png deleted file mode 100644 index 74132bdda0..0000000000 Binary files a/vuepress/docs/next/tutorials/compose/img/Publish2.png and /dev/null differ diff --git a/vuepress/docs/next/tutorials/compose/img/Publish3.png b/vuepress/docs/next/tutorials/compose/img/Publish3.png deleted file mode 100644 index 810d53ade1..0000000000 Binary files a/vuepress/docs/next/tutorials/compose/img/Publish3.png and /dev/null differ diff --git a/vuepress/docs/next/tutorials/compose/img/Publish4.png b/vuepress/docs/next/tutorials/compose/img/Publish4.png deleted file mode 100644 index 837a554cb3..0000000000 Binary files a/vuepress/docs/next/tutorials/compose/img/Publish4.png and /dev/null differ diff --git a/vuepress/docs/next/tutorials/compose/img/Publish5.png b/vuepress/docs/next/tutorials/compose/img/Publish5.png deleted file mode 100644 index 5e7c893249..0000000000 Binary files a/vuepress/docs/next/tutorials/compose/img/Publish5.png and /dev/null differ diff --git a/vuepress/docs/next/tutorials/compose/img/Publish5b.png b/vuepress/docs/next/tutorials/compose/img/Publish5b.png deleted file mode 100644 index ccd90090c1..0000000000 Binary files a/vuepress/docs/next/tutorials/compose/img/Publish5b.png and /dev/null differ diff --git a/vuepress/docs/next/tutorials/compose/img/content_types1.png b/vuepress/docs/next/tutorials/compose/img/content_types1.png index 134f53aed7..e6e9cbab74 100644 Binary files a/vuepress/docs/next/tutorials/compose/img/content_types1.png and b/vuepress/docs/next/tutorials/compose/img/content_types1.png differ diff --git a/vuepress/docs/next/tutorials/compose/img/content_types5.png b/vuepress/docs/next/tutorials/compose/img/content_types5.png index 15ba225eb3..9e986d302b 100644 Binary files a/vuepress/docs/next/tutorials/compose/img/content_types5.png and b/vuepress/docs/next/tutorials/compose/img/content_types5.png differ diff --git a/vuepress/docs/next/tutorials/compose/img/publish6.png b/vuepress/docs/next/tutorials/compose/img/publish6.png deleted file mode 100644 index cc80951cb3..0000000000 Binary files a/vuepress/docs/next/tutorials/compose/img/publish6.png and /dev/null differ diff --git a/vuepress/docs/next/tutorials/compose/img/publish_page5.png b/vuepress/docs/next/tutorials/compose/img/publish_page5.png index a01ea76c4e..f5f5b0cff7 100644 Binary files a/vuepress/docs/next/tutorials/compose/img/publish_page5.png and b/vuepress/docs/next/tutorials/compose/img/publish_page5.png differ diff --git a/vuepress/docs/next/tutorials/compose/img/publish_page5b.png b/vuepress/docs/next/tutorials/compose/img/publish_page5b.png index aa482aadf0..5793cd3304 100644 Binary files a/vuepress/docs/next/tutorials/compose/img/publish_page5b.png and b/vuepress/docs/next/tutorials/compose/img/publish_page5b.png differ diff --git a/vuepress/docs/next/tutorials/compose/page-management.md b/vuepress/docs/next/tutorials/compose/page-management.md index fa7dd49093..a24b70676e 100644 --- a/vuepress/docs/next/tutorials/compose/page-management.md +++ b/vuepress/docs/next/tutorials/compose/page-management.md @@ -1,101 +1,101 @@ # Page Management -The [Entando App Builder](../../docs/compose/app-builder.md) provides the capability to publish application pages containing content as well as other Entando components. Page Templates are used to define the layout of available frames on a page. +The [Entando App Builder](../../docs/compose/app-builder.md) provides the Content Management System (CMS) to design and publish application pages. Page Templates are used to define the layout using frames on a page where content and other frontend components are placed. Details of this process are examined below. -The App Builder also offers a distributed editorial management method for your application through roles and groups. When a user is created, they are assigned a role or added to a group to grant access to the application pages they are responsible for. For details, see the [Manage Roles, Users, and Groups tutorial](./role-users-groups.md) +Additionally, the App Builder offers a distributed editorial management system through roles and groups. When a user is created, they are assigned a role and added to groups to grant access to the content and pages of an application. For details on this topic, see the [Manage Roles, Users, and Groups tutorial](./role-users-groups.md). ## Create a Page -Follow the steps below to create a Page with a Content widget. +Follow the steps below to create a page with a content widget. -**1. Go to `Pages` → `Management`.** +**1. Go to `Pages` → `Management` in the App Builder.** ![image](./img/publish_page1.png) **2. Click the `Add` button.** -This generates a form where the following fields are mandatory: +This generates a form with the following required fields: - `Title`: used for SEO -- `Code`: must be unique -- `Page placement`: the location of the Page in the Page Tree -- `Owner Group`: the Group that should have access to the Page -- `Page Template`: the structure and presentation of the Page +- `Code`: must be unique (maximum of 100 alphanumeric characters, upper- and lowercase, and the '_' and '-' characters) +- `Select page placement`: the location of the page in the page tree +- `Owner group`: the group that should have access to edit and design the page +- `Page Template`: the structure and layout of the page ![image](./img/publish_page2.png) -**3. Click the `Save and Design` button.** +**3. Click `Save and Design`.** -This loads the Designer UI, which lets you place widgets into the Page Template frames. +This launches the Page Designer where you place frontend components into the Page Template frames. Note the widgets are categorized by type, including CMS, Navigation, and User which are created by you. ![image](./img/publish_page3.png) **4. Add a widget.** -This is done by dragging a widget from the right panel into the desired frame. Adding the Content widget will load the configuration page shown below. +Drag a widget from the right panel into the desired frame. Adding the Content widget loads the configuration page shown here. ![image](./img/publish_page4.png) **5. Click `Add existing content`.** -This generates the content selection pop-up. +This opens the content selection pop-up window. ![image](./img/publish_page5.png) -You can search for the name of the content that you would like to publish. Remember that content must be saved and approved before it can be published to a page. +Search for content by name, use the Advanced filters, or browse the table to find what you need. Remember that content must be saved and approved before it can be published to a page. **6. Select the desired content item(s) from the list.** -**7. Click the `Continue` button.** +**7. Click `Choose`.** -The selected `Content` item will now be displayed. +The selected `Content` item is displayed here. ![image](./img/publish_page5b.png) -**8. Click the `Save` button.** +**8. Click `Save` at the top of the page.** The following actions are now available: -- Click on the `Preview` button to show the page preview with the updated settings. -- Click on the `Publish` button to publish the page. -- Click on the `View published page` button to view the published page in your application. +- `Preview` to show the page with the updates +- `Publish` +- `View published page` to view the page in your application. ## Page Templates -Page Templates provide the scaffolding of a Page and are constructed using two main elements: +Page Templates provide the scaffolding of a page and are constructed using two main elements: -- A `JSON configuration` field which lists the set of frames that can be used on a page. -- A `Template` field which uses Freemarker code to setup the HTML page itself. +- A `JSON configuration` field which lists the set of frames that can be used on a page +- A `Template` field which uses FreeMarker code to setup the HTML page ### JSON Configuration Each item in the `frames` array of the JSON configuration represents a frame or slot in the page, characterized by the following values: -- `pos`: A zero-based position index (starts from zero). This value is used by APIs to address a specific widget on the page. -- `descr`: The frame description displayed in the Page Design view. +- `pos`: A zero-based position index (starting from zero). This value is used by APIs to address a specific widget on the page. +- `descr`: The frame description displayed in the Page Designer view. - `mainFrame`: This designates the primary frame in the Page Template. - `defaultWidget`: The code for a default widget to use in this frame. Page Template developers can use this field to provide suggestions for common widgets, e.g. header and footer widgets. - `sketch`: An object with 4 coordinates (x1,x2,y1,y2) to allow the developer to place the widgets in the Page preview. The x and y values go from 0 to 11 (similar to columns in Bootstrap), so if you want to place a 2x2 frame at the top left corner of the page, the values would be `x1: 0`, `x2: 1`, `y1: 0` and `y2: 1`. ### Template -To add a frame in a specific place of the page, input `<@wp.show frame=0 />`, where `frame` is the `pos` variable from the `JSON configuration`. To setup the `wp` variable, `<#assign wp=JspTaglibs["/aps-core"]>` is required at the top of the template. +To add a frame in a specific position on the page, input `<@wp.show frame=0 />`, where `frame` is the `pos` variable from the `JSON configuration`. To setup the `wp` variable, `<#assign wp=JspTaglibs["/aps-core"]>` is required at the top of the template. -Common code can be shared across Pages by using [UX Fragments](./widgets-fragments.md#create-and-update-a-ux-fragment) and ```<@wp.fragment code="\" escapeXml=false /\>```. +Common code can be shared across multiple pages by using [UX Fragments](./widgets-fragments.md#create-and-update-a-ux-fragment) and ```<@wp.fragment code="\" escapeXml=false /\>```. ### Create a Page Template -Follow the steps below to prepare a Page Template with two frames on it. +Follow the steps below to prepare a Page Template with two frames. **1. Go to `Pages` → `Templates` → `Add`** ![image](./img/publish_page6.png) -**2. Enter the field information below:** +**2. Enter the field values as shown below:** -- `Code`: double_frame (Note: Dashes are not allowed) -- `Name`: Double Frame -- `JSON Configuration:` +- `Code`: double_frame (allows max of 40 uppercase or lowercase letters, numbers and special characters) +- `Name`: Double Frame (allows max of 50 uppercase or lowercase letters, numbers and special characters) +- `JSON Configuration`: ``` json { @@ -118,7 +118,7 @@ Follow the steps below to prepare a Page Template with two frames on it. } ``` -- `Template:` +- `Template`: ``` ftl <#assign wp=JspTaglibs["/aps-core"]> @@ -126,6 +126,7 @@ Follow the steps below to prepare a Page Template with two frames on it. <@wp.currentPage param="title" /> + <@wp.fragment code="keycloak_auth" escapeXml=false />

<@wp.currentPage param="title" />

@@ -134,11 +135,10 @@ Follow the steps below to prepare a Page Template with two frames on it. ``` -Include the following fragment in the `head` section to make use of the user's Keycloak identity information. -```ftl -<@wp.fragment code="keycloak_auth" escapeXml=false /> -``` +The fragment in the `head` section `<@wp.fragment code="keycloak_auth" escapeXml=false />` makes use of the user's Keycloak identity information. -**3. Verify that the `Template preview` is reflecting the desired two frame layout.** -**4. Click the `Save` button.** \ No newline at end of file +**3. Verify that the `Template preview` reflects the two frame layout.** + +**4. Click the `Save` button.** +This Template is now available to use in your application. \ No newline at end of file diff --git a/vuepress/docs/next/tutorials/compose/role-users-groups.md b/vuepress/docs/next/tutorials/compose/role-users-groups.md index 133f1a86cc..765b817082 100644 --- a/vuepress/docs/next/tutorials/compose/role-users-groups.md +++ b/vuepress/docs/next/tutorials/compose/role-users-groups.md @@ -5,44 +5,45 @@ sidebarDepth: 2 # Manage Roles, Users and Groups ## Role-based Page Management -The Entando App Builder provides a page management system with distributed editorial controls. With editing privileges based on roles and groups, a user only sees the application pages they're given access to when they log in. Users and groups are assigned different levels of control and access to manage only those pages with the proper group ownership. +Entando provides distributed editorial controls for building composable applications. With editing privileges based on roles and groups, a user only sees the application pages they're given access to when they log in. Users are assigned roles and groups based on group ownership so teams can manage portions of the application that belong to them. -This tutorial demonstrates how to grant a user editorial access to a particular page in an application. +This tutorial demonstrates how to grant editorial access to a particular page in an application. -To add controls to micro frontends and/or microservices and additional details, see the [Role Based Access Controls for Micro Frontends & Microservices](../create/ms/add-access-controls.md) tutorial. +To add controls to micro frontends and/or microservices, see the [Role Based Access Controls for Micro Frontends & Microservices](../create/ms/add-access-controls.md) tutorial. -### 1. Create Role -This role will have access to edit, delete, and create pages. Users are assigned roles and added to groups who own the pages of an application. +### 1. Create a Role +This role will have access to edit, delete, and create pages. Users are assigned roles and then added to groups who own the pages of an application. 1. Log in to your Entando App Builder. 2. Go to `Users`→ `Roles` in the left navigation menu. 3. Click `Add` to create a new role. 4. Enter a name and code. -5. Turn `ON` the following selections under `Permissions`: `Content Editing`, `Access to Administration Area` and `Operations on Pages`. Click `Save`. +5. Turn `ON` the following selections under `Permissions`: `Content Editing`, `Access to Administration Area` and `Operations on Pages`. +6. Click `Save`. ![AddPermissionsToRole](./img/add-permissions-role.png) -### 2. Create Group +### 2. Create a Group 1. Go to `Users`→ `Group` from the left navigation menu. -2. Click `Add` to create a new group that will manage a subsection of the application. +2. Click `Add` to create a new group who will manage a subsection of the application. 3. Enter a name and code. Click `Save` -### 3. Add New User -1. Go to `Users`→ `Management` in the left navigation menu. -2. Click `Add` to create a new user. -3. Enter a `Username` and `Password`. Select the default `Profile Type` and `Status`: `ON`. -Click `Save`. The user account will appear with `Status`: `Expired Password` until the first time they login and reset their password. To change this status or add an email, go to `Edit` in the `Actions` column. +### 3. Add a New User, assign role and group +1. From the left navigation menu, go to `Users`→ `Management`. +1. Click `Add` to create a new user. +1. Enter a `Username` and `Password`. Select the default `Profile Type` and `Status`: `ON`. +1. Click `Save`. The user account will appear with `Status`: `Expired Password` until the first time they log in and reset their password. To change this status or add an email, go to `Edit` from the `Actions` menu of the User account. ![AddNewUser](./img/add-user.png) -4. For the new user, select `Manage Authorization for: USERNAME` under the `Actions` column. -5. Select `Add new Authorization` and choose the `User Group` and `User Role` created above. Click `Add`. -6. Click `Save`. +1. For the new user, select `Manage Authorization for: USERNAME` under the `Actions` column. +1. Select `Add new Authorization` and choose the `User Group` and `User Role` created in the previous steps. Click `Add`. +1. Click `Save`. -### 4. Create New Page and Assign Owner Group -1. Go to `Pages`→ `Management` in the left navigation menu. +### 4. Create a New Page and Assign Owner Group +1. Go to `Pages`→ `Management` from the left navigation menu. 2. Click `Add` to create a new page. -3. Add `Title`, `Description`, `Keywords` and a `SEO-friendly Code` for the new page. Fill in the remaining fields as appropriate. -4. For `Owner group`, under the `Page groups` heading, choose the newly created group who should have editing privileges to this page. If `Free` is chosen, all users will have access to this page. +3. Add `Title`, `Code` and other fields as appropriate. See [Page Management](page-management.md) for more details. +4. Under the `Page groups` heading, choose the `Owner group` who should have editing privileges to this page. If `Free Access` is chosen, everyone can view this page and users with access to the App Builder can edit the page. 5. Click `Save`. -When the new user logs in, they will have access only to the pages for which they are part of the authorized Owner Group. +When the new user logs in, they will only have access to the pages for which they are part of the authorized Owner Group. #### Existing Page Assignment -If you need to assign editorial access to existing pages, add the user to the current Owner Group for the page in the `User Management` section. If a new group was added, go to `Pages` → `Management` from the left navigation menu, and select `Edit` under the `Actions` drop-down menu to reassign `Owner group` for each page. +If you need to assign editorial access to existing pages, add the user to the current Owner Group for the page in the `User Management` section. If a new group was added, go to `Pages` → `Management`, and select `Edit` under the `Actions` drop-down menu to reassign `Owner group` for each page. diff --git a/vuepress/docs/next/tutorials/compose/widgets-fragments.md b/vuepress/docs/next/tutorials/compose/widgets-fragments.md index c66d938ef0..1fb33e86cc 100644 --- a/vuepress/docs/next/tutorials/compose/widgets-fragments.md +++ b/vuepress/docs/next/tutorials/compose/widgets-fragments.md @@ -1,100 +1,105 @@ +--- +sidebarDepth:2 +--- # Widgets and Fragments -This tutorial covers the basics of how to create an Entando widget and place it on a page. It also reviews the -basics of fragments, which are reusable components of a user interface. +This tutorial covers the basics of how to create an Entando widget and place it on a page. It also incorporates fragments, adding it to templates to make it easy to reuse. ## Create and Publish a Widget -For this example, you will use the Entando App Builder to build and display a simple widget on a page. You would create and deploy widgets differently in a production system or larger development environment, but this gives a quick introduction to the building blocks. - -For a more advanced example, check out how to [generate microservices and micro frontends](../create/ms/generate-microservices-and-micro-frontends), which includes how to build and deploy a micro frontend as a widget in Entando. - -### Create a widget - -1. In the left pane of the App Builder, go to `Components` → `MFE & Widgets` -2. At bottom of the page, click `Add` -3. Create a widget with some sample HTML code. Enter or select the following: - - en Title: `Hello World` - - it Title: `Ciao Mondo` - - Code: `MyHelloWorld` - - Group: either `Administrators` or `Free Access` - - Icon: upload or select an icon of your choice - - Custom UI: `

Hello World

` - > Note: the Custom UI Field is a FreeMarker template where you can enter raw HTML and include FreeMarker logic. This allows you to import JavaScript, CSS or basic HTML. -4. Click `Save` - -### Place the widget on a page +For this example, you will use the App Builder to build and display a simple widget on a page. This is a quick introduction to one of the building blocks that make up composable applications. + +For a more advanced example, check out how to [generate microservices and micro frontends (MFEs)](../create/ms/generate-microservices-and-micro-frontends), which includes how to build and deploy a micro frontend as a widget in Entando. + +### 1. Create a widget + + 1. From the left navigation menu of the App Builder, go to `Components` → `MFE & Widgets` + 2. To create a new widget, click `Add` + 3. Enter the following values: + - en Title: `Hello World` + - it Title: `Ciao Mondo` + - Code: `MyHelloWorld` + - Group: either `Administrators` or `Free Access` + - Icon: upload or select an icon of your choice + - Custom UI: `

Hello World

` + > Note: the Custom UI Field is a FreeMarker template where you can enter raw HTML and include FreeMarker logic. This allows you to import JavaScript, CSS or basic HTML. + 4. Click `Save` + +### 2. Place the widget on a page -1. From the left pane of the App Builder, go to `Pages` → `Settings` -2. Select a page, e.g. "Home / Service" from the “Home Page” dropdown menu -3. Click `Save` -4. From the left pane of the App Builder, go to `Pages` → `Management` -5. On the row with the folder named for your page (e.g. "Service"), click on the Actions icon and select "Design" -6. From the Widgets tab in the right pane, drag and drop your new widget into an open frame on the page -7. At the top of the middle pane, click `Preview` -8. Confirm that your page displays "Hello World" +1. Go to `Pages` → `Management` from the left navigation menu. +1. Create a [new page](page-management.md#create-a-page) or select an existing page to add the widget to. +1. Click the corresponding Actions icon and choose `Design` from the drop-down. +1. From the Widgets tab in the right pane, under the User list of widgets, drag and drop your new widget into an open frame on the page. +1. Click the `Preview` button at the top to display your page. +1. Confirm that your page displays "Hello World". -### Publish the updated page - -1. Navigate back to "Design" for your page -2. At the bottom of the middle pane, click `Publish`. Note that the Status icon for your page, represented by a colored dot, has changed from yellow to green. +### 3. Publish the updated page +1. Navigate back to the Page Designer +2. Below your application page, click `Publish`. Note that the Status icon for your page, the circle next to the page title, has changed from yellow to green to show its completed status. ## Create and Update a UX Fragment A UX fragment is a way to reuse snippets of frontend code across multiple pages or widgets. Common elements such as basic HTML, JavaScript or FreeMarker logic can be stored as fragments and referenced via the `<@wp.fragment …` tag. -To create and update a basic UX fragment per the steps below, first [create and publish a widget](#create-and-publish-a-widget) as the basis for this exercise. +The [create and publish a widget](#create-and-publish-a-widget) in the previous steps is a prerequisite for the next part of the tutorial. -### Create a new fragment +### 1. Create a new fragment -1. In the left pane of the App Builder, go to `Components` → `UX Fragments` -2. At bottom of the page, click `Add` -3. Enter the following field information: +1. Go to `Components` → `UX Fragments` +2. At the bottom of the page, click `Add` +3. Enter the following field values: - Code: `test` - Gui Code: `

Hello World

` 4. Click `Save` -### Identify the widget's page template +### 2. Identify the widget's page template -1. From the left pane of the App Builder, go to `Pages` → `Management` -2. On the row with the folder named for your page (e.g. "Service"), click on the Actions icon and select "Details" -3. Click on the `Info` button to expand the page information -4. Note the Page Template used for your page, e.g. "single_frame_page" -### Place the fragment in the template +1. Now go to `Pages` → `Management` +2. From the Actions drop-down menu for your desired page, select `Details` +3. Click the `Info` button to expand the page details +4. Note the Page Template used for your page, e.g., "single_frame_page" -1. From the left pane of the App Builder, go to `Pages` → `Templates` -2. On the row with the page template used for your page (e.g. "single_frame_page"), click on the Actions icon and select "Edit" -3. In the `Template` text box, add `<@wp.fragment code="test"/>` on a new line between the `` and `` tags +### 3. Place the fragment in the template + +1. Go to `Pages` → `Templates` from the left nav +2. In the Actions drop-down menu for the noted Template, select `Edit` +3. In the `Template` text box, add the following line within the `` tags: +``` html +<@wp.fragment code="test"/> +``` 4. At the bottom of the page, click `Save` -### View the page with the new fragment +### 4. View the page with the new fragment -1. From the left pane of the App Builder, go to `Pages` → `Management` -2. On the row with the folder named for your page (e.g. "Service"), click on the Actions icon and select "Design" -3. At the top of the middle pane, click `Preview` -> Note: The page will display the fragment `

This is a fragment.

`, which includes the HTML tags. By default, HTML embedded via a fragment tag is escaped, so it renders exactly as you enter it. You’ll need to un-escape the fragment to render it correctly. +1. Now go to `Pages` → `Management` +2. From the Actions drop-down menu for your page, select `Preview` + +> Note: The page will display the fragment `

This is a fragment.

` with the HTML tags. By default, HTML tags embedded within a fragment are ignored, or 'escaped', so it renders like a string, exactly as it appears. You need to reverse this when you call the fragment to render it properly. -### Update the fragment +### 5. Update the fragment -1. From the left pane of the App Builder, go to `Pages` → `Templates` -2. On the row with the page template used for your page (e.g. "single_frame_page"), click on the Actions icon and select "Edit" -3. Change the tag to `<@wp.fragment code="test" escapeXml=false/>` +1. Back in the App Builder, go to `Pages` → `Templates` +2. From the Actions drop-down menu for the Template, select `Edit` +3. Replace the inserted tag in Step 3 with this to render the html properly: + ```html + <@wp.fragment code="test" escapeXml=false/> + ``` -### View the page with the updated fragment +### 6. View the page with the updated fragment -1. From the left pane of the App Builder, go to `Pages` → `Management` -2. On the row with the folder named for your page (e.g. "Service"), click on the Actions icon and select "Design" -3. At the top of the middle pane, click `Preview` -4. Confirm the fragment is rendered correctly +1. Return to `Pages` → `Management` +2. Click on the Actions icon and select `Preview` for your test page +3. Confirm the fragment is rendered correctly ## FreeMarker Basics in Entando FreeMarker is a powerful templating language that provides flexibility in how pages are rendered. It allows you to include conditional logic, inject information from the backend, check for query parameters and route to different pages. For example: -- To check for a query parameter, use: +- To check for a query parameter: `<#if RequestParameters.myParam?exists > …` -- To check the current username, use: +- To check the current username: `<#if (Session.currentUser.username != "guest") >` Consider using [FreeMarker](https://freemarker.apache.org) for widgets that need to support dynamic behavior. diff --git a/vuepress/docs/v7.3/docs/curate/bundle-component-details.md b/vuepress/docs/v7.3/docs/curate/bundle-component-details.md index e72a06b928..3b9e12b494 100644 --- a/vuepress/docs/v7.3/docs/curate/bundle-component-details.md +++ b/vuepress/docs/v7.3/docs/curate/bundle-component-details.md @@ -240,7 +240,7 @@ For some more details, refer to the [Content Types Tutorial](../../tutorials/com ognlExpression: string ## Fragments -See an example of [how to use a fragment](../../tutorials/compose/widgets-fragments.md#create-a-new-fragment). +See an example of [how to use a fragment](../../tutorials/compose/widgets-fragments.md#create-and-update-a-ux-fragment). **fragments-descriptor.yaml** diff --git a/vuepress/docs/v7.3/tutorials/compose/content-attributes.md b/vuepress/docs/v7.3/tutorials/compose/content-attributes.md index c36f209a20..6eb5fcf797 100644 --- a/vuepress/docs/v7.3/tutorials/compose/content-attributes.md +++ b/vuepress/docs/v7.3/tutorials/compose/content-attributes.md @@ -1,50 +1,56 @@ +--- +sidebarDepth: 2 +--- # Content Attributes -An attribute is a well-defined property characterized by an attribute type and a set of applicable parameters. One or more attributes establish the definition of a content type comprise the information provided by content. This section describes the different attribute types supported by Entando. +On Entando, content type is defined by a collection of attributes. These attributes can be further broken down into their types, each with a list of parameters that carry the information inside the content. In other words, Attributes make it easier to categorize and find content and content types. + +This section describes the different attribute types supported by Entando. ## Attribute Types -Attribute types can be broken into two categories: simple and composed. A simple attribute type consists of a single piece of information, e.g. an image. A composed attribute type is a collection of simple attribute types, e.g. a set of images. +Attribute types can be organized into two categories: simple and composed. A simple attribute type consists of a single piece of information, e.g., an image. A composed attribute type is a collection of simple attribute types, e.g., a set of images. + ### Simple Attribute Types **Attach** - Represents a file attached to the content - Consists of the URL of the file in the system’s resources and a text entry containing the file name or description -- Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select a file from the system's Digital Assets attachment list. +- Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select a file from the system's digital assets attachment list. **Boolean** - Represents a boolean value which can be either true or false -- Rendered as a ***radio button*** with options labeled “Yes” and “No” -- Alternative to the **check box** attribute +- Rendered as a ***radio button*** with options labeled `Yes` and `No` +- Alternative to the **check box** attribute type **Check box** - Represents a boolean value which can be either true or false -- Rendered as a ***check box*** labeled “Yes” or “No” +- Rendered as a ***check box*** labeled `Yes` or `No` - Alternative to the **boolean** attribute **Date** - Represents a date - Provides time tracking capabilities -- Often used to filter content by publication date, etc. +- Often used to filter content by publication date - Rendered as a ***datepicker*** **Timestamp** - A specialized instance of the **date** attribute - The hour, minute and second can be specified -- Rendered as a ***datepicker*** for the date and a ***select*** for hours, minutes and seconds +- Rendered as ***datepicker*** for the date and ***select*** for hours, minutes and seconds **Enumerator** - Represents textual information using a predefined set of options - Defined by: - Mandatory elements declaring the set of available options - - An optional separator declaring the character to separate the enumerator arguments. The default separator is a comma. + - An optional separator declaring the character to separate the enumerator arguments. The default is a comma. - An ExtractorBean parameter naming the Spring bean that processes the enumerator. The value of ExtractorBean must exactly match the bean ID as defined in the Spring configuration file. - Rendered as a ***select list*** @@ -62,42 +68,42 @@ Attribute types can be broken into two categories: simple and composed. A simple - Retains a single value for all languages - Rendered as a ***text area*** on the page to edit content -> Notes: It is best practice to only enter meaningful HTML tags. Avoid those which are decorative or add graphics. If the CKEditor is active, additional functionalities are accessible from a dedicated editor’s toolbar (e.g.table insertion, table manipulation, special character insertion, string formatting, links creation). +> Note: It is best practice to only enter meaningful HTML tags. Avoid those which add graphics or are decorative. If the CKEditor is active, additional functionalities are accessible from a dedicated editor’s toolbar (e.g., table insertion, table manipulation, special character insertion, string formatting, & links creation). **Image** - Binds an image resource to the content - The user must specify a description to accompany the image - Images are rarely indexed or used to filter content -- Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select an image from the Digital Assets image list. -- Selecting an image presents the user with a thumbnail preview and parameters: - - Text (mandatory) that defaults to the name of the selected image +- Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select an image from the digital assets image list. +- Selecting an image presents the user with a thumbnail preview and these parameters: + - Text (required) defaults to the name of the selected image - Legend (optional) - - Alt tag (optional) + - Alt tag (optional but recommended) - Description (optional) - Title (optional) **Link** -- Represents an hypertext link +- Represents a hypertext link - Normally used to include a link within content - It is possible to define up to three different types of links: 1. External link: Points to a location external to the Entando instance - 2. Page link: Points to a page of the Entando instance + 2. Page link: Points to a page within the Entando instance 3. Content link: Points to other content within the Entando instance - Rendered as a ***button*** called `Add`. Clicking `Add` opens a modal window from which the user can select the link type. **Longtext** - Represents simple unformatted text -- Supports several languages and the optional parameters of minimum length, maximum length and regular expressions +- Supports several languages and the optional parameters of minimum and maximum length and regular expressions - Normally used for a brief description when a short string is insufficient - Rendered as a ***text area*** **Monotext** - Represents information in textual form -- Supports only one language and the optional parameters of minimum length, maximum length and regular expressions +- Supports only one language and the optional parameters of minimum and maximum length and regular expressions - Used for fields that do not require localization - Rendered as a ***text field*** @@ -105,43 +111,43 @@ Attribute types can be broken into two categories: simple and composed. A simple - Holds an integer number - Retains a single value for all languages -- Supports the optional parameters "From," "To" and "Equal to" +- Supports the optional parameters `From`, `To` and `Equal to` - Rendered as a ***text field*** **Text** - Holds a string - Retains a single value for all languages -- Supports minimum length, maximum length and regular expressions as optional parameters +- Supports minimum and maximum length and regular expressions as optional parameters - Rendered as a ***text field*** **ThreeState** -- Conceptually similar to the **boolean** attribute, with "Both" as a third status option -- Rendered as a ***radio button*** with options labeled “Yes," "No” and "Both" +- Conceptually similar to the **boolean** attribute, with `Both` as a third status option +- Rendered as a ***radio button*** with options labeled `Yes`, `No` and `Both` ### Composed Attribute Types -Simple attributes types can only retain a single type of information, whereas composed attribute types aggregate -different types of information into one attribute. +Simple attributes can only retain a single type of information, whereas composed attributes retain +many different types of information in one attribute. -It is functionally legal to build a content type where all attributes are specified back-to-back: Although formally complete, this is logically insufficient, as attributes would appear mutually unrelated and their relationships to one another would not be explicitly defined. +Though it is functionally acceptable to build composed attributes with back-to-back types, it is not recommended as the parameters would appear unrelated and their relationship to one another could not be defined. Entando offers three types of composed attributes: List, Monolist, and Composite. **List** -- Represents a set of independent and homogeneous elementary attribute types -- Each attribute type is associated with only one of the languages defined in the system, limiting the **list** attribute to mono-language attributes +- Represents a set of independent and homogeneous elementary attribute types. +- Each attribute type is associated with only one of the languages defined in the system, limiting the **list** attribute to mono-language attributes. - Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select or define the single elements which compose the list. **Monolist** -- Represents a list that is common to all of the languages defined in the system, allowing the **monolist** attribute to handle both mono-language and multi-language attributes +- Represents a list that is common to all of the languages defined in the system, allowing the **monolist** attribute to handle both mono-language and multi-language attributes. - Rendered as a ***button*** called `Add`. Clicking `Add` prompts the user to select or define the single elements which compose the monolist. **Composite** -- Represents an aggregate of different, non-homogeneous, simple attributes types -- The aggregation of different types is treated as a single unit -- Rendered as a combination of the elementary attribute types, where each attribute type presents the proper rendering +- Represents an aggregate of different, non-homogeneous, simple attribute types. +- The aggregation of different types is treated as a single unit. +- Rendered as a combination of the elementary attribute types, where each attribute type presents the proper rendering. diff --git a/vuepress/docs/v7.3/tutorials/compose/content-templates-tutorial.md b/vuepress/docs/v7.3/tutorials/compose/content-templates-tutorial.md index bd69d74396..9c33084282 100644 --- a/vuepress/docs/v7.3/tutorials/compose/content-templates-tutorial.md +++ b/vuepress/docs/v7.3/tutorials/compose/content-templates-tutorial.md @@ -1,32 +1,34 @@ # Content Templates -Content Templates define how information is displayed when content is published. They provide the styling and layout for Content Types and enable different representations of the same content. +Content templates define how information is displayed when content is published. They provide the styling and layout parameters for Content Types and enable different representations of the same content. + +Note that the terms "templates" and "models" are used interchangeably. ## Create a Content Template -Content templates are managed by the Entando Web Content Management System (WCMS), through a user interface accessible from the [App Builder](../../docs/getting-started/concepts-overview.md#entando-app-builder). Follow the steps below to create and configure a content template. +Content templates are managed by the Entando Web Content Management System (WCMS) in the [App Builder](../../docs/getting-started/concepts-overview.md#entando-app-builder). Follow the steps below to create and configure a content template. -**1. From the left menu of the App Builder, go to `Content` → `Templates`** +**1.** From the left menu in the App Builder, go to `Content` → `Templates` -**2. Click the `Add` button above the list of existing templates** +**2.** Click the `Add` button above the list of existing models ![createContentTemplate](./img/content_template1.png) -**3. Define the characteristics of the content template** +**3.** Define the characteristics of the content model ![defineContentTemplate](./img/content_template2.png) -- `Type`: Choose a content type from the drop-down list. Click the `Set` button to input your selection. +- `Type`: Choose a content type from the drop-down list. Click `Set` to complete the selection. -- `Code`: Enter a sequence of up to 10 numbers to uniquely identify the content template. This field is mandatory. +- `Code`: Enter a sequence of up to 10 numbers to uniquely identify the content template. This field is required. -- `Name`: Enter a name or description for the content template. This field is mandatory and supports a string of 50 characters or less and should consist of one or more of the following: uppercase letters, lowercase letters, numbers and/or special characters. +- `Name`: Enter a name or description for the content template. This field is mandatory and supports a string of 50 characters or less and should consist of one or more of the following: uppercase and lowercase letters, numbers, and/or special characters. -- `Model`: Enter HTML to model the content template with Velocity language. This field is mandatory. +- `Model`: Enter HTML to model the content template with Velocity language. This field is required. - `Style Sheet`: (Optional) Enter the CSS to be applied to the HTML `Model`. -**4. Click the `Save` button** +**4.** Click `Save` -This adds the content template to the content type. +Now the content template/model is available to the content type. diff --git a/vuepress/docs/v7.3/tutorials/compose/content-tutorial.md b/vuepress/docs/v7.3/tutorials/compose/content-tutorial.md index fb513668e1..344321cfef 100644 --- a/vuepress/docs/v7.3/tutorials/compose/content-tutorial.md +++ b/vuepress/docs/v7.3/tutorials/compose/content-tutorial.md @@ -4,34 +4,34 @@ sidebarDepth: 2 # Create and Manage Content -This tutorial describes how to create, edit and publish content in an application from the [App Builder](../../docs/compose/app-builder.md) using the Entando Web Content Management System (WCMS). +This tutorial describes how to create, edit and publish content in an application from the [App Builder](../../docs/compose/app-builder.md). ## Create Content -1. Log into your App Builder -2. From the left sidebar, go to `Content` → `Management`. All existing content is displayed in a table. +1. Log in to your App Builder +2. From the left sidebar, go to `Content` → `Management`. Existing content is displayed in the table. ![image](./img/content-management.png) -3. Click the `Add` button on the right side of page and select the desired content type from the drop-down list. This loads a form to further define the content. See [Content Type](./content-types-tutorial.md) for how to add new types. +3. To create new content, click the `Add` button on the right and select the desired type from the drop-down list. This loads a form to add details about the content. See [Content Type tutorial](./content-types-tutorial.md) to add new types. ![image](./img/content-add.png) 4. Provide the following information: * `Info` * `Content description`: Enter the content name or description. This field is required. * `Groups` - * `Owner Group`: From the drop-down list, choose an available user group to manage the content, then click `Set group`. This field is required and can be amended in the App Builder's `Users` section under `Groups`. - * `View Only Groups`: Provide groups with viewing access to content by highlighting an available group and clicking `+` to add it. This field is required. - * `Categories`: If categories have been added, you can select a category and click `+` under `Join` to include the content in that category for searching and sorting. This field is not required. + * `Owner Group`: From the drop-down list, choose an available user group to manage the content, then click `Set group`. This field is mandatory and can be amended in the App Builder's `Users` section under `Groups`. + * `View Only Groups`: Add groups to provide viewing access by highlighting an available group and clicking `+` to add it. This field is required. + * `Categories`: If categories have been added, you can select a category and click `+` under `Join` to include it in that category for searching and sorting. This field is not required. * `Content attributes`: You are required to enter a title for the content type in the `Title` field. Populate the remaining optional fields as needed. - > Note: `History` displays the iterations of the saved content. You can view the content details or revert to a previous version. + > Note: `History` displays the iterations of the content previously saved. You can view the details or revert to a previous version. -5. Determine the status of the content to inform how it should be saved: - * `Draft`: The content is in the development stage and not ready for approval or publication. The `Save` or `Save and Continue` buttons establish `Draft` status for the content. +5. Determine the status of the content: + * `Draft`: The content is in the development stage and not ready for approval and publication. `Save` or `Save and Continue` keeps it in `Draft` mode. * `Ready`: The content is ready for review, but has not been approved or published. Content with this status can be approved later or published immediately. -6. Choose from the options to save the content: - * `Save`: Save the content as work in progress without approving it +6. Choose from these options to save the content: + * `Save`: Save the content as a work in progress without approving it * `Save and Continue`: Save the content as a draft and continue editing it * `Save and Approve`: The content is saved, approved, and ready to use in an application @@ -40,16 +40,16 @@ This tutorial describes how to create, edit and publish content in an applicatio ### Find Content -From `Content` → `Management` you can use the `Advanced Filters` feature to search for content by type, category, group or status. +From `Content` → `Management` of the left navigation menu, you can use the `Advanced Filters` to search for content by type, category, group, or status. ![Content Filters](./img/content-filters.png) -In the resultant table, a set of parameters identifies matching content. Any parameter can be deleted from view by unchecking it in the `Additions to the table of results` drop-down menu. +In the resultant table, a set of parameters identifies the matching content. The parameters can be deleted from view by unchecking it from the `Additions to the table of results` drop-down menu. ![Content Table List View](./img/content-table-view.png) ### Content Actions -For all content shown in the table, the Actions menu provides the following options: +For each content listed in the table, the `Actions` menu provides the following options: * `Copy/Paste`: Replicate the content * `Draft version`: Edit the unpublished draft version * `Published version`: Edit the published content or revert to a previous version @@ -74,7 +74,7 @@ Content Settings provide a method for managing aspects of your assets, letting t ![image](./img/content-setting.png) ### Solr Configuration -* In a multitenant application, when Solr is enabled and the `advancedSearch` environment variable is set to `true`, the Solr configuration page is accessible as the last item under `Content` in the App Builder navigation sidebar. +* In a multitenant application, when Solr is enabled and the `advancedSearch` environment variable is set to `true`, the Solr configuration page is accessible as the last item under `Content` in the App Builder left sidebar. * The Solr Configuration page allows you to monitor and update the schema of the fields required by the content types, which the search is dependent on. diff --git a/vuepress/docs/v7.3/tutorials/compose/content-types-tutorial.md b/vuepress/docs/v7.3/tutorials/compose/content-types-tutorial.md index 86d71b095d..35f8a8ce40 100644 --- a/vuepress/docs/v7.3/tutorials/compose/content-types-tutorial.md +++ b/vuepress/docs/v7.3/tutorials/compose/content-types-tutorial.md @@ -4,66 +4,65 @@ sidebarDepth: 2 # Content Types -Content is a specific instance of a content type. A content type provides a template to specify and represent content. +On Entando, content refers to a specific instance of a content type. A content type provides the template to specify and represent content. Content types are characterized by [attributes](./content-attributes.md). Each attribute is a specialized instance of an attribute type and defined by the parameters available to that attribute type. + ## Create a Content Type -Content types are managed by the Entando Web Content Management System (WCMS), through a user interface accessible from the [App Builder](../../docs/getting-started/concepts-overview.md#entando-app-builder). Follow the steps below to create and configure a content type. +Content types are managed by the Entando Web Content Management System (WCMS) in the [App Builder](../../docs/getting-started/concepts-overview.md#entando-app-builder). Follow the steps below to create and configure a content type. -**1. From the left menu of the App Builder, go to `Content` → `Types`** +**1.** From the left menu of the App Builder, go to `Content` → `Types` -**2. Click the `Add` button in the upper right corner** +**2.** Click the `Add` button in the upper right corner ![addContentType](./img/content_types1.png) -**3. Configure the content type** +**3.** Configure the content type -- When adding a content type, it is mandatory to enter `Code` and `Name` values consistent with the following: +- Enter these required fields: - `Code`: A unique identifier of the content type consisting of 3 uppercase letters - - `Name`: A string of 50 characters or less consisting of one or more of the following: uppercase letters, lowercase letters, numbers and/or special characters + - `Name`: A string of 50 characters or less consisting of uppercase and lowercase letters, numbers, and/or special characters -- To specify a meaningful content type, you must choose the appropriate attribute type from the `Type` drop-down menu +- To specify a meaningful content type, you must choose the appropriate attribute `Type` from the drop-down menu ![configureContentType](./img/content_types2.png) -**4. Click the `Add` button** - -This launches the configuration of an attribute based on the selected attribute type. +**4.** Click `Add`to configure the details of the selected attribute type -## Attribute Configuration +### Configure the Attribute -Clicking `Add` loads a form to configure the attribute. The `Type` field is pre-filled with the attribute type you selected. +When the configuration form loads, the `Type` field should be auto-filled with what was selected. -**1. Define the characteristics of the attribute** +**1.** Define the parameters of the attribute: ![configureAttributeType](./img/content_types3.png) -- `Code`: It is mandatory to enter a unique name for the attribute. This field supports a string value of 10 characters or less and should consist of one or more of the following: uppercase letters, lowercase letters, numbers and/or special characters. +- `Code`: A unique name mandatory for the attribute. This field supports a string value of 10 characters or less, and should consist of one or more of the following: uppercase & lowercase letters, numbers, and/or special characters. -- `Name`: Enter a description of the attribute. This field supports a string of 50 characters or less and should consist of one or more of the following: uppercase letters, lowercase letters, numbers and/or special characters. +- `Name`: Enter a description of the attribute. This field supports a string of 50 characters or less, and should consist of one or more of the following: uppercase & lowercase letters, numbers, and/or special characters. -- Certain attribute types support the option to declare that the attribute is `Mandatory`, `Searchable` and/or `Can be used as a filter in lists` via toggle buttons. +- Certain attribute types allow you to declare the attribute as `Mandatory`, `Searchable` and/or `Can be used as a filter in lists` via toggle buttons. -- Certain attribute types support the option to choose an attribute `Role`. Be sure to click the `Add` button after making your selection. +- Certain attribute types allow you to choose an attribute `Role`. Be sure to click the `Add` button after making your selection. > Note: Certain attribute types support the `Role` of `jacms:title - The main title of a Content` to inform plugins or services that the attribute is a title, regardless of the value entered for `Code`. A `Code` value of "title" avoids confusion if `jacms:title - The main title of a Content` is selected. -- The remaining fields are not mandatory and may be left empty. +- The remaining fields are not required and may be left empty. -**2. Click the `Continue` button** +**2.** Click `Continue` -This adds the configured attribute to the content type. Complete the additional configuration steps required by your attribute type, if applicable. +This adds the configured attribute to the content type. Complete the additional configuration steps required by your attribute type, as needed. ![modifyContentType](./img/content_types4.png) -**3. (Optional) Add other attributes to your content type, if desired** +**3.** (Optional) Add other attributes to your content type, if desired -Each attribute requires its own configuration. +Each attribute requires its own configurations. -**4. Click the `Save` button** +**4.** Click the `Save` button The content type you created is now displayed in the table. diff --git a/vuepress/docs/v7.3/tutorials/compose/creating-protected-resources.md b/vuepress/docs/v7.3/tutorials/compose/creating-protected-resources.md index f5ffa700ca..5feed408af 100644 --- a/vuepress/docs/v7.3/tutorials/compose/creating-protected-resources.md +++ b/vuepress/docs/v7.3/tutorials/compose/creating-protected-resources.md @@ -1,61 +1,63 @@ # Page and Content Protection -In the Entando Web Content Management System (WCMS) you have the ability to protect pages, content, and digital assets (images and files) by assigning groups that have the authorization to view those assets. If users without the correct authorization attempt to view those assets the platform will return an error. You can handle those errors as required for your application with dedicated error pages or by adding logic to your widgets or freemarker templates. +On Entando's Web Content Management System (WCMS), you can protect pages, content, and other digital assets by assigning groups that have the authority to view those assets. If users without the correct authorization attempt to view them, the platform will return an error. You can manage these errors for your application with dedicated error pages or by adding logic to your widgets or FreeMarker templates. + +For content with no restrictions, the default setting is `Free Access` for group ownership. ## Create a Group -Protected pages, content, and digital assets in the WCMS are protected by assigning groups to the resource that is being created. You can add new groups in the Entando App Builder as follows: +Pages, content, and digital assets (images and files) are protected with group assignments. You can add new groups in the Entando App Builder as follows: -1. Go to `Users → Groups` from the left navigation +1. Go to `Users` → `Groups` from the left navigation 1. Select `Add` 1. Enter a `Name` and a `Code` for your group` +1. Go to `Users`→`Management` in the left navigation menu to create `Users` and assign them to the new group. -The groups you create here can be utilized to protect pages, content, images, and attachments in the CMS. Groups can be assigned to individual users in the `Users` section of the app builder or as part of a customization of your entando-core-app using APIs or custom code. +An `Owner Group` is assigned when pages, content, and assets are created. The `Owner Group` indicates the team who owns the item and can make modifications. Additional groups can be given viewing access to the item via the `Join Group` field. -Pages and Content have settings for an `Owner Group` as well as a set of optional `Join Groups`. The `Owner Group` indicates the team within the `App Builder` who owns and can modify the page. Additional groups can be given access to the item via the `Join Group` setting. Note: the default App Builder configuration prevents the `Owner Group` from being changed after the item is created. +>Note: The `Owner Group` can not be changed after an item is created. ## Protect a Page -1. Select `Pages → Management` from the left navigation -1. Create a new page. Assign values as you see fit -1. To protect a page, assign the `Owner Group` to any group other than `Free Access` -1. (Optional) Add groups via `Join Group` -1. Finish configuring the page and select `Save` +1. Select `Pages` → `Management` from the left navigation. +1. Create a new page. Assign values as needed. +1. Assign an `Owner Group`. +1. (Optional) Add groups via `Join Group` to allow viewing access. +1. Complete configuring the page and select `Save`. -At this point only users assigned to either the `Owner Group` or `Join Group` will have the ability to view that page. They can also manage the Page if they have the appropriate App Builder role. +Now only users assigned to the `Owner Group` or `Join Group` will have the ability to view the page. They can manage and edit the Page if they have the appropriate role within the App Builder and are part of the `Owner Group`. -If you would like to test this, navigate to the page URL in a private or incognito browser window and you will be redirected to the `Sign in to Proceed Further` page of your application. -The `Sign in to Proceed Further` page can be changed by going to `Pages → Settings` and picking the page you would like to render to users who need to sign in. +>To test this, navigate to the new page URL from a private or incognito browser window, and you will be redirected to the default `Sign in to Proceed Further` page of your application. +The `Sign in to Proceed Further` page can be changed by going to `Pages` → `Settings` and picking the page to render for users who need to sign in. ## Protect Content -1. Select `Content → Management` from the left navigation -1. Select the `Add Content` button and pick the content type to be created -1. To protect a content item, assign the `Owner Group` to any group other than `Free Access` -1. (Optional) Add groups via `Join Group` +1. Select `Content` → `Management` +1. Click the `Add` button and choose the type to create from the drop-down list +1. Assign an `Owner Group`. +1. (Optional) Add groups via `Join Group` to allow viewing access. + 1. Finish configuring the page and select `Save` -The content you are creating will only be available to users assigned to the `Owner Group` of `Join Group`. The default WCMS widgets will only return content authorized for a given user. See the [freemarker tags](#freemarker-tags-and-consuming-protected-resources) section below for information on creating custom widgets that utilize protected content. +Only users within the `Owner Group` can view and edit the content. Users assigned to groups listed under the `Join Group` field can view it. See the [FreeMarker tags](#freemarker-tags-and-consuming-protected-resources) section below for information on creating custom widgets that utilize protected content. -::: tip Images and Attachments and Groups +::: tip Access to Images and Attachments -When creating content the `Owner Group` of the content and the `Group` assigned to the digital asset must match. For example, when creating content with an `Owner Group` of `Administrators` the content creator will be unable to select images and attachments that are assigned a different group. The exception to this is assets with a group of `Free Access`. Assets with `Free Access` can be added to protected content. +An item with the `Free Access` assignment offers viewing access to everyone. Items with `Free Access` can be added to protected pages. ::: ## Protect Images and Attachments Images and attachments uploaded to the CMS can be protected by assigning groups. -1. Select `Content → Assets` from the left navigation -2. Upload your file(s) -3. In the provided modal window select the `Group` that you would like to own the asset -4. Only users with the assigned `Group` will have the ability to view the asset you've created - - The asset will only be available to content with the same `Group` unless the attachment or image has been given a group of `Free Access` - - -## Freemarker Tags and Consuming Protected Resources +1. Select `Content` → `Assets` from the left navigation +2. Click `Add` to select and upload your file(s) +3. For the `Group` field, select the owner group to grant viewing and editing privileges +4. Only users within the assigned `Group` will have the ability to view and edit the asset you've created + - The asset is available to content such as pages with the same `Group` assignment unless it has been assigned `Free Access`. -The WCMS provides a set of freemarker tags to assist in consuming protected assets in widgets and pages. The [if-authorized](../../docs/reference/freemarker-tags/freemarker-core-tags.md#tag-ifauthorized) and [tag-nav](../../docs/reference/freemarker-tags/freemarker-core-tags.md#tag-nav) tags can help in rendering page lists and fetching assets. +## FreeMarker Tags and Consuming Protected Resources -The [content](../../docs/reference/freemarker-tags/freemarker-JACMS-tags.md#tag-content) and [content-list](../../docs/reference/freemarker-tags/freemarker-JACMS-tags.md#tag-contentlist) tags also provide the ability to fetch and render protected content and protected lists of content. +Entando supports a set of FreeMarker tags to assist in accessing and using protected assets in widgets and pages. The [if-authorized](../../docs/reference/freemarker-tags/freemarker-core-tags.md#tag-ifauthorized) and [tag-nav](../../docs/reference/freemarker-tags/freemarker-core-tags.md#tag-nav) tags can help in rendering page lists and fetching assets. +The [content](../../docs/reference/freemarker-tags/freemarker-JACMS-tags.md#tag-content) and [content-list](../../docs/reference/freemarker-tags/freemarker-JACMS-tags.md#tag-contentlist) tags also provide the ability to fetch and render protected content and lists of content. -Additionally, the [REST APIs](../../docs/consume/entando-apis.md) allow clients to fetch protected pages and assets by group via query parameters. The content REST APIs also include the ability to filter by group and access level. +Additionally, [REST APIs](../../docs/consume/entando-apis.md) allow clients to fetch protected pages and assets by group via query parameters. The content REST APIs also include the ability to filter by group and access level. diff --git a/vuepress/docs/v7.3/tutorials/compose/digital-assets-tutorial.md b/vuepress/docs/v7.3/tutorials/compose/digital-assets-tutorial.md index 2e07d0c200..9a2d97edb4 100644 --- a/vuepress/docs/v7.3/tutorials/compose/digital-assets-tutorial.md +++ b/vuepress/docs/v7.3/tutorials/compose/digital-assets-tutorial.md @@ -4,10 +4,10 @@ sidebarDepth: 2 # Digital Assets -The Entando Web Content Management System (WCMS) includes capabilities to manage content and digital assets. Digital assets are images, documents and other media files with specific formats. +The Entando Web Content Management System (WCMS) includes capabilities to manage content and digital assets. These can include images, documents and other media files in the following formats. -**Default Supported Document Formats:** `pdf`, `xls`, `doc`, `ppt`, `txt`, `rtf`, `sxw`, `sxc`, `odt`, `ods`, `odp`, `tar`, `gz`, `zip`, `rar`, `flv`, `swf`, `avi`, `wmv`, `ogg`, `mp3`, `wav`, `ogm`, `mov`, `iso`, `nrg`, `docx`, `docm`, `xlsx`, `xlsm`, `xlsb`, `pptx`, `pptm`, `ppsx`, `ppsm`, `sldx`, `sldm` -The Entando WCMS can be configured to allow or exclude any type of file extension. The MIME type of each App Builder asset should be specified. +**Default Supported Document Formats:** `pdf`, `xls`, `doc`, `ppt`, `txt`, `rtf`, `sxw`, `sxc`, `odt`, `ods`, `odp`, `tar`, `gz`, `zip`, `rar`, `flv`, `swf`, `avi`, `wmv`, `ogg`, `mp3`, `wav`, `ogm`, `mov`, `iso`, `nrg`, `docx`, `docm`, `xlsx`, `xlsm`, `xlsb`, `pptx`, `pptm`, `ppsx`, `ppsm`, `sldx`, `sldm` +The WCMS in the App Builder can be configured to allow or exclude any type of file extension. The MIME type of each asset should be specified. **Default Supported Image Formats**: `jpg`, `jpeg`, `png`, `svg`, `svg+xml` @@ -16,62 +16,64 @@ The Entando WCMS can be configured to allow or exclude any type of file extensio 1. Log in to the App Builder 2. From the left sidebar, go to `Content` → `Assets` ![Digital Asset Main Page](./img/assets-manage.png) - * View `Images` or `Attachments` using the links at the top of the page - * Search for assests by Name and/or the parameters of the `Advanced filters` function - * Assets are displayed by Name in alphabetical order. Change the order using the buttons above the list and `Choose View` to toggle between list and grid formats - * Click on the action menu (indicated by three vertical dots) of the resource to edit or delete the asset and preview available sizes + * Select `Images` or `Attachments` in the tabs at the top of the page + * Search for assests by name and/or by using the `Advanced filters` + * Assets are displayed in alphabetical order by name. Organize the results with the `Order by` buttons just above the list. Toggle between list and grid formats with the `Choose View` button. + * Click on the action menu (indicated by three vertical dots) of the item to edit or delete it. ![Digital Asset Information](./img/assets-info.png) ### Add a New Asset -1. From the left sidebar of the App Builder, go to `Content` → `Assets` -2. Click the `Add` button to add a new image or document file +1. From the left sidebar, go to `Content` → `Assets` +2. Click the `Add` button ![Add Digital Assets Window](./img/assets-add.png) -3. Define the asset parameters: - - `Group`: Choose from the drop-down menu. This is a required field and defaults to `Free Access`. Additional groups can be defined in the Users section of the App Builder. - - `Categories`: You have the option to add the asset to a category using the `+` symbol under `Join`. Categorizing an asset expands upon the criteria by which it can be searched and sorted. New categories can be created via `Content` → `Categories`. - - Add your asset by dragging it into the frame or click `browse` to select it from the file system. The file you choose should appear in the Name field, which is a required value. Multiple files can be selected simultaneously. To add files individually, use `Add Another Resource` and `Choose file` (for the first asset selection) or `Select file` (for subsequent assets). -4. (Image only) You have the option to flip, rotate or crop your image per [Edit Assets](#edit-assets) -5. Click `Add` to upload your asset(s) -6. Confirm the list of assets displays the file(s) you uploaded +3. Define the asset's parameters: + - `Group`: Choose from the drop-down menu. This is a required field and defaults to `Free Access` which does not limit access. Additional groups can be defined in the Users section of the App Builder. + - `Categories`: You have the option to add the asset to a category using the `+` button under `Join`. Categorizing an asset expands the criteria by which it can be searched and sorted. New categories can be created via `Content` → `Categories`. + - Add your asset by dragging it into the frame or click `browse` to select it from the file system. The file you choose should appear in the Name field. Use the `Add Another Resource` and `Choose file` buttons to select multiple items simultaneously. +4. (Image only) You have the option to flip, rotate or crop your image by selecting [Edit](#edit-assets) from the kebab drop-down menu of each item. +5. Click `Save` to upload your asset(s). +6. Confirm the list of images or attachments displayed in the table. ## Edit Assets -1. From the left sidebar of the App Builder, go to `Content` → `Assets` -2. Click on the action menu (indicated by three vertical dots) of the resource +1. From the left sidebar, go to `Content` → `Assets` +2. Click on the action menu (indicated by three vertical dots) next to the item 3. Select `Edit` to modify the asset: - Edit the asset name via the text field - Edit the asset's category using the `+` button under `Join` - To edit an image: 1. Click on the actions menu to the right of the image and select `Edit` ![Add Digital Assets Window](./img/assets-edit-image.png) - 2. Use the arrows to flip, rotate or recenter your image - 3. Click the `Crop` check button to resize your image. Click `Free` to remove resizing ratio restrictions. - 4. (Optional) repeat this process to create additional modified instances of the image - 5. Click `Done` - 6. Click `Add` to save all image versions - > Note: Only newly uploaded images can be flipped, rotated or cropped -4. Click the `Add` button to save your edits + 2. Use the arrows to flip, rotate, zoom or recenter your image. Use the select window to resize. Click `Free` to remove the resizing ratio restrictions. + 3. Click the check button after all changes are made. + 4. Click `Close` when all changes are done + +4. Click the `Save` button to save your edits ::: tip To organize or download assets, go to `Administration` → `File browser` and navigate to `/public/cms` ::: ## Embed an Image on a Page -An image can be embedded on a page using FreeMarker code following the format of **<@wp.resourceUrl>cms/images/YOUR-ASSET.jpg**. Go to `Administration` → `File Browser` in the App Builder to see the list of uploaded images. +An image can be embedded on a page using FreeMarker code like this: +```html +<@wp.resourceUrl>cms/images/YOUR-ASSET.jpg +``` +Go to `Administration` → `File Browser` and navigate to `/public/cms` to see the list of uploaded images. ![File Browser](./img/assets-filebrowser.png) ## Include an Asset in Content -The asset can be added to a content type that has an `Attach` or `Image` attribute. Refer to the [Content Type tutorial](./content-types-tutorial.md) for a detailed set of instructions. +The asset can be added to a content type that has an `Attach` or `Image` attribute. Refer to the [Content Type tutorial](./content-types-tutorial.md) for detailed instructions. ## Configure File Extensions for Upload -The file types that can be uploaded to an Entando Application are defined on the server side of the App Builder, e.g. in `entando-de-app` of a quickstart application. +The file types that can be uploaded to an Entando Application are defined on the server side of the App Builder, in the `entando-de-app` of a quickstart application. Two properties in `src/main/conf/systemParams.properties` specify the supported file types via comma delimitted lists: * `jacms.imageResource.allowedExtensions=` * `jacms.attachResource.allowedExtensions=` -For example, `jacms.imageResource.allowedExtensions=jpg,jpeg,png,svg,svg+xml`, where `svg+xml` is the MIME type for an SVG image. The MIME type of an asset is checked by APIs that support resources and should be defined in addition to the asset's file extensions. +For example, `jacms.imageResource.allowedExtensions=jpg,jpeg,png,svg,svg+xml`, where `svg+xml` is the MIME type for an SVG image. The MIME type of an asset is checked by APIs that support them and should be defined in addition to the asset's file extension. The `systemParams.properties` file is bundled into the WAR, so an image must be created and deployed to reflect changes to these properties. diff --git a/vuepress/docs/v7.3/tutorials/compose/img/Publish1.png b/vuepress/docs/v7.3/tutorials/compose/img/Publish1.png deleted file mode 100644 index c7899436e2..0000000000 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/Publish1.png and /dev/null differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/Publish2.png b/vuepress/docs/v7.3/tutorials/compose/img/Publish2.png deleted file mode 100644 index 74132bdda0..0000000000 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/Publish2.png and /dev/null differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/Publish3.png b/vuepress/docs/v7.3/tutorials/compose/img/Publish3.png deleted file mode 100644 index 810d53ade1..0000000000 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/Publish3.png and /dev/null differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/Publish4.png b/vuepress/docs/v7.3/tutorials/compose/img/Publish4.png deleted file mode 100644 index 837a554cb3..0000000000 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/Publish4.png and /dev/null differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/Publish5.png b/vuepress/docs/v7.3/tutorials/compose/img/Publish5.png deleted file mode 100644 index 5e7c893249..0000000000 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/Publish5.png and /dev/null differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/Publish5b.png b/vuepress/docs/v7.3/tutorials/compose/img/Publish5b.png deleted file mode 100644 index ccd90090c1..0000000000 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/Publish5b.png and /dev/null differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/content_types1.png b/vuepress/docs/v7.3/tutorials/compose/img/content_types1.png index 134f53aed7..e6e9cbab74 100644 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/content_types1.png and b/vuepress/docs/v7.3/tutorials/compose/img/content_types1.png differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/content_types5.png b/vuepress/docs/v7.3/tutorials/compose/img/content_types5.png index 15ba225eb3..9e986d302b 100644 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/content_types5.png and b/vuepress/docs/v7.3/tutorials/compose/img/content_types5.png differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/publish6.png b/vuepress/docs/v7.3/tutorials/compose/img/publish6.png deleted file mode 100644 index cc80951cb3..0000000000 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/publish6.png and /dev/null differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/publish_page5.png b/vuepress/docs/v7.3/tutorials/compose/img/publish_page5.png index a01ea76c4e..f5f5b0cff7 100644 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/publish_page5.png and b/vuepress/docs/v7.3/tutorials/compose/img/publish_page5.png differ diff --git a/vuepress/docs/v7.3/tutorials/compose/img/publish_page5b.png b/vuepress/docs/v7.3/tutorials/compose/img/publish_page5b.png index aa482aadf0..5793cd3304 100644 Binary files a/vuepress/docs/v7.3/tutorials/compose/img/publish_page5b.png and b/vuepress/docs/v7.3/tutorials/compose/img/publish_page5b.png differ diff --git a/vuepress/docs/v7.3/tutorials/compose/page-management.md b/vuepress/docs/v7.3/tutorials/compose/page-management.md index fa7dd49093..a24b70676e 100644 --- a/vuepress/docs/v7.3/tutorials/compose/page-management.md +++ b/vuepress/docs/v7.3/tutorials/compose/page-management.md @@ -1,101 +1,101 @@ # Page Management -The [Entando App Builder](../../docs/compose/app-builder.md) provides the capability to publish application pages containing content as well as other Entando components. Page Templates are used to define the layout of available frames on a page. +The [Entando App Builder](../../docs/compose/app-builder.md) provides the Content Management System (CMS) to design and publish application pages. Page Templates are used to define the layout using frames on a page where content and other frontend components are placed. Details of this process are examined below. -The App Builder also offers a distributed editorial management method for your application through roles and groups. When a user is created, they are assigned a role or added to a group to grant access to the application pages they are responsible for. For details, see the [Manage Roles, Users, and Groups tutorial](./role-users-groups.md) +Additionally, the App Builder offers a distributed editorial management system through roles and groups. When a user is created, they are assigned a role and added to groups to grant access to the content and pages of an application. For details on this topic, see the [Manage Roles, Users, and Groups tutorial](./role-users-groups.md). ## Create a Page -Follow the steps below to create a Page with a Content widget. +Follow the steps below to create a page with a content widget. -**1. Go to `Pages` → `Management`.** +**1. Go to `Pages` → `Management` in the App Builder.** ![image](./img/publish_page1.png) **2. Click the `Add` button.** -This generates a form where the following fields are mandatory: +This generates a form with the following required fields: - `Title`: used for SEO -- `Code`: must be unique -- `Page placement`: the location of the Page in the Page Tree -- `Owner Group`: the Group that should have access to the Page -- `Page Template`: the structure and presentation of the Page +- `Code`: must be unique (maximum of 100 alphanumeric characters, upper- and lowercase, and the '_' and '-' characters) +- `Select page placement`: the location of the page in the page tree +- `Owner group`: the group that should have access to edit and design the page +- `Page Template`: the structure and layout of the page ![image](./img/publish_page2.png) -**3. Click the `Save and Design` button.** +**3. Click `Save and Design`.** -This loads the Designer UI, which lets you place widgets into the Page Template frames. +This launches the Page Designer where you place frontend components into the Page Template frames. Note the widgets are categorized by type, including CMS, Navigation, and User which are created by you. ![image](./img/publish_page3.png) **4. Add a widget.** -This is done by dragging a widget from the right panel into the desired frame. Adding the Content widget will load the configuration page shown below. +Drag a widget from the right panel into the desired frame. Adding the Content widget loads the configuration page shown here. ![image](./img/publish_page4.png) **5. Click `Add existing content`.** -This generates the content selection pop-up. +This opens the content selection pop-up window. ![image](./img/publish_page5.png) -You can search for the name of the content that you would like to publish. Remember that content must be saved and approved before it can be published to a page. +Search for content by name, use the Advanced filters, or browse the table to find what you need. Remember that content must be saved and approved before it can be published to a page. **6. Select the desired content item(s) from the list.** -**7. Click the `Continue` button.** +**7. Click `Choose`.** -The selected `Content` item will now be displayed. +The selected `Content` item is displayed here. ![image](./img/publish_page5b.png) -**8. Click the `Save` button.** +**8. Click `Save` at the top of the page.** The following actions are now available: -- Click on the `Preview` button to show the page preview with the updated settings. -- Click on the `Publish` button to publish the page. -- Click on the `View published page` button to view the published page in your application. +- `Preview` to show the page with the updates +- `Publish` +- `View published page` to view the page in your application. ## Page Templates -Page Templates provide the scaffolding of a Page and are constructed using two main elements: +Page Templates provide the scaffolding of a page and are constructed using two main elements: -- A `JSON configuration` field which lists the set of frames that can be used on a page. -- A `Template` field which uses Freemarker code to setup the HTML page itself. +- A `JSON configuration` field which lists the set of frames that can be used on a page +- A `Template` field which uses FreeMarker code to setup the HTML page ### JSON Configuration Each item in the `frames` array of the JSON configuration represents a frame or slot in the page, characterized by the following values: -- `pos`: A zero-based position index (starts from zero). This value is used by APIs to address a specific widget on the page. -- `descr`: The frame description displayed in the Page Design view. +- `pos`: A zero-based position index (starting from zero). This value is used by APIs to address a specific widget on the page. +- `descr`: The frame description displayed in the Page Designer view. - `mainFrame`: This designates the primary frame in the Page Template. - `defaultWidget`: The code for a default widget to use in this frame. Page Template developers can use this field to provide suggestions for common widgets, e.g. header and footer widgets. - `sketch`: An object with 4 coordinates (x1,x2,y1,y2) to allow the developer to place the widgets in the Page preview. The x and y values go from 0 to 11 (similar to columns in Bootstrap), so if you want to place a 2x2 frame at the top left corner of the page, the values would be `x1: 0`, `x2: 1`, `y1: 0` and `y2: 1`. ### Template -To add a frame in a specific place of the page, input `<@wp.show frame=0 />`, where `frame` is the `pos` variable from the `JSON configuration`. To setup the `wp` variable, `<#assign wp=JspTaglibs["/aps-core"]>` is required at the top of the template. +To add a frame in a specific position on the page, input `<@wp.show frame=0 />`, where `frame` is the `pos` variable from the `JSON configuration`. To setup the `wp` variable, `<#assign wp=JspTaglibs["/aps-core"]>` is required at the top of the template. -Common code can be shared across Pages by using [UX Fragments](./widgets-fragments.md#create-and-update-a-ux-fragment) and ```<@wp.fragment code="\" escapeXml=false /\>```. +Common code can be shared across multiple pages by using [UX Fragments](./widgets-fragments.md#create-and-update-a-ux-fragment) and ```<@wp.fragment code="\" escapeXml=false /\>```. ### Create a Page Template -Follow the steps below to prepare a Page Template with two frames on it. +Follow the steps below to prepare a Page Template with two frames. **1. Go to `Pages` → `Templates` → `Add`** ![image](./img/publish_page6.png) -**2. Enter the field information below:** +**2. Enter the field values as shown below:** -- `Code`: double_frame (Note: Dashes are not allowed) -- `Name`: Double Frame -- `JSON Configuration:` +- `Code`: double_frame (allows max of 40 uppercase or lowercase letters, numbers and special characters) +- `Name`: Double Frame (allows max of 50 uppercase or lowercase letters, numbers and special characters) +- `JSON Configuration`: ``` json { @@ -118,7 +118,7 @@ Follow the steps below to prepare a Page Template with two frames on it. } ``` -- `Template:` +- `Template`: ``` ftl <#assign wp=JspTaglibs["/aps-core"]> @@ -126,6 +126,7 @@ Follow the steps below to prepare a Page Template with two frames on it. <@wp.currentPage param="title" /> + <@wp.fragment code="keycloak_auth" escapeXml=false />

<@wp.currentPage param="title" />

@@ -134,11 +135,10 @@ Follow the steps below to prepare a Page Template with two frames on it. ``` -Include the following fragment in the `head` section to make use of the user's Keycloak identity information. -```ftl -<@wp.fragment code="keycloak_auth" escapeXml=false /> -``` +The fragment in the `head` section `<@wp.fragment code="keycloak_auth" escapeXml=false />` makes use of the user's Keycloak identity information. -**3. Verify that the `Template preview` is reflecting the desired two frame layout.** -**4. Click the `Save` button.** \ No newline at end of file +**3. Verify that the `Template preview` reflects the two frame layout.** + +**4. Click the `Save` button.** +This Template is now available to use in your application. \ No newline at end of file diff --git a/vuepress/docs/v7.3/tutorials/compose/role-users-groups.md b/vuepress/docs/v7.3/tutorials/compose/role-users-groups.md index 133f1a86cc..765b817082 100644 --- a/vuepress/docs/v7.3/tutorials/compose/role-users-groups.md +++ b/vuepress/docs/v7.3/tutorials/compose/role-users-groups.md @@ -5,44 +5,45 @@ sidebarDepth: 2 # Manage Roles, Users and Groups ## Role-based Page Management -The Entando App Builder provides a page management system with distributed editorial controls. With editing privileges based on roles and groups, a user only sees the application pages they're given access to when they log in. Users and groups are assigned different levels of control and access to manage only those pages with the proper group ownership. +Entando provides distributed editorial controls for building composable applications. With editing privileges based on roles and groups, a user only sees the application pages they're given access to when they log in. Users are assigned roles and groups based on group ownership so teams can manage portions of the application that belong to them. -This tutorial demonstrates how to grant a user editorial access to a particular page in an application. +This tutorial demonstrates how to grant editorial access to a particular page in an application. -To add controls to micro frontends and/or microservices and additional details, see the [Role Based Access Controls for Micro Frontends & Microservices](../create/ms/add-access-controls.md) tutorial. +To add controls to micro frontends and/or microservices, see the [Role Based Access Controls for Micro Frontends & Microservices](../create/ms/add-access-controls.md) tutorial. -### 1. Create Role -This role will have access to edit, delete, and create pages. Users are assigned roles and added to groups who own the pages of an application. +### 1. Create a Role +This role will have access to edit, delete, and create pages. Users are assigned roles and then added to groups who own the pages of an application. 1. Log in to your Entando App Builder. 2. Go to `Users`→ `Roles` in the left navigation menu. 3. Click `Add` to create a new role. 4. Enter a name and code. -5. Turn `ON` the following selections under `Permissions`: `Content Editing`, `Access to Administration Area` and `Operations on Pages`. Click `Save`. +5. Turn `ON` the following selections under `Permissions`: `Content Editing`, `Access to Administration Area` and `Operations on Pages`. +6. Click `Save`. ![AddPermissionsToRole](./img/add-permissions-role.png) -### 2. Create Group +### 2. Create a Group 1. Go to `Users`→ `Group` from the left navigation menu. -2. Click `Add` to create a new group that will manage a subsection of the application. +2. Click `Add` to create a new group who will manage a subsection of the application. 3. Enter a name and code. Click `Save` -### 3. Add New User -1. Go to `Users`→ `Management` in the left navigation menu. -2. Click `Add` to create a new user. -3. Enter a `Username` and `Password`. Select the default `Profile Type` and `Status`: `ON`. -Click `Save`. The user account will appear with `Status`: `Expired Password` until the first time they login and reset their password. To change this status or add an email, go to `Edit` in the `Actions` column. +### 3. Add a New User, assign role and group +1. From the left navigation menu, go to `Users`→ `Management`. +1. Click `Add` to create a new user. +1. Enter a `Username` and `Password`. Select the default `Profile Type` and `Status`: `ON`. +1. Click `Save`. The user account will appear with `Status`: `Expired Password` until the first time they log in and reset their password. To change this status or add an email, go to `Edit` from the `Actions` menu of the User account. ![AddNewUser](./img/add-user.png) -4. For the new user, select `Manage Authorization for: USERNAME` under the `Actions` column. -5. Select `Add new Authorization` and choose the `User Group` and `User Role` created above. Click `Add`. -6. Click `Save`. +1. For the new user, select `Manage Authorization for: USERNAME` under the `Actions` column. +1. Select `Add new Authorization` and choose the `User Group` and `User Role` created in the previous steps. Click `Add`. +1. Click `Save`. -### 4. Create New Page and Assign Owner Group -1. Go to `Pages`→ `Management` in the left navigation menu. +### 4. Create a New Page and Assign Owner Group +1. Go to `Pages`→ `Management` from the left navigation menu. 2. Click `Add` to create a new page. -3. Add `Title`, `Description`, `Keywords` and a `SEO-friendly Code` for the new page. Fill in the remaining fields as appropriate. -4. For `Owner group`, under the `Page groups` heading, choose the newly created group who should have editing privileges to this page. If `Free` is chosen, all users will have access to this page. +3. Add `Title`, `Code` and other fields as appropriate. See [Page Management](page-management.md) for more details. +4. Under the `Page groups` heading, choose the `Owner group` who should have editing privileges to this page. If `Free Access` is chosen, everyone can view this page and users with access to the App Builder can edit the page. 5. Click `Save`. -When the new user logs in, they will have access only to the pages for which they are part of the authorized Owner Group. +When the new user logs in, they will only have access to the pages for which they are part of the authorized Owner Group. #### Existing Page Assignment -If you need to assign editorial access to existing pages, add the user to the current Owner Group for the page in the `User Management` section. If a new group was added, go to `Pages` → `Management` from the left navigation menu, and select `Edit` under the `Actions` drop-down menu to reassign `Owner group` for each page. +If you need to assign editorial access to existing pages, add the user to the current Owner Group for the page in the `User Management` section. If a new group was added, go to `Pages` → `Management`, and select `Edit` under the `Actions` drop-down menu to reassign `Owner group` for each page. diff --git a/vuepress/docs/v7.3/tutorials/compose/widgets-fragments.md b/vuepress/docs/v7.3/tutorials/compose/widgets-fragments.md index c66d938ef0..1fb33e86cc 100644 --- a/vuepress/docs/v7.3/tutorials/compose/widgets-fragments.md +++ b/vuepress/docs/v7.3/tutorials/compose/widgets-fragments.md @@ -1,100 +1,105 @@ +--- +sidebarDepth:2 +--- # Widgets and Fragments -This tutorial covers the basics of how to create an Entando widget and place it on a page. It also reviews the -basics of fragments, which are reusable components of a user interface. +This tutorial covers the basics of how to create an Entando widget and place it on a page. It also incorporates fragments, adding it to templates to make it easy to reuse. ## Create and Publish a Widget -For this example, you will use the Entando App Builder to build and display a simple widget on a page. You would create and deploy widgets differently in a production system or larger development environment, but this gives a quick introduction to the building blocks. - -For a more advanced example, check out how to [generate microservices and micro frontends](../create/ms/generate-microservices-and-micro-frontends), which includes how to build and deploy a micro frontend as a widget in Entando. - -### Create a widget - -1. In the left pane of the App Builder, go to `Components` → `MFE & Widgets` -2. At bottom of the page, click `Add` -3. Create a widget with some sample HTML code. Enter or select the following: - - en Title: `Hello World` - - it Title: `Ciao Mondo` - - Code: `MyHelloWorld` - - Group: either `Administrators` or `Free Access` - - Icon: upload or select an icon of your choice - - Custom UI: `

Hello World

` - > Note: the Custom UI Field is a FreeMarker template where you can enter raw HTML and include FreeMarker logic. This allows you to import JavaScript, CSS or basic HTML. -4. Click `Save` - -### Place the widget on a page +For this example, you will use the App Builder to build and display a simple widget on a page. This is a quick introduction to one of the building blocks that make up composable applications. + +For a more advanced example, check out how to [generate microservices and micro frontends (MFEs)](../create/ms/generate-microservices-and-micro-frontends), which includes how to build and deploy a micro frontend as a widget in Entando. + +### 1. Create a widget + + 1. From the left navigation menu of the App Builder, go to `Components` → `MFE & Widgets` + 2. To create a new widget, click `Add` + 3. Enter the following values: + - en Title: `Hello World` + - it Title: `Ciao Mondo` + - Code: `MyHelloWorld` + - Group: either `Administrators` or `Free Access` + - Icon: upload or select an icon of your choice + - Custom UI: `

Hello World

` + > Note: the Custom UI Field is a FreeMarker template where you can enter raw HTML and include FreeMarker logic. This allows you to import JavaScript, CSS or basic HTML. + 4. Click `Save` + +### 2. Place the widget on a page -1. From the left pane of the App Builder, go to `Pages` → `Settings` -2. Select a page, e.g. "Home / Service" from the “Home Page” dropdown menu -3. Click `Save` -4. From the left pane of the App Builder, go to `Pages` → `Management` -5. On the row with the folder named for your page (e.g. "Service"), click on the Actions icon and select "Design" -6. From the Widgets tab in the right pane, drag and drop your new widget into an open frame on the page -7. At the top of the middle pane, click `Preview` -8. Confirm that your page displays "Hello World" +1. Go to `Pages` → `Management` from the left navigation menu. +1. Create a [new page](page-management.md#create-a-page) or select an existing page to add the widget to. +1. Click the corresponding Actions icon and choose `Design` from the drop-down. +1. From the Widgets tab in the right pane, under the User list of widgets, drag and drop your new widget into an open frame on the page. +1. Click the `Preview` button at the top to display your page. +1. Confirm that your page displays "Hello World". -### Publish the updated page - -1. Navigate back to "Design" for your page -2. At the bottom of the middle pane, click `Publish`. Note that the Status icon for your page, represented by a colored dot, has changed from yellow to green. +### 3. Publish the updated page +1. Navigate back to the Page Designer +2. Below your application page, click `Publish`. Note that the Status icon for your page, the circle next to the page title, has changed from yellow to green to show its completed status. ## Create and Update a UX Fragment A UX fragment is a way to reuse snippets of frontend code across multiple pages or widgets. Common elements such as basic HTML, JavaScript or FreeMarker logic can be stored as fragments and referenced via the `<@wp.fragment …` tag. -To create and update a basic UX fragment per the steps below, first [create and publish a widget](#create-and-publish-a-widget) as the basis for this exercise. +The [create and publish a widget](#create-and-publish-a-widget) in the previous steps is a prerequisite for the next part of the tutorial. -### Create a new fragment +### 1. Create a new fragment -1. In the left pane of the App Builder, go to `Components` → `UX Fragments` -2. At bottom of the page, click `Add` -3. Enter the following field information: +1. Go to `Components` → `UX Fragments` +2. At the bottom of the page, click `Add` +3. Enter the following field values: - Code: `test` - Gui Code: `

Hello World

` 4. Click `Save` -### Identify the widget's page template +### 2. Identify the widget's page template -1. From the left pane of the App Builder, go to `Pages` → `Management` -2. On the row with the folder named for your page (e.g. "Service"), click on the Actions icon and select "Details" -3. Click on the `Info` button to expand the page information -4. Note the Page Template used for your page, e.g. "single_frame_page" -### Place the fragment in the template +1. Now go to `Pages` → `Management` +2. From the Actions drop-down menu for your desired page, select `Details` +3. Click the `Info` button to expand the page details +4. Note the Page Template used for your page, e.g., "single_frame_page" -1. From the left pane of the App Builder, go to `Pages` → `Templates` -2. On the row with the page template used for your page (e.g. "single_frame_page"), click on the Actions icon and select "Edit" -3. In the `Template` text box, add `<@wp.fragment code="test"/>` on a new line between the `` and `` tags +### 3. Place the fragment in the template + +1. Go to `Pages` → `Templates` from the left nav +2. In the Actions drop-down menu for the noted Template, select `Edit` +3. In the `Template` text box, add the following line within the `` tags: +``` html +<@wp.fragment code="test"/> +``` 4. At the bottom of the page, click `Save` -### View the page with the new fragment +### 4. View the page with the new fragment -1. From the left pane of the App Builder, go to `Pages` → `Management` -2. On the row with the folder named for your page (e.g. "Service"), click on the Actions icon and select "Design" -3. At the top of the middle pane, click `Preview` -> Note: The page will display the fragment `

This is a fragment.

`, which includes the HTML tags. By default, HTML embedded via a fragment tag is escaped, so it renders exactly as you enter it. You’ll need to un-escape the fragment to render it correctly. +1. Now go to `Pages` → `Management` +2. From the Actions drop-down menu for your page, select `Preview` + +> Note: The page will display the fragment `

This is a fragment.

` with the HTML tags. By default, HTML tags embedded within a fragment are ignored, or 'escaped', so it renders like a string, exactly as it appears. You need to reverse this when you call the fragment to render it properly. -### Update the fragment +### 5. Update the fragment -1. From the left pane of the App Builder, go to `Pages` → `Templates` -2. On the row with the page template used for your page (e.g. "single_frame_page"), click on the Actions icon and select "Edit" -3. Change the tag to `<@wp.fragment code="test" escapeXml=false/>` +1. Back in the App Builder, go to `Pages` → `Templates` +2. From the Actions drop-down menu for the Template, select `Edit` +3. Replace the inserted tag in Step 3 with this to render the html properly: + ```html + <@wp.fragment code="test" escapeXml=false/> + ``` -### View the page with the updated fragment +### 6. View the page with the updated fragment -1. From the left pane of the App Builder, go to `Pages` → `Management` -2. On the row with the folder named for your page (e.g. "Service"), click on the Actions icon and select "Design" -3. At the top of the middle pane, click `Preview` -4. Confirm the fragment is rendered correctly +1. Return to `Pages` → `Management` +2. Click on the Actions icon and select `Preview` for your test page +3. Confirm the fragment is rendered correctly ## FreeMarker Basics in Entando FreeMarker is a powerful templating language that provides flexibility in how pages are rendered. It allows you to include conditional logic, inject information from the backend, check for query parameters and route to different pages. For example: -- To check for a query parameter, use: +- To check for a query parameter: `<#if RequestParameters.myParam?exists > …` -- To check the current username, use: +- To check the current username: `<#if (Session.currentUser.username != "guest") >` Consider using [FreeMarker](https://freemarker.apache.org) for widgets that need to support dynamic behavior.