Feature/add doc for cards (#33)

Author: michelu89

documentation/js-sdk-guide/modules/tooling-guide/images/schema.another-aspect-model-selection.png

@@ -12,5 +12,6 @@ SPDX-License-Identifier: MPL-2.0
 * xref:internationalization.adoc[Add i18n support to a project]
 * xref:table-generation.adoc[Generating a table component]
 * xref:table-custom-column.adoc[Generating a table with custom columns]
+* xref:card-generation.adoc[Generating a card which you can add a custom content template]
 * xref:types.adoc[Generating Interfaces]
 

documentation/js-sdk-guide/modules/tooling-guide/images/schema.aspect-model-selection.png

@@ -0,0 +1,339 @@
+////
+Copyright (c) 2023 Robert Bosch Manufacturing Solutions GmbH
+
+See the AUTHORS file(s) distributed with this work for additional information regarding authorship.
+
+This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/
+SPDX-License-Identifier: MPL-2.0
+////
+
+= Card component generation
+
+== _Detailed schema overview_
+
+NOTE: Before generating a card component refer to the xref:internationalization.adoc[internationalization] file.
+
+In the example, a brand-new application was generated using the command:
+
+[source]
+ng new app demo-schematics
+
+A schematics will be generated using the following command:
+
+[source]
+ng generate [collection-name]:[schematics-name]
+
+
+For demonstration purposes, the https://github.com/eclipse-esmf/esmf-aspect-model-editor/blob/main/core/apps/ame/src/assets/aspect-models/org.esmf.examples.movement/1.0.0/Movement.ttl[Movement.ttl] Aspect Model will be used.
+Below is a detailed representation of the command-line interface steps which generates a card component using the Movement.ttl Aspect Model file by running the command.
+
+NOTE: Before running any schematics commands make sure you are in the Angular project folder where you want to generate the new component.
+
+Component generation is achieved by running either of the following commands:
+
+[source]
+ng generate @esmf/semantic-ui-schematics:card
+
+[source]
+ng g @esmf/semantic-ui-schematics:card
+
+NOTE: The Angular folder where the component generation takes place should contain another folder with the .ttl files.
+
+=== _Load pre-existing configuration file_
+After going through the wizard at least once, a config file will be
+auto-generated. The first prompt allows you to load a config file or start from scratch by loading one or multiple Aspect Model files.
+
+image::config-file-loading.png[width=100%]
+
+When you decide to create a new configuration file, you will be prompted to specify a name for your config file. This provided name will be integrated into the default naming structure for the config file.
+
+The naming structure is <config-file-name>-wizard.config.json. Here, <config-file-name> is the name that you provide when prompted.
+
+For example, if you enter myConfig when prompted for the config file name, your new config file will be named myConfig-wizard.config.json.
+
+image::schema.enter-name-for-config-file.png[width=100%]
+
+When you decide to load a pre-existing config file, the system will display the result as follows:
+
+image::schema.load-config-file.yes.png[width=100%]
+
+This will give access to the folder structure and by using a FUZZY search mechanism can provide the possibility to input the pre-existing config file. The config file will now be named based on your input _<config-file-name>_-wizard.config.json, and can be found in the root folder of the project.
+
+=== _Aspect Model selection_
+If no pre-existing config file is loaded, then there is an option to choose for one or multiple Aspect Model files from the folder structure, using the same FUZZY search mechanism.
+
+image::schema.aspect-model-selection.png[width=100%]
+
+image::schema.another-aspect-model-selection.png[width=100%]
+
+=== _Entity or specific aspect selection_
+
+An Aspect or an Entity must be chosen in order for the card to be created. This can be done in this step by choosing from a list.
+
+image::schema.aspect-or-entity-selection-card.png[width=100%]
+
+=== _Property exclusion_
+
+Some properties may be omitted. This can be done in the following step.
+
+image::schema.exclude-properties.png[width=100%]
+
+=== _Default property sorting_
+
+The card can sort based on a property. In this step the default one can be chosen.
+
+image::schema.default-sorting-property.png[width=100%]
+
+=== _Command bar_
+
+The command bar is displayed above the cards, and it holds the controls for searching and filtering the data inside the card. This is shown only if the 'yes' option is chosen in the provided input.
+
+image::command-bar-prompt.png[width=100%]
+
+If you select to have a command bar, another prompt question will appear for selecting the additional functionality attached to it.
+
+image::command-bar-additional-functionalities.png[width=100%]
+
+In the example provided, only the search functionality will be available.
+
+image::search-bar.png[width=100%]
+
+The search input is present allowing you to filter the existing data in the card if the data is handled on the client side or request new data. This can be decided in the next steps. The filtered data will be displayed after pressing the `search` button next to the search field.
+
+NOTE:  _The search input will filter the data `*ONLY*` by the existing `*STRING*` properties in the chosen Aspect Model._
+
+Once the search functionality has been enabled, the next step is to choose the default language for remote access. This language selection determines the language used in the statement when accessing the system remotely.
+
+image::choose-language.png[width=100%]
+
+=== _Data handling_
+
+After generating a component, you can pass the data from the parent to the child components and also the other way around. There is a prompt present which determines if the data should be handled on the client side or remote via an API call.
+
+image::remote-data-handling-prompt.png[width=100%]
+
+This means that any time you request data, an API endpoint will be called and the result coming from that endpoint will populate the card with a fresh set of data.
+
+=== _Component path_
+
+Once all the prompts are answered, a card will be generated based on the selected options. The default path of the newly generated component is `*_src/app/shared/components/<component-name>_*`.
+
+[source]
+----
+shared
+└─── components
+        └─── <component-name>
+        │   │   <component-name>.component.html
+        │   │   <component-name>.component.scss
+        │   │   <component-name>.component.ts
+        │   │   <component-name>-command-bar.component.ts
+        │   │   <component-name>-command-bar.component.html
+        │   │   <component-name>-chip-list.component.ts
+        │   │   <component-name>-chip-list.component.scss
+        │   │   <component-name>-chip-list.component.html
+        │   │   <component-name>.module.ts
+        │   │   <component-name>.service.ts
+        │   │   <component-name>-filter.service.ts
+----
+
+=== _Persistent custom service_
+
+By default, as seen above, a _<component-name>.service.ts_ file is auto-generated. This file is `*OVERRIDDEN*` each time a component is re-generated.
+
+Which is why we introduced another prompt question for a custom service generation which is `_persistent_` if the component is re-generated.
+
+image::custom-service.png[width=100%]
+
+If this option is selected, another file will show up in the folder structure.
+
+[source]
+----
+shared
+└───components
+        └─── <component-name>
+        │   │   custom-<component-name>.service.ts
+        │   │   <component-name>.component.html
+        │   │   <component-name>.component.scss
+        │   │   <component-name>.component.ts
+        │   │   <component-name>-command-bar.component.ts
+        │   │   <component-name>-command-bar.component.html
+        │   │   <component-name>-chip-list.component.ts
+        │   │   <component-name>-chip-list.component.scss
+        │   │   <component-name>-chip-list.component.html
+        │   │   <component-name>.module.ts
+        │   │   <component-name>.service.ts
+        │   │   <component-name>-filter.service.ts
+----
+
+This file will be overridden `_ONLY_` if you choose to do so by providing the `--overwrite` option when starting the generation process.
+
+=== _Multiple version support_
+
+An Aspect Model can have multiple versions. If this is the case, and you want to generate multiple components having different version, this can be done when this prompt question shows up:
+
+image::multi-version-support.png[width=100%]
+
+The folder structure will then change accordingly.
+
+[source]
+----
+shared
+└───components
+        └─── <component-version-0>
+        │    └─── <component-name>
+        │    │   │   custom-<component-name>.service.ts
+        │    │   │   <component-name>.component.html
+        │    │   │   <component-name>.component.scss
+        │    │   │   <component-name>.component.ts
+        │    │   │   <component-name>-command-bar.component.ts
+        │    │   │   <component-name>-command-bar.component.html
+        │    │   │   <component-name>-chip-list.component.ts
+        │    │   │   <component-name>-chip-list.component.scss
+        │    │   │   <component-name>-chip-list.component.html
+        │    │   │   <component-name>.module.ts
+        │    │   │   <component-name>.service.ts
+        │    │   │   <component-name>-filter.service.ts
+        └─── <component-version-1>
+        │    └─── <component-name>
+        │    │   │   custom-<component-name>.service.ts
+        │    │   │   <component-name>.component.html
+        │    │   │   <component-name>.component.scss
+        │    │   │   <component-name>.component.ts
+        │    │   │   <component-name>-command-bar.component.ts
+        │    │   │   <component-name>-command-bar.component.html
+        │    │   │   <component-name>-chip-list.component.ts
+        │    │   │   <component-name>-chip-list.component.scss
+        │    │   │   <component-name>-chip-list.component.html
+        │    │   │   <component-name>.module.ts
+        │    │   │   <component-name>.service.ts
+        │    │   │   <component-name>-filter.service.ts
+----
+
+=== _Material theme(Indigo pink)_
+
+User can add to angular.json Indigo pink material theme. These action will appear in the actions column of the card. In the following prompt you can choose to add the Indigo pink material theme.
+
+image::material-theme-prompt.png[width=100%]
+
+In the generated angular.json card if user selected yes we can observe the change in styles array.
+
+image::angular-json-example.png[width=100%]
+
+=== _Set view encapsulation strategy for the generated card component_
+
+User can set the View Encapsulation strategy by default the ViewEncapsulation will be set to None on the generated card component. In the following prompt you can choose to add another View Encapsulation value.
+
+image::view-encapsulation-prompt.png[width=100%]
+
+=== _Flags for generating the card_
+
+By using
+
+[source]
+ng generate @esmf/semantic-ui-schematics:card --help
+
+or
+
+[source]
+ng g @esmf/semantic-ui-schematics:card --help
+
+you can get access to all the options encapsulated in the schema.json file. Each field has a description for a better understanding of it and how to use it.
+
+|===
+|Flag |Description |Default |Type
+|_--add-command-bar_
+|Flag to add the command bar
+|false
+|boolean
+|_--aspect-model-urn-to-load_
+|Specify the Aspect Model for card generation
+|''
+|string
+|_--change-detection_
+|Change detection strategy for the generated angular component
+|'default'
+|enum
+|_--custom-remote-service_
+|Generate _custom-<component-name>.service.ts_ file
+which is persistent and not overwritable in case the
+component is regenerated.
+
+This can be changed using the `_--overwrite_` flag
+Conditions: this flag appears only if the data is
+handled remotely. This is specified using the flag
+`_--enable-remote-data-handling_`
+|false
+|boolean
+|_--enable-remote-data-handling_
+|Flag used to choose how to handle the data, pagination, sorting or filtering.
+
+(client-side or remote)
+|false
+|boolean
+|_--enable-version-support_
+|Multiple versions support for different version of an
+
+Aspect Model
+|false
+|boolean
+|_--json-access-path_
+|Enter the access path in the JSON payload e.g. position
+|''
+|string
+|_--overwrite_
+|Overwrite existing files
+|true
+|boolean
+|_--selected-model-element-urn_
+|Choose a specific Entity or Aspect to show as card
+|''
+|string
+|_--ttl_
+|Path for the Aspect Model files
+|[]
+|string[]
+|===
+
+## Customize the date format
+
+Various date formats can be configured e.g. for the date filter and the corresponding chip label.
+
+Set the desired default format for dates in the app.component.ts:
+
+    constructor(@Inject(MAT_DATE_FORMATS) private dateFormats: MatDateFormats) {
+        this.dateFormats.display.dateInput = 'DD.MMM.YYYY';
+        this.dateFormats.display.monthYearLabel = 'MMM YYYY';
+        this.dateFormats.display.dateA11yLabel = 'LL';
+        this.dateFormats.display.monthYearA11yLabel = 'MMMM YYYY';
+    }
+
+Make sure moment.js and dateAdaptor are correctly installed
+
+## Set default language
+
+In app.component.ts, it is required to set the default language:
+
+    constructor(lang: TranslateService) {
+        lang.use(lang.defaultLang);
+    }
+
+---
+
+## Add custom content template
+
+In the app.component.ts you can determine the content of the cards yourself:
+
+    <esmf-ui-cards [data]="data">
+      <ng-template #cardTemplate let-data let-element="cardValues" let-getElementValue="getElementValue" let-translateService="translateService">
+        <div class="data-card-element" *ngFor="let elem of element">
+          <b>{{ translateService.instant(elem + '.preferredName') }}</b>: {{ getElementValue(data, elem) }}
+        </div>
+      </ng-template>
+    </esmf-ui-cards>
+
+The ng-tempalte values can be used from the child componente or can be determined by the user.
+
+---
+
+