NG-Exploder

The UI builder and controls logic

NG-Expoder is an angular library and based on - primefaces- controls and it help you to create forms and page elements like (tables - chips - contexture) using json object and you can create the following types:

• textarea
• textField
• number
• checkbox
• switch
• autocomplete
• dropdown
• multipleSelect
• uploader
• rating
• radio
• table
• button
• chips
• map

Features

• You did not need to wite html codes
• You did not need to re-write css or scss once create global style it will be applied on all controls.
• You can create a complexity forms easily
• you can create and manage logic easily
• it's support translations (arabic and english till now)
• flexible to extend and editable

Installation

NG-Exploder requires Angular v11 to run.

Install the dependencies and devDependencies and start the server.

1cd [your project]
2npm install primeng-lts --save
3npm install primeicons --save

Install ng-exploder.

1npm i ng-exploder

Now you should import ( ExploderModule ) in AppModule

1@NgModule({
2  declarations: [
3    ......
4  ],
5  imports: [
6    BrowserModule,
7    BrowserAnimationsModule,
8    ReactiveFormsModule,
9    ExploderModule
10    .....
11  ],
12  providers: [],
13  bootstrap: [AppComponent]
14})

Optional:

• you can create custom expolder.theme. (*css/scss*) for set customize controls

Plugins

NG-Exploder is currently extended with the following plugins. Instructions on how to use them in your own application are linked below.

Plugin	README
Angular	[https://angular.io/][PlDb]
Primefaces	[https://www.primefaces.org/primeng-v11-lts/#/setup][PlDb]
Bootstrap	[https://getbootstrap.com/][PlGd]

Development

Want to continue? Great!

Ng-Exploder uses primefaces for fast developing.

after run angualr project.

1ng serve

Create new class and extends Exploder from 'ng-exploder' but it's optional to use inheritance and OOP concepts but you can create main component directly and strat implement forms also . Let's start to create Commen class and set it as base class

1export class Common extends Exploder {
2 .....
3 
4}

In the above class you can inject all services that will use it in component class and following example :

1export class Common extends Exploder {
2  public expService: ExploderService;
3  public httpApiService: HttpApiService;
4  public route: ActivatedRoute;
5  ........
6 constructor(public injector: Injector) {
7    super();
8    this.expService = this.injector.get(ExploderService);
9    this.httpApiService = this.injector.get(HttpApiService);
10    this.route = this.injector.get(ActivatedRoute);
11    .....
12    }
13}

then you can implement all methods in abstract class and the important method is (getByType). it used for search about control [will use it next time and know how?].

Component Class

In our case, We will use AppComponent.ts as main component to bind and display our page design and that is main task so i will extends from Exploder.class.ts and impement setConfig to create json configuration in it [Schema].

Notes:

• I create Form using Angular reactiveForms to push all controls on it and should it contain FormGroup at least one.
• I create Config Variable as ConfigType to set a json config in it.

1export class Common extends Exploder {
2  public config: Config;
3  public mainForm: FormGroup;
4  ........
5 constructor(public injector: Injector) {
6    ....
7    this.mainForm = new FormGroup({
8      pageControls: new FormGroup({}),
9    });
10    .....
11    }
12}

And then open AppComponent.html and set the following code :

1<div [formGroup]="mainForm">
2......
3   <exp-head [config]="config" FormGroupName="pageControls"
4                  [Lang]=".." ></exp-head>
5.....
6</div>

• You should pass root Form Group the FormGroupName as you created in the form as string and formGroup as parent Form. then config as json Object. -- and config should defined from Config Type
• the lang Input is optional.

Config Type Properties

Name	Type	Default	Description
exp	ExpTypes	should select from this types [ 'builder' , 'resource']	you should use ExpTypes enum to select type BUILDER or RESOURCE
components	ExpComponent[]	[]	describe In the table below

Let's now start build JSON Object or Schema that responsible display UI and logic.

the below example describe how you can create schema:

1export class Common extends Exploder {
2  public config: Config;
3  public mainForm: FormGroup;
4  ........
5 constructor(public injector: Injector) {
6    ....
7    this.mainForm = new FormGroup({
8      pageControls: new FormGroup({}),
9    });
10    this.setConfig();
11    .....
12    }
13    setConfig(): any {
14    this.config = {
15      exp: ExpTypes.BUILDER,
16      components: [
17        new ExpComponent({
18          key: 'campaignDetails',
19          columns: [
20            new ExpColumn({
21              width: 12,
22              type: 'radio',
23              key: 'testRadioKey',
24              label: 'Test',
25              options: [
26                {id: 1, nameEn: 'test', nameAr: 'اختبار'}
27              ],
28              properties: {
29                labelEn: 'nameEn',
30                labelAr: 'nameAr',
31                optionValue: 'id',
32                onChange: () => {
33                ....
34                },
35                styleClass: 'p-radio-button-custom',
36              },
37              validate: {required: true}
38            }),
39            new ExpColumn({
40              width: 6,
41              type: 'textField',
42              key: 'testTextFieldKey',
43              label: 'Text Field Key',
44              placeholder: 'Text Field Key',
45              validate: {
46                required: true,
47              }
48            }),
49            new ExpColumn({
50              width: 6,
51              type: 'uploader',
52              key: 'file',
53           // hidden: true,
54              label: 'file',
55              properties: {
56                previewWidth: 50,
57                showCancelButton: true,
58                showUploadButton: false,
59                path: 'API for download file in view mode after upload it',
60                accept: 'image/*,application/pdf,.pdf',
61                maxFileSize: 5000000,
62                mode: 'basic',
63                onPush: true,
64              }
65            }),
66            new ExpColumn({
67              width: 6,
68              type: 'dropdown',
69              key: '...',
70              label: ...,
71              placeholder: ....,
72              options: [
73                {id: 1, nameEn: 'Regular', nameAr: 'منظمة'},
74              ],
75              properties: {
76                labelEn: 'id',
77                labelAr: 'id',
78                optionValue: 'id',
79                styleClass: 'p-dropdown-custom',
80              },
81              validate: {required: true}
82            })
83          ],
84        }),
85        new ExpComponent({
86          key: 'locationDetails',
87          columns: [
88            new ExpColumn({
89              width: 6,
90              type: 'dropdown',
91              key: 'zone',
92              options: [
93                {id: 1, nameEn: 'xxx', nameAr: 'xxx'},
94              ],
95              label:  'ZONE',
96              placeholder: 'ZONE',
97              properties: {
98                labelEn: 'nameEn',
99                labelAr: 'nameAr',
100                styleClass: 'p-dropdown-custom',
101              },
102              validate: {required: true}
103            })
104          ]
105        }),
106        new ExpComponent({
107          key: 'campaignTableDetails',
108          columns: [
109            new ExpColumn({
110              width: 12,
111              type: 'button',
112              key: 'addItem',
113              properties: {
114                onClick: () => {
115....
116},
117                btnLabel:  'ADD',
118                class: 'p-d-inline-flex p-jc-end text-right'
119              }
120            }),
121            new ExpColumn({
122              width: 10,
123              type: 'button',
124              key: 'cancelItem',
125              hidden: true,
126              properties: {
127                onClick: () => {
128                  ....
129                },
130                btnLabel:  'CANCEL',
131                class: 'p-d-inline-flex p-jc-end text-right'
132              }
133            }),
134            new ExpColumn({
135              width: 2,
136              type: 'button',
137              key: 'saveItem',
138              hidden: true,
139              properties: {
140                onClick: () => {
141                 ....
142                },
143                btnLabel:  'SAVE',
144                class: 'p-d-inline-flex p-jc-end text-right'
145              }
146            }),
147            new ExpColumn({
148              width: 12,
149              type: 'table',
150              key: 'locationTable',
151              value: [],
152              options: [{
153                zone: 'zone',
154                region: 'region'
155              }],
156              validate: {required: true},
157              properties: {
158                cols: [
159                  {
160                    name: 'ZONE',
161                    field: 'zone',
162                    isObject: true,
163                    labelEn: 'nameEn',
164                    labelAr: 'nameAr',
165                  }
166                  {name: 'ACTIONS', actions: ['delete', 'edit']}
167                ],
168                transPath: this.messageTranslationPrefix,
169                actions: {
170                  onClick: (control, event) => {
171                    ....
172                  }
173                }
174              }
175            }),
176          ],
177        })
178      ]
179    };
180  }
181
182}

As per the above code the configuration assume that we have more than onle component and every component have one or more controle.

• every compoent should have unique key componentKey and you other optional properties :

Name	Type	Default	Description
key	string	auto generated [if is empty]	you should add unique key and it will create fromGroup using this key in parent form and push all the controls in it.
label	string	null	if you set it will displayed as section title
width	number	6	it's grid system class using bootsrap system from 1 - 12
properties	any	null	any additional properties
order	number	null	if you need to re-order compenetes based logic so you can set it as any number [0]
components	ExpComponent[]	[]	if you need to to set child components.
columns	ExpColumn[]	should have one control at least	you can check the below column properties table.
hidden	boolean	false	if you need to hide all component contols set it true

After know how to create component. let's know what is the mandatory properties and optional in column? and will explained in the following table:

Name	Type	Default	Description
type	string	null	this field is required so you should select type from the following types textarea , textField , number , date , checkbox , switch , autocomplete , dropdown , multipleSelect , uploader , rating , radio , multiSelect , table , button , chips , map
width	number	6	it's grid system class using bootsrap system from 1 - 12
label	string	null	if you set it will displayed as control title
placeholder	string	null	if you set it will displayed as placeholder inside control
key	string	auto generated [if is empty]	you should add unique key and it will create fromControl using this key in parent formGroup and push all the controls in it.
disabled	boolean	false	if you need to diable control set it true
hidden	boolean	false	if you need to hide all control set it true
options	ExpLookup[] or any[]	false	for dropdown option list

License

MIT