Aurelia-editables is a configurable data editor plugin for Aurelia with built-in validation and localization support. It provides an easy solution for creating editable datagrids or tables and forms. This project's main goal is to provide configurable, reusable widgets for data manipulation that can make the development of admin applications easier.
With aurelia-editables you can create:
@TODO: Showcase and more examples
@TODO: Check out the Github Wiki.
Run jspm install npm:aurelia-editables
This plugin has several resources other than the main javascript file, so we'll need a bit of additional tweaking for correct bundling. Add this code below to the corresponding (bundles.dist/aurelia.includes or similar) section of build/bundles.js.
"aurelia-editables",
"aurelia-editables/**/*.js",
"aurelia-editables/**/*.html!text",
"aurelia-editables/**/*.css!text",Install via NPM
npm install aurelia-editables --saveeditables helper task for aurelia-cliSince aurelia-cli is still in alpha stage and install command is not yet implemented, I've created a custom cli task to help you with configuring plugin dependencies in aurelia.json. It adds a pre-configured set of dependencies to aurelia.json.
A post-install npm script takes care of placing this new editables.ts|js task into aurelia_project/tasks folder.
All parameters are optional
| Optional parameters | Description |
|---|---|
| --bundle, b |
Set bundle section to be modified |
| --force, f | Overwrite previously set dependencies (applies to this package's dependencies only! It won't delete the whole bundle setting.) |
| --generate, g |
(Not implemented yet.) Generates a Grid/Form configuration based on given parameters and saves it to a json file. |
Run editables helper
au editables [--bunde <custom-bundle-filename>] [--force]Note: tested on Windows platform only.
If you'd prefer embracing the power of CTRL+C over using some mysterious script, just add below section to your desired bundle section in aurelia.json:
...
{
"name": "interact",
"path": "../node_modules/interact.js/dist",
"main": "interact"
},
{
"name": "aurelia-interactjs",
"path": "../node_modules/aurelia-interactjs/dist/amd",
"main": "index"
},
"aurelia-http-client",
"underscore",
{
"name": "jquery",
"path": "../node_modules/jquery/dist",
"main": "jquery.min"
},
{
"name": "bootstrap",
"path": "../node_modules/bootstrap/dist",
"main": "js/bootstrap.min",
"deps": ["jquery"],
"exports": "$"
},
{
"name": "i18next",
"path": "../node_modules/i18next/dist/umd",
"main": "i18next"
},
{
"name": "aurelia-i18n",
"path": "../node_modules/aurelia-i18n/dist/amd",
"main": "aurelia-i18n"
},
{
"name": "i18next-xhr-backend",
"path": "../node_modules/i18next-xhr-backend/dist/umd",
"main": "i18nextXHRBackend"
},
{
"name": "aurelia-validation",
"path": "../node_modules/aurelia-validation/dist/amd",
"main": "aurelia-validation"
},
{
"name": "aurelia-ui-virtualization",
"path": "../node_modules/aurelia-ui-virtualization/dist/amd",
"main": "aurelia-ui-virtualization"
},
{
"name": "aurelia-editables",
"path": "../node_modules/aurelia-editables/dist/amd",
"main": "aurelia-editables",
"resources": [
"**/*.html",
"**/*.css"
]
}
...@TODO: provide installation steps. I have no prior experience with webpack. Any feedback or help would be appreciated on this.
Register plugin in your main.js. It configures all resources, eliminating the need for additional <require> declarations in views.
Default configuration...
export function configure(aurelia) {
aurelia.use
.standardConfiguration()
.developmentLogging()
.plugin('aurelia-interactjs') // Add this line to load interact.js (optional)
.plugin('aurelia-editables'); // Add this line to load the plugin
aurelia.start().then(a => a.setRoot());
}...or customized configuration
aurelia.use
.standardConfiguration()
.developmentLogging()
.plugin('aurelia-interactjs') // Add this line to load interact.js (optional)
.plugin('aurelia-editables', (config) => {
// replace default remote data connector
config.api = MyOwnApiClass;
// replace existing editor templates
config.editors['text'] = './custom/text-editor';
// register additional editor templates
config.editors['datepicker'] = './custom/date-picker';
});MultiGrid:
<multi-grid options.bind="gridOptions"></multi-grid>DataGrid:
<data-grid options.bind="gridOptions"></data-grid>DataForm:
<data-form options.bind="gridOptions" record.bind="currentRecord"></data-form>Standalone Fields:
<field options.bind="fieldOptions"
integrated-mode.bind="false"
edit-mode.bind="true"
field-value.bind="item[fieldOptions.name]"
record.bind="item"
with-label.bind="true" />There are a bunch of bindable events available for all components. Usually, the viewModel instance can be accessed through the viewModel property of any $event.detail object.
data-grid.ts source:
this.dispatch('on-before-save', { viewModel: this, changes: changes });Usage in template (my-view-model.html):
<template>
<data-grid on-before-save.delegate="myEvent($event)"></data-grid>
</template>Usage in viewmodel (my-view-model.js):
export class MyViewModel {
...
myEvent(event) {
console.log(event.detail.viewModel);
}
...
}| Name | Tag | Description |
|---|---|---|
| DataGrid | <data-grid> |
Editable DataGrid, generated based on a configuration object |
| MultiGrid | <multi-grid> |
Tabbed view generated based on an array of configuration objects |
| DataForm | <data-form> |
Editable form, generated based on the same configuration as DataGrids |
| Field | <field> |
Basic data editor component |
It is commonly used by all components, which makes it possible to combine them as lego-parts. The config contains a set of definitions for fields/columns, backend-connection, parent-child relations, etc.
Simplified sematic view of DataGrid/DataForm configuration objects:
<grid-definition> {
<base-attributes>
<form-options>
<columns>: [
<field-definition>,
<field-definition>
]
<children>: [
<grid-definition>,
<grid-definition>
]
<child-options>
}
Based on above, a similar view of Field configuration objects. It is the integral part of any DataGrid/DataForm config, but it can be used with standalone Fields as well.
<field-definition> {
<base-attributes>,
<filter-options>
<editor-options>,
<validation-options>
}MultiGrid configuration is simply an array of DataGrid configs objects:
[
<grid-definition>,
<grid-definition>,
<grid-definition>
]Full example here: config.example.json
Definition is available in typings_custom and dist folders. Package.json has been configured as well.
Notes on aurelia-interactjs:
Its usage is optional at this point in time, there is no hard reference for it. If you don't need column resizing, it can be left out from plugin references in main.js|ts.
Future versions: planned drag and drop features may involve deeper integration with this plugin.
Notes on jQuery + Bootstrap: Although, this plugin is not dependent on jQuery, the basic layout has primarily designed to work with Bootstrap. That means no hard dependencies in this project, but your application may need to have jQuery and Bootstrap bundled.
MultiGrid component:
MultiGrid, then referencing Bootstrap css only without jQuery + Bootstrap JS references could be working.Support for Other UI frameworks (not implemented)
@TODO: I have some ideas how to do that. For example, by making views replaceable via configuration or binding.
E.g. <data-grid layout.bind="./grid-sematic-ui.html"></data-grid>
This library can be used in the browser only.
To build the code, follow these steps.
Ensure that NodeJS is installed. This provides the platform on which the build tooling runs.
From the project folder, execute the following command:
npm installEnsure that Gulp is installed. If you need to install it, use the following command:
npm install -g gulpTo build the code, you can now run:
gulp buildYou will find the compiled code in the dist folder, available in five module formats: AMD, CommonJS, ES2015, Native-modules and System.
See gulpfile.js for other tasks related to generating the docs and linting.