Peer review: View Entities #9106
Conversation
| @@ -7,31 +7,54 @@ cascade: | |||
| #If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. | |||
| --- | |||
|
|
|||
| {{% alert color="info" %}} This feature was introduced in Mendix 10.19 and is currently in beta. For more information, see [Beta and Experimental Releases](/releasenotes/beta-features/). {{% /alert %}} | |||
| {{% alert color="info" %}} | |||
| This feature was introduced in Studio Pro 10.19 and is currently in beta. For more information, see [Beta and Experimental Releases](/releasenotes/beta-features/). | |||
There was a problem hiding this comment.
Changed "Mendix 10.19" to "Studio Pro 10.19" since it's a feature in Studio Pro and "Mendix" is a broader term that refers to the whole platform.
|
|
||
| ## Introduction | ||
|
|
||
| A view entity represents the result set of a stored [OQL query](/refguide/oql/) and can be used similarly to a [persistable entity](/refguide/persistability/#persistable). This concept is similar to the function of views in general database technology. Whenever a view entity is retrieved via a page or a microflow, the corresponding OQL query executes to fetch the relevant data. Consequently, the result set of a view entity is not stored as a separate table in the database (like a materialized view). Instead, the query runs each time the view entity is accessed, dynamically retrieving the data. | ||
| A view entity represents the result set of a stored [OQL query](/refguide/oql/) and can be used similarly to a [persistable entity](/refguide/persistability/#persistable). This concept is similar to the function of views in general database technology. Whenever a view entity is retrieved via a page or a microflow, the corresponding OQL query runs and fetches the relevant data. Consequently, the result set of a view entity is not stored as a separate table in the database (like a materialized view). Instead, the query runs each time the view entity is accessed, dynamically retrieving the data. |
There was a problem hiding this comment.
Made this change to avoid the use of "executes".
| {{% alert color="info" %}} | ||
| View entities are read-only. To change the resulting data of a view entity retrieval, the source data should be modified. For this purpose, you can set up a microflow to map a view object to an object (or objects) of their corresponding source entity (or entities) and commit those. | ||
| {{% /alert %}} |
There was a problem hiding this comment.
Adjusted the styling of the alerts in the doc to keep consistent with the rest of our docs (also below).
| {{% alert color="info" %}} View entities are read-only. To change the resulting data of a view entity retrieval, the source data should be modified. For this purpose, you can set up a microflow to map a view object to object (or objects) of their corresponding source entity/entities and commit those. {{% /alert %}} | ||
| {{% alert color="info" %}} | ||
| View entities are read-only. To change the resulting data of a view entity retrieval, the source data should be modified. For this purpose, you can set up a microflow to map a view object to an object (or objects) of their corresponding source entity (or entities) and commit those. | ||
| {{% /alert %}} | ||
|
|
||
| ## Enabling OQL Version 2 |
There was a problem hiding this comment.
I was wondering whether we should change this "Enabling OQL Version 2" hearder to "Prerequisite" to emphasize that this is a must for using view entities (besides mentioning it in the paragraph).
|
|
||
| ## Enabling OQL Version 2 | ||
|
|
||
| Your app must use OQL version 2 to use view entities. You can change this setting by clicking **App** > **Settings** > **Runtime** and setting [OQL version 2](/refguide/app-settings/#oql-version-2) to **Yes**. You can also drag a new view entity from the toolbar or **Toolbox** to the domain model, in which Studio Pro will confirm setting the OQL version to 2. | ||
| Your app must use OQL version 2 to use view entities. You can change this setting by clicking **App 'APP_NAME'** > **Settings** > **Runtime** and setting [OQL version 2](/refguide/app-settings/#oql-version-2) to **Yes**. Alternatively, you can drag a new view entity from the toolbar or **Toolbox** to the domain model, which opens a dialog box where you can confirm upgrading to OQL version 2 if it has not been upgraded. | ||
|
|
||
| ## Properties |
There was a problem hiding this comment.
I rearranged the whole Properties section (including its sub-sections) to make it more allign with other docs. Some details might need technical verfication though. I will point out the content in other comments that might need to be verifed by devs.
| #### Name {#name} | ||
|
|
||
| The name property defines the name of the view entity. This name is used to refer to the view entity in forms, microflows, queries, constraints, etc. | ||
|
|
||
| The name has to be unique only within the domain model of a module. You can have two view entities with the same name, provided that they are in the domain models of different modules. | ||
|
|
||
| #### Image {#image} | ||
|
|
||
| The image property can be used to associate an image with a view entity. In the domain model, this image is shown in the top-left corner of the view entity. The image is also shown in other places where view entities are mentioned, such as the entity selection pop-up window when selecting an entity for a data view. |
There was a problem hiding this comment.
I added these two sub-sections based on the UI. I basically copied what's in this General section for entities but I don't know if those properties still work the same for view entities. Could you ask the dev team to verify this? Thanks!!
|
|
||
| ## Properties | ||
|
|
||
| After adding a view entity, you can specify the OQL query by double-clicking the entity to open the view entity properties dialog: | ||
| Double-clicking a view entity to open its properties dialog box. An example of a view entity's properties dialog box is represented in the image below: | ||
|
|
||
| {{< figure src="/attachments/refguide/modeling/domain-model/use-view-entities/customer-with-address.png" width="500" >}} |
There was a problem hiding this comment.
This image does not allign with the UI of SP 10.19 and 10.20. I am guessing that the person who provided this screenshot could be using an SP version that's not finalised yet before the first release. It's hard to replicate this screenshot ourselves. Is it possible to ask for their demo app or ask them to provide one that's from a released SP version?
| ## Using a View Entity | ||
|
|
||
| After creating a view entity in the domain model, it can be used in microflows and pages like any other entity. For more information, see [Use View Entities](/refguide/use-view-entities/). |
There was a problem hiding this comment.
I would suggest to place this Read More section in Use View Entities here since this doc offers more general information. And an overview of how-to examples seems to suit here as well. Besides, this doc is still short and the Use View Entities doc is already pretty long. Pls let me know what you think and feel free to refuse it if you don't think it's a good idea :)
Review language and format