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.

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

Install ng-exploder.

npm i ng-exploder

Now you should import ( ExploderModule ) in AppModule

@NgModule({
  declarations: [
    ......
  ],
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    ReactiveFormsModule,
    ExploderModule
    .....
  ],
  providers: [],
  bootstrap: [AppComponent]
})

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.

ng 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

export class Common extends Exploder {
 .....
 
}

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

export class Common extends Exploder {
  public expService: ExploderService;
  public httpApiService: HttpApiService;
  public route: ActivatedRoute;
  ........
 constructor(public injector: Injector) {
    super();
    this.expService = this.injector.get(ExploderService);
    this.httpApiService = this.injector.get(HttpApiService);
    this.route = this.injector.get(ActivatedRoute);
    .....
    }
}

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.

export class Common extends Exploder {
  public config: Config;
  public mainForm: FormGroup;
  ........
 constructor(public injector: Injector) {
    ....
    this.mainForm = new FormGroup({
      pageControls: new FormGroup({}),
    });
    .....
    }
}

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

<div [formGroup]="mainForm">
......
   <exp-head [config]="config" FormGroupName="pageControls"
                  [Lang]=".." ></exp-head>
.....
</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:

export class Common extends Exploder {
  public config: Config;
  public mainForm: FormGroup;
  ........
 constructor(public injector: Injector) {
    ....
    this.mainForm = new FormGroup({
      pageControls: new FormGroup({}),
    });
    this.setConfig();
    .....
    }
    setConfig(): any {
    this.config = {
      exp: ExpTypes.BUILDER,
      components: [
        new ExpComponent({
          key: 'campaignDetails',
          columns: [
            new ExpColumn({
              width: 12,
              type: 'radio',
              key: 'testRadioKey',
              label: 'Test',
              options: [
                {id: 1, nameEn: 'test', nameAr: 'اختبار'}
              ],
              properties: {
                labelEn: 'nameEn',
                labelAr: 'nameAr',
                optionValue: 'id',
                onChange: () => {
                ....
                },
                styleClass: 'p-radio-button-custom',
              },
              validate: {required: true}
            }),
            new ExpColumn({
              width: 6,
              type: 'textField',
              key: 'testTextFieldKey',
              label: 'Text Field Key',
              placeholder: 'Text Field Key',
              validate: {
                required: true,
              }
            }),
            new ExpColumn({
              width: 6,
              type: 'uploader',
              key: 'file',
           // hidden: true,
              label: 'file',
              properties: {
                previewWidth: 50,
                showCancelButton: true,
                showUploadButton: false,
                path: 'API for download file in view mode after upload it',
                accept: 'image/*,application/pdf,.pdf',
                maxFileSize: 5000000,
                mode: 'basic',
                onPush: true,
              }
            }),
            new ExpColumn({
              width: 6,
              type: 'dropdown',
              key: '...',
              label: ...,
              placeholder: ....,
              options: [
                {id: 1, nameEn: 'Regular', nameAr: 'منظمة'},
              ],
              properties: {
                labelEn: 'id',
                labelAr: 'id',
                optionValue: 'id',
                styleClass: 'p-dropdown-custom',
              },
              validate: {required: true}
            })
          ],
        }),
        new ExpComponent({
          key: 'locationDetails',
          columns: [
            new ExpColumn({
              width: 6,
              type: 'dropdown',
              key: 'zone',
              options: [
                {id: 1, nameEn: 'xxx', nameAr: 'xxx'},
              ],
              label:  'ZONE',
              placeholder: 'ZONE',
              properties: {
                labelEn: 'nameEn',
                labelAr: 'nameAr',
                styleClass: 'p-dropdown-custom',
              },
              validate: {required: true}
            })
          ]
        }),
        new ExpComponent({
          key: 'campaignTableDetails',
          columns: [
            new ExpColumn({
              width: 12,
              type: 'button',
              key: 'addItem',
              properties: {
                onClick: () => {
....
},
                btnLabel:  'ADD',
                class: 'p-d-inline-flex p-jc-end text-right'
              }
            }),
            new ExpColumn({
              width: 10,
              type: 'button',
              key: 'cancelItem',
              hidden: true,
              properties: {
                onClick: () => {
                  ....
                },
                btnLabel:  'CANCEL',
                class: 'p-d-inline-flex p-jc-end text-right'
              }
            }),
            new ExpColumn({
              width: 2,
              type: 'button',
              key: 'saveItem',
              hidden: true,
              properties: {
                onClick: () => {
                 ....
                },
                btnLabel:  'SAVE',
                class: 'p-d-inline-flex p-jc-end text-right'
              }
            }),
            new ExpColumn({
              width: 12,
              type: 'table',
              key: 'locationTable',
              value: [],
              options: [{
                zone: 'zone',
                region: 'region'
              }],
              validate: {required: true},
              properties: {
                cols: [
                  {
                    name: 'ZONE',
                    field: 'zone',
                    isObject: true,
                    labelEn: 'nameEn',
                    labelAr: 'nameAr',
                  }
                  {name: 'ACTIONS', actions: ['delete', 'edit']}
                ],
                transPath: this.messageTranslationPrefix,
                actions: {
                  onClick: (control, event) => {
                    ....
                  }
                }
              }
            }),
          ],
        })
      ]
    };
  }

}

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