Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added Query Builder Control and Metadata Picker documentation #109

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
57 changes: 57 additions & 0 deletions src/en/developer-guide/applications/controls/metadatapicker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
Author: Adel Šabić
---

# Metadata picker
This control is used as a way to fetch metadata and give user ability to choose values from its autocomplete control. It gives ability to choose entity, attribute, relationship or language depending on control setup.
## Visual Example
![Metadata Picker Screenshot](/.attachments/applications/Controls/metadatapicker.png)

# Structure
## Data Access Layer (DAL)
### Metadata repository
Job of this class is to fetch metadata for multiple entites or specific entity. It has two methods:
- ```typescript
/**
* Gets all entites contained in environment
* @returns object with LogicalName, DisplayName and MetadataId
*/
public GetEntities()
```
- ```typescript
/**
* Gets the entity metadata for the specified entity.
* @param entityName - The logical name of the entity.
* @returns object with LogicalName, DisplayName, MetadataId, Attributes and Relationships
*/
public GetEntity(entityName:string)
```

## Logic

``json`` property has very nice role in Metadata picker. You can provide it with array of entity metadata objects as ``IEntityMetadata[]`` and it will enable Metadata picker to work with it. In that case it will not need to fetch metadata. Only if metadata is missing, it will fetch it and populate back ``json`` property with newly fetched data.

### MetadataMapper
It's job is to map metadata to objects acceptable by Autocomplete UI component.

<!-- TODO: ## Presentation (UI) -->

# Control manifest parameters
<!-- Make window bigger for table to be able to fit and be formated correctly -->
| Name | Type | Usage | Required |
| ----------------------------------------- | ----------------------------- | ----- | -------- |
| bindingField | SingleLine.Text/Whole.None | bound | true |
| entityLogicalName | SingleLine.Text | bound | false |
| applyAppmoduleFilter | Enum | input | false |
| applyEnvironmentEnabledLanguagesFilter | Enum | input | false |
| json | Multiple | input | false |
| mode | Enum | input | false |
| enableBorder | Enum | input | false |



# Dependencies
### NPM
- @talxis/react-components: 1.2305.3 - Used UI components
- @types/xrm: ^9.0.73 - Used for usage of certain Xrm methods
- remove-accents: ^0.4.4 - Used for removing accents from strings
88 changes: 88 additions & 0 deletions src/en/developer-guide/applications/controls/querybuilder.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
---
Author: Adel Šabić
---

# Query Builder
This control is used to compose FetchXML query.
## Visual Example
![Query Builder V1 Screenshot](/.attachments/applications/Controls/querybuilder.png)

# Structure
## Data Access Layer (DAL)
### Entity metadata
For entity metadata fetching [TALXIS Metadata Picker](https://dev.azure.com/thenetworg/_git/INT0015?path=/src/controls/MetadataPicker) is used.

``json`` parameter of Metadata Picker is link through which Metadata Picker and QueryBuilder are communicating. Metadata Picker is fulfilling that parameter with entity metadata object array every time it fetches something new, but it is also capable of reading it. So if metadata already exists inside of the JSON object, it will not fetch it twice.

Query Builder is taking this entity metadata array object and works with it. So there is no need to implement entity metadata fetch inside of the Query Builder. All work is being done by Metadata Picker.

### Option sets metadata
When control is being used in TALXIS Portal, there is no need for optionset fetching. TALXIS Portal is handling optionset fetching when rendering optionset control.

Control is not currently ready for PowerApps use, but there is logic implemented which would fetch optionsets. This is needed in PowerApps because of when using nested optionset control in PowerApps, we need to provide options to it. PowerApps optionset control is not handling optionset fetching like TALXIS Portal does.

## Logic
### Custom Value Editor
Custom value editor is used for values representation, edit and update. Depending on the portal that Query Builder is being rendered on, it uses either TALXIS Portal or PowerApps native controls (DateTime, TextField, MultiselectOptionset etc.). It job is to bind correct control based on chosen attribute and operator type.

### Entity Metadata Mapper
Job of entity metadata mapper is to compose object that is acceptable by React query builder component from provided entity metadata.

### FetchXML
FetchXML class is handling composition and output of FetchXML. It is used through out QueryConverter logic to compose correct FetchXML from object that is passed from React Query Builder.

### Metadata Picker
It handles binding and event handling of TALXIS Metadata Picker control

### Operators
Class that handles supported condition operators. It translates and retrieves correct set of operators for specific attribute type.

### Query Builder
This is most important class. This is where all of the classes meet together and Query Builder handles all of the event events, composes props for UI, renders components, takes care of value state.

### Query Converter
This class handles conversion from FetchXML to React Query Builder object and viceversa.


## Presentation (UI)
### Query Builder
Query builder component utilizes already existing UI from @react/querybuilder. It also contains the logic for rendering all custom components used in query builder. Few things custom things worth mentioning:
- #### Custom components
``controlElements`` property of React Query Builder allows us to overwrite all components used inside of the Query Builder. Therefor, many of controls have been overwritten either to be able to compose linked entities or to use Fluent UI controls.
- #### Context
``context`` property allows us to pass any object to childer components in Query tree. So there we are sending object with values so it can be read in controlsElements when that are supposed to be rendered.
- #### Control Class Names
``controlClassnames`` is property used to overwrite default React Query Builder styles.

It also contains seprate folders and files for used enums, interfaces and styles.

### Metadata Picker
Wrapper div for metadata picker. It triggers binding logic upon div render.

### Link Entity
Custom component for link-entity composition. It renders TALXIS Metadata Picker as relationship selector, handles value changes and metadata loading events and renders nested query builder component upon props composition.

### Custom Value Editor
Wrapper div for Custom Value Editor. It triggers binding logic upon div render.

# Control manifest parameters
<!-- Make window bigger for table to be able to fit and be formated correctly -->
| Name | Type | Usage | Required | Description |
| ----------------- | --------------------------------------------- | ----- | -------- | --------------------------------------------------------- |
| value | SingleLine.Text/SingleLine.TextArea/Multiple | bound | true | Stores Fetch XML |
| queryEntity | SingleLine.Text | bound | false | Custom entity name for which fetchXML will be composed for |
| showEntityPicker | SingleLine.Text (true/false) | input | false | Give user ability to change entity name |


# Dependencies
### Nested PCFs
- TALXIS.PCF.MetadataPicker
### NPM
- @fluentui/react: ^8.110.11 - It uses Fluent UI for custom controls (selectors, operators, buttons, icons etc).
- react-querybuilder: ^6.5.1 - Open source react component used for UI representation
- fast-xml-parser: ^4.2.7 - Used for parsing FetchXML so object for react-querybuilder could be composed.
- xmlbuilder2: ^3.1.1 - Used for FetchXML composition
- uuid: ^9.0.0 - Used for generating unique IDs for rows and groups inside of the querybuilder.
- Declared but unused dependecies: (More effort needs to be put in to figure out a way how these import will not make production build bigger than 5MB)
- @react-querybuilder/dnd: ^6.5.1
- @react-querybuilder/fluent: ^6.5.1