https://github.com/solidlabresearch/solid-sfef-cli
Solid Frontend Forms CLI
https://github.com/solidlabresearch/solid-sfef-cli
Last synced: 11 months ago
JSON representation
Solid Frontend Forms CLI
- Host: GitHub
- URL: https://github.com/solidlabresearch/solid-sfef-cli
- Owner: SolidLabResearch
- License: mit
- Created: 2024-01-23T09:41:08.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-02T18:30:41.000Z (about 2 years ago)
- Last Synced: 2025-01-17T07:09:34.258Z (about 1 year ago)
- Language: JavaScript
- Size: 649 KB
- Stars: 1
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Solid FE Form CLI
- [Introduction](#introduction)
- [CLI commands](#commands)
- [Install](#install)
- [Usage and examples](#usage)
- [Help](#help)
- [List shapes available](#usage-list-shapes)
- [Set custom CSS styles](#usage-set-custom-styles)
- [Create form file and dependencies](#usage-create)
- [Uninstall](#uninstall)
- [Changelog](#changelog)
The Solid Front End Form CLI is meant to help create forms on Vue/Angular frameworks from SHACL (Shapes Constraint Language) files.
The [```create```](#usage-create) command recreates a `````` using the rules from a SHACL file on the framework selected.
The available frameworks are **Vue3** and **Angular2**.
All outputted form components are created without styles.
For both frameworks, all [HTML form elements](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements) have been implemented. For each form element, all possible attributes and values have been taken into consideration.
But, only the `````` element is considered in the mapping as of now.
Please, check ```BASIC_TYPE_MAP``` in ```constants.ts``` for a mapping between ```sh:datatype``` and basic components and its types.
See [Changelog](#changelog) for the current status of the CLI.
```mermaid
---
title: The 'create' diagram flow from .ttl shape to the FE 'form' component
---
flowchart LR
A(SHACL\n.ttl):::bold
B(JSONLD)
C(custom\nJSON)
D(form\ncomponent):::bold
E(BasicInput\nBasicFieldset\nBasicButton\nBasicTextarea\nBasicSelect)
A --> B
B --> C
C --> D
subgraph DE[FE framework]
D <-. dependecies .-> E
end
classDef bold stroke-width:3px
```
- ```sfef set-custom-css``` :
Set up custom CSS classes to be used in the FE form component.
- ```sfef create -f -s [-c]``` :
Creates the form (following SHACL shape) and required dependencies according to the selected framework.
- ```sfef list-shapes``` :
List of available shapes (SHACL .ttl files).
- Solid-sfef-cli is a development CLI tool, it is recommended to install it using ```--global``` parameter. The following commands can be used:
```bash
npm install @solidlab/solid-sfef-cli --global
```
or
```bash
npm i @solidlab/solid-sfef-cli -g
```
- It could also be installed locally as a dev dependency using ```--save-dev``` parameter. The following commands can be used:
```bash
npm install @solidlab/solid-sfef-cli --save-dev
```
or
```bash
npm i @solidlab/solid-sfef-cli -D
```
**The current section bash commands are under the assumption that the installation was done globally**.
If the installation was done **locally** bash commands should be adapted accordingly.
e.g.
instead of
```bash
sfef list-shapes
```
use
```bash
node . list-shapes
```
Use the help command to print out the commands and parameters available in the CLI tool.
```bash
sfef help
```
Define some custom CSS classes to be used when creating the form.
```bash
sfef set-custom-css
```
The command asks for CSS classes on:
- `````` element
- ```
``` wrapper around input and label
- `````` element
- `````` element which contains additional information bound to the label (```sh:description```)
- `````` element
The custom classes are stored in the project root under filename **form-custom-classes.json**.
Example of custom CSS classes JSON structure:
```json
[
{
"element":"form",
"classes":["css-custom__form"]
}, {
"element":"input-wrapper",
"classes":["css-custom__wrapper"]
}, {
"element":"input-label",
"classes":["css-custom__label", "css-custom__label--bold"]
}, {
"element":"input-additional-info",
"classes":["css-custom__info"]
}, {
"element":"input-element",
"classes":["css-custom__input", "css-custom__input--required"]
}
]
```
### Create form file and dependencies
Creates the form component according to the frame selected (vue or angular) and the shape (.ttl file).
The ```create``` command has 2 required parameters (```--framework``` and ```--shape```) and 1 optional parameter (```--css```).
```bash
sfef create --framework --shape
```
or
```bash
sfef create -f -s
```
With the optional parameter ```--css```, the component file will include the css classes available in **form-custom-classes.json**.
This JSON file needs to be created using the [```set-custom-css```](#usage-set-custom-styles) command.
```bash
sfef create --framework --shape --css
```
or
```bash
sfef create -f -s --c
```
The shape could be an **absolute path** or a **file name (relative path)**.
The relative path refers to the solid-sfef-cli package.
Check available .ttl file names using ```sfef list-shapes``` command.
examples of valid **fileName** values:
- ```'adresregister-SHACL'```
a .ttl file name from ```'.assets/shacl'``` folder in the cli package.
- ```'/Users/myname/Documents/GIT/myProject/.shapes/my-project-shape.ttl'```
an absolute path.
#### Vue example
```bash
sfef create -f vue -s example
```
Executing above command will create the ```FormExample.vue``` file in ```src/vue``` folder along with all depency components (```BasicInput.vue``` and ```BasicOption.vue```).
The ```example.ttl``` includes various input types: ```text```, ```date```, ```email```, ```checkbox``` and ```number```.
Being ```'Given name'```, ```'Family name'```, ```'Street address'```, ```'house number'``` and ```'Postal code'``` required fields.
The ```'Genre'``` field uses a `````` to restrict the options allowed.
Finally ```'Postal code'``` uses a ```regex``` pattern.
```html
// FormExample.vue
PersonShape
AddressShape
import { defineComponent } from "vue"
import BasicInput from "./components/BasicInput.vue"
export default defineComponent({
name: "FormExample",
components: {
BasicInput,
},
})
```
Which will look like:
and with a some minimal styling:
when all fields are filled properly:
#### Angular example
```bash
sfef create -f angular -s another-example -c
```
Executing above command will create the ```FormAnotherExample.component.html``` and ```FormAnotherExample.component.ts``` file in ```src/app/FormAnotherExample``` folder along with ```BasicInput``` depency component.
The ```another-example.ttl``` shape includes ```text``` and ```email``` input types.
Being ```'Given name'```, ```'Family name'```, ```'Country'```, ```'City'```, ```'Street Line'```, ```'Postal code'``` and ```'Organization name'``` required fields.
As the optional parameter ```-c``` (```--css```) is also present, thus the css classes from ```form-custom-classes.json``` are applied to corresponding elements.
```json
[
{"element":"form","classes":["css__form"]},
{"element":"input-wrapper","classes":["css__wrapper"]},
{"element":"input-label","classes":["css__label"]},
{"element":"input-additional-info","classes":["css__xtra-info"]},
{"element":"input-element","classes":["css__input"]}
]
```
Resulting in following ```html``` and ```ts``` files:
```html
// FormAnotherExample.component.html
Contact
Address
Organization
```
and
```ts
// FormAnotherExample.component.ts
import { Component, ViewEncapsulation } from '@angular/core';
import { BasicInputComponent } from "../components/BasicInput/BasicInput.component"
@Component({
selector: "app-form-another-example",
standalone: true,
imports: [
BasicInputComponent,
],
templateUrl: './FormAnotherExample.component.html',
encapsulation: ViewEncapsulation.None
})
export class FormAnotherExample {
}
```
Which will look like:
and with a some minimal styling:
when all fields are filled properly:
List the actual available shapes inside the solid-sfef-cli package.
```bash
sfef list-shapes
```
A part from the listed shapes, the ```create``` command also allows to use global path for any shape file.
Example of package's shapes folder path on OSX: ```'/Users/myname/node_modules/@solidlab/solid-sfef-cli/.assets/shacl/'```
To uninstall, simply run:
- for global installation:
```bash
npm uninstall @solidlab/solid-sfef-cli --global
```
or
```bash
npm rm @solidlab/solid-sfef-cli -g
```
- for development installation:
```bash
npm uninstall @solidlab/solid-sfef-cli --save-dev
```
or
```bash
npm rm @solidlab/solid-sfef-cli -D
```
### version 0.1.0 - January 2024
#### Limitation
The ```create``` functionality is adapted to a small amount of shape scenarios.
See the .ttl files in the ```./assets/shacl/``` folder for some examples.
##### ```BasicInput``` component
As a result of this scope scenarios, only the HTML `````` element is considered.
See ```BASIC_TYPE_MAP``` in ```constants.ts``` for mapping between shape (```sh:property```) and the corresponding Basic element (as well as type value).
e.g.
```js
...
['email', ['BasicInput', 'email']],
['string', ['BasicInput', 'text']],
['lang String', ['BasicInput', 'text']],
['boolean', ['BasicInput', 'checkbox']],
['integer', ['BasicInput', 'number']],
...
```
##### ``````
Only a small amount of available attributes are taken in account: ```id```, ```name```, ```form```, ```type```, ```pattern```, ```required``` and ```list```.
And for the ```type``` attribute only some values are considered: ```text```, ```number```, ```checkbox```, ```email```, ```url```, ```date```, ```time```, ```datetime-local``` and ```month```.
##### ``````
Related to the `````` element, the value is coming from ```sh:name``` (or ```sh:path```).
On top, an option to add additional information to the label is available. The value is coming from ```sh:description``` and set in a `````` element.
Then, it is up to developer to style it properly (e.g. second line, :hover, floating,...).
#### Ready to grow
Anyway, in both frameworks, the basic HTML forms elements has been created, and are ready to be implemented.
The ``````, ``````, ``````, `````` and `````` components are created following expected [HTML markup](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements), with all the possible attributes and values.
So, the package is ready to be extended for any particular shapes scenarios, or simply be custom adapted.