[Task] Update docs (#920)

* Added new doc for alias operator * Added new doc for alias operator * Fix operators * Removed isOperator variable * Removed debug info * Added new operator section and documentation * Added new operator section and documentation * More operators * Added examples and screenshots * Reverted change to merge operator * Added mutation examples * Update security settings * Fix links * Fix links * Updated mutations page * Updated mutations page * Code format and lightboxes * Added info boxes * Updated documentation for advanced relations * Removed unused screenshots * Removed unused screenshots
pimcore · Dec 2, 2024 · 7bd6287 · 7bd6287
1 parent 656cfe6
commit 7bd6287
Show file tree

Hide file tree

Showing 91 changed files with 887 additions and 325 deletions.
diff --git a/doc/02_Basic_Principle.md b/doc/02_Basic_Principle.md
@@ -6,11 +6,15 @@ Pimcore Datahub allows defining multiple endpoints that allow data delivery and
 
 1. Open the Datahub configuration panel:
 
+<div class="image-as-lightbox"></div>
+
 ![Configuration Overview](./img/graphql/configuration3.png)
 
 
 2. Choose an endpoint technology: 
 
+<div class="image-as-lightbox"></div>
+
 ![Add Configuration](./img/add_config.png)
 
 3. Get the configuration done by defining the followings:

diff --git a/doc/10_GraphQL/01_Configuration/01_General_Settings.md b/doc/10_GraphQL/01_Configuration/01_General_Settings.md
@@ -1,5 +1,7 @@
 # General Settings
 
+<div class="image-as-lightbox"></div>
+
 ![General Settings](../../img/graphql/general.png)
 
 #### Some Aspects:
@@ -8,9 +10,15 @@
   the [workspace settings](./03_Security_Settings.md).
 
 SQL Condition is currently deprecated but still enabled by default. If you want to disable it, you can do so in the symfony configuration tree:
-```
+
+```yaml
 pimcore_data_hub:
     graphql:
         allow_sqlObjectCondition: false
 ```
-Please note that this option will be also removed in the next major version.
+
+:::caution
+
+Please note that this option will be also removed in the next major version.
+
+:::
diff --git a/doc/10_GraphQL/01_Configuration/02_Schema_Settings.md b/doc/10_GraphQL/01_Configuration/02_Schema_Settings.md
@@ -2,6 +2,8 @@
 
 Schema settings define which data entities (Data Object classes, Assets, Documents) should be exposed via the endpoint. For Assets and Documents, default schemas are provided, for Data Object classes the schema can be defined in the field configuration.
 
+<div class="image-as-lightbox"></div>
+
 ![Add](../../img/graphql/schema_add.png)
 
 ## Query Schema
@@ -14,9 +16,16 @@ When adding a new entity with the `Add` button, you can access the `Available Fi
 
 In addition, you can employ a set of operators.
 
+<div class="image-as-lightbox"></div>
+
 ![Schema Settings](../../img/graphql/schema.png)
 
+:::info
+
 Please note that not all data types are supported yet!
+
+:::
+
 You will get a notice if you try to add an unsupported data type.
 
 ## Mutation Schema

diff --git a/doc/10_GraphQL/01_Configuration/03_Security_Settings.md b/doc/10_GraphQL/01_Configuration/03_Security_Settings.md
@@ -1,17 +1,31 @@
 # Security Settings
 
+The security settings define how the endpoint is secured and which data is accessible.
+
+<div class="image-as-lightbox"></div>
+
+![security1.png](../../img/graphql/security1.png)
+
 ## Authentication
 
 Here you can define how users are authenticated when accessing the endpoint.
 
 #### Supported Methods
 
 * API Key: needs to be sent with every request.
-* ... more to come
+
+#### API Key
+
+To automatically create an API key use the button next to the input. 
+For each click on the button a new API key is generated and will be added to the input field in addition to the list of existing keys.
 
 ## Introspection Settings
 
-Introspection provides an information about queries which are supported by GraphQl schema. This is currently enabled by default. It can be disabled via security settings or in the symfony configuration tree:
+Introspection provides an information about queries which are supported by GraphQl schema. 
+If introspection is enabled, the endpoint will provide a schema definition which can be used by GraphiQL or other tools to provide auto-completion and documentation.
+If introspection is disabled, the schema definition will not be provided and therefore no auto-completion or documentation will be available.
+
+This is currently enabled by default. It can be disabled via security settings tab directly in the backend or in the symfony configuration tree:
 ```
 pimcore_data_hub:
     graphql:
@@ -20,17 +34,21 @@ pimcore_data_hub:
 
 ## Workspace Settings
 
-Defines workspaces for data that should be accessible via the endpoint. 
+Defines workspaces for data that should be accessible via the endpoint.
 The definition is similar to Pimcore user [workspace permissions](https://pimcore.com/docs/6.x/Development_Documentation/Administration_of_Pimcore/Users_and_Roles.html) 
 
+:::warning
+
+If no workspace is selected, no directories are accessible.
+
+:::
+
 Available permissions:
 * Create
 * Read
 * Update
 * Delete
 
-![Settings](../../img/graphql/security1.png)
-
 
 ## Error Handling  - Configuration Values
 

diff --git a/doc/10_GraphQL/04_Query/05_DataObject_Queries.md b/doc/10_GraphQL/04_Query/05_DataObject_Queries.md
@@ -1,6 +1,6 @@
 # DataObject Queries
 
-## Supported Data Types
+## Suppored Data Types
 
 Also check out the Pimcore's [data type documentation](https://pimcore.com/docs/6.x/Development_Documentation/Objects/Object_Classes/Data_Types/index.html). 
 
@@ -53,18 +53,7 @@ Also check out the Pimcore's [data type documentation](https://pimcore.com/docs/
 
 ## Available Query Operators
 
-Check out the [Operators](./06_Operators.md) page for more information.
-
-* Alias
-* Asset Thumbnail
-* Asset Thumbnail HTML
-* Concatenator
-* Date Formatter
-* Element Counter
-* Merge
-* Substring
-* Static Text
-* Trimmer
+Check out the [operators section](../08_Operators/README.md) for more information.
 
 ## Get single Data Object
 

diff --git a/doc/10_GraphQL/04_Query/06_Operators.md b/doc/10_GraphQL/04_Query/06_Operators.md
diff --git a/doc/10_GraphQL/04_Query/08_Localization.md b/doc/10_GraphQL/04_Query/08_Localization.md
@@ -6,7 +6,7 @@ You can change the default language for localized fields by passing the `default
 for single and listing queries.
 
 #####  Sample Request
-```
+```graphql
 {
   getNewsListing(defaultLanguage: "de") {
   ...
@@ -18,7 +18,7 @@ for single and listing queries.
 However, you can always provide an alternative language for a specific field.
 
 #####  Sample Request
-```
+```graphql
 {
   getUser(id: 50, defaultLanguage: "en") {
     myAdvancedObjects {
@@ -39,7 +39,7 @@ However, you can always provide an alternative language for a specific field.
 ```
 
 ##### Response
-```
+```graphql
 {
   "data": {
     "getUser": {

diff --git a/doc/10_GraphQL/04_Query/10_Filtering.md b/doc/10_GraphQL/04_Query/10_Filtering.md
@@ -6,7 +6,9 @@ to filter listing.
 
 
 ## Sample
-Get all `Manufacturer` objects which have 'ca' in their name field. 
+Get all `Manufacturer` objects which have 'ca' in their name field.
+
+<div class="image-as-lightbox"></div>
 
 ![Filtered Grid](../../img/graphql/filtering.png)
 

diff --git a/doc/10_GraphQL/04_Query/11_Query_Samples/05_Sample_Element_Properties.md b/doc/10_GraphQL/04_Query/11_Query_Samples/05_Sample_Element_Properties.md
@@ -1,5 +1,7 @@
 # Get Element Properties
 
+<div class="image-as-lightbox"></div>
+
 ![Sample Document Properties](../../../img/graphql/element_properties.png)
 
 ### Request

diff --git a/doc/10_GraphQL/04_Query/11_Query_Samples/11_Sample_GetAsset.md b/doc/10_GraphQL/04_Query/11_Query_Samples/11_Sample_GetAsset.md
@@ -1,15 +1,24 @@
 # Get Asset By Id
 
 If you want to access an Asset directly.
+
+:::caution
+
 Note that the data will be base64 encoded and quite time-consuming to deliver.
 
+:::
+
 Deeplink: [http://pimcore-demo-basic.pim.zone/admin/login/deeplink?asset_4_image](http://pimcore-demo-basic.pim.zone/admin/login/deeplink?asset_4_image)
 
 ### Request
 
+:::info
+
 Note that for the fullpath and the base64 encoded data you can specify a thumbnail config.
 You can use the `format` argument to retrieve the values for a specific format like `webp`.
 
+:::
+
 ```
 {
   getAsset(id: 4) {

diff --git a/doc/10_GraphQL/04_Query/11_Query_Samples/12_Sample_Asset_Metadata.md b/doc/10_GraphQL/04_Query/11_Query_Samples/12_Sample_Asset_Metadata.md
@@ -1,5 +1,7 @@
 # Get Asset Metadata
 
+<div class="image-as-lightbox"></div>
+
 ![Metadata](../../../img/graphql/asset_metadata.png)
 
 Deeplink: [http://pimcore-demo-basic.pim.zone/admin/login/deeplink?asset_4_image](http://pimcore-demo-basic.pim.zone/admin/login/deeplink?asset_4_image)
@@ -82,6 +84,8 @@ Get the custom asset metadata for language `de`
 
 ## Get Asset Embedded Meta Info
 
+<div class="image-as-lightbox"></div>
+
 ![Metadata](../../../img/graphql/asset_embeddedMetaInfo.png)
 
 ### Request

diff --git a/doc/10_GraphQL/04_Query/11_Query_Samples/13_Sample_GetAssetListing.md b/doc/10_GraphQL/04_Query/11_Query_Samples/13_Sample_GetAssetListing.md
@@ -2,8 +2,12 @@
 
 ### Request
 
+:::info
+
 Note that for the fullpath and the base64 encoded data you can specify a thumbnail config.
 
+:::
+
 ```
 {
   getAssetListing {

diff --git a/doc/10_GraphQL/04_Query/11_Query_Samples/20_Sample_Manufacturer_Listing.md b/doc/10_GraphQL/04_Query/11_Query_Samples/20_Sample_Manufacturer_Listing.md
@@ -1,5 +1,7 @@
 # Get Manufacturer Listing
 
+<div class="image-as-lightbox"></div>
+
 ![Grid](../../../img/graphql/manufacturer_listing.png)
 
 ### Request

diff --git a/doc/10_GraphQL/04_Query/11_Query_Samples/21_Sample_ManyToMany_Object_Relation.md b/doc/10_GraphQL/04_Query/11_Query_Samples/21_Sample_ManyToMany_Object_Relation.md
@@ -1,5 +1,7 @@
 # Many-to-Many Object Relation
 
+<div class="image-as-lightbox"></div>
+
 ![Data](../../../img/graphql/many_to_many_object_relation.png)
 
 ### Request
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,8 +2,12 @@ @@
     ### Request
+    :::info
     Note that for the fullpath and the base64 encoded data you can specify a thumbnail config.
+    :::
     ```
     {
       getAssetListing {
@@ Expand Down @@