Property Grid

• Overview
• Installation
• Usage
  • With Typescript
  • With JavaScript
  • Advanced
• API
  • Properties
  • Methods
  • Events
  • Hooks
  • Styling

Overview

A small and simple property grid, written in pure Vanilla JavaScript (web components), inspired by jqPropertyGrid.

With this PropertyGrid control you can pass object and allow users to edit the properties with the data type-specific editors. The component offers the ability to group and sort its items, use custom editors per data type, work with and without configuration...etc.

Installation

Install with npm:

npm i clean-web-ui-property-grid --save

Usage

With Typescript

If you are using typescript:

// In your main file
import 'clean-web-ui-property-grid';

const pgOptions = {
  hasGroups: true,
  propertySort: true,
  toolbarVisible: true,
} as PropertyGridOptions;

const pgData = {
  filter: true,
  filterSize: 200,
};

const pg1: PropertyGrid = document.getElementById('pg1') as PropertyGrid;
pg1.options = pgOptions;
pg1.selectedObject = pgData;

// To listen for value changes
pg1.addEventListener('valueChanged', (v) => console.log(v));

// To get values from property grid
document.querySelector('#getValuesBtn').addEventListener('click', () => {
  console.log(pg1.getValues());
});

Html markup

<property-grid id="pg1"></property-grid>

With JavaScript

With JavaScript, just import the script in the html body:

<script src="clean-web-ui-property-grid.js"></script>

You can use by inserting web component in html:

<property-grid id="pg1"></property-grid>

With JS:

const pg1 = document.getElementById('pg1');
pg1.selectedObject = pgData;

Advanced

More complex example would be to pass config and options to the grid.

In HTML:

<div id="propertyGridWithConfig"></div>

In Js/Typescript:

//If using Typescript
import {createPropertyGrid} from 'clean-web-ui-property-grid';

var pgOptions = {
  hasGroups: true,
  propertySort: true
};

var pgConfig = {
  filter: { group: 'Behavior', name: 'Filter', type: 'boolean' },
  filterSize: {
    group: 'Behavior',
    name: 'Filter size',
    type: 'number',
    options: { min: 0, max: 500, step: 10 },
  }
};

var pgData = {
  filter: true,
  filterSize: 200
};

function createPropertyGrid(id, config, options, data) {
  var propertyGridWrapper = document.getElementById(id);
  let propertyGrid = document.createElement('property-grid');
  propertyGrid.id = 'pg' + id;
  propertyGrid.config = config;
  propertyGrid.options = options;
  propertyGrid.selectedObject = data;
  propertyGridWrapper.innerHTML = '';
  propertyGridWrapper.appendChild(propertyGrid);
}

createPropertyGrid('propertyGridWithConfig', pgConfig, pgOptions, pgData);

// To listen for events emmited from grid
 document.getElementById('pgpropertyGridWithConfig').addEventListener('valueChanged', (v) => console.log(v));

API

Properties

config - PropertyGridConfig | null This is the metadata object that describes the target object properties. Here you can pass and configure how the property grid editors will work like: control type, min/max values...etc.

{
"browsable": boolean //  Whether this property should be included in the grid, default is true (can be omitted),
"group": string // The group this property belongs to
"name": string // The display name of the property in the grid
"type": 'text' | 'number' | 'boolean' | 'color' | 'options' | 'label' // The type of the property
"description": string // A description of the property, will be used as tooltip on an hint element (a span with text "[?]")
"showHelp": boolean // If set to false, will disable showing description's span with text "[?]" on property name.
"items": string[] // List of Dropdown Items used for select control
"options": Object // An extra options object per type (attributes per control)
}

options - PropertyGridOptions | null The options that are passed to the property grid control to configure how the grid will work. Here you pass options that configure the grid itself, not the individual controls. You can pass options like: show/hide groups, sort method...etc.

{
"hasGroups": boolean //Gets or sets a value indicating whether controls are groupped and if groups are visible
"propertySort": boolean | Function //If and how to sort properties in the grid. Optionally you can pass callback functiom
"onValueChange": FormControl // Hook that is called before value is changed
"controls": Function // Set custom controls that will be used for rendering
"enabled": boolean // Gets or sets a value indicating whether the control can respond to user interaction.
"toolbarVisible": boolean // Gets or sets a value indicating whether the toolbar is visible.
}

selectedObject - Object The is the object that you want to edit in the grid. If no config is passed to the grid, the grid will try to create config based on object properties and value type.

disabled - boolean Gets or sets a value indicating whether the control can respond to user interaction.

Methods

render() - void Build the config for the grid, render controls on UI and attach event listeners. Called internally by the grid when selectedObject is changed.

getValues() - Object Returns the current values for all properties in the grid.

destroy() - void Destroys all elements and removes all event listners from elements. Called internally by the grid when the component is about to be destroyed.

Events

valueChanged - CustomEvent Fired when the value is changed for some of controls in the property grid.

Event payload:

{name: 'controlname', value: 'new value'}

Hooks

onValueChange(event) - Object | boolean | void Hook that is called before value is changed. Usefull if you want to intercept the original valueChange event.

Styling

Available CSS variables

--property-grid-header-background: #E0ECFF;
--property-grid-header-border: 1px dotted #95B8E7;
--property-grid-table-row-group-background: #E0ECFF;
--property-grid-table-row-group-font-weight: bold;
--property-grid-table-row-hover: #f0f5fd;
--property-grid-cell-border: 1px dotted #ccc;