Skip to content

HOWTO Step by Step

Ghislain B edited this page Nov 4, 2019 · 45 revisions

1. Install NPM Package

Install the Aurelia-Slickgrid, Bootstrap 3.x, Font-Awesome and jQuery 3.x NPM packages with

npm install --save aurelia-slickgrid jquery bootstrap font-awesome
# or with yarn add

2. For Aurelia-CLI with RequireJS/SystemJS, modify the aurelia.json file

For WebPack users, you can skip this step and continue at step 3.

With Aurelia-CLI, some may try to import the packages with au import [packageName] or simply add the following to your aurelia.json file.

Note: I can assure you that the last 3 are not going to work with au import, so you better off copying them from below.

"jquery",
"moment",
"text-encoding-utf-8",
{
  "name": "aurelia-slickgrid",
  "path": "../node_modules/aurelia-slickgrid/dist/amd",
  "main": "index",
  "resources": ["**/*.{css,html}"]
},
{
  "name": "bootstrap",
  "path": "../node_modules/bootstrap/dist",
  "main": "js/bootstrap.min",
  "deps": ["jquery"],
  "exports": "$",
  "resources": ["css/bootstrap.css"]
},
{
  "name": "flatpickr",
  "path": "../node_modules/flatpickr/dist",
  "main": "flatpickr.min",
  "resources": ["flatpickr.min.css"]
},
{
  "name": "multiple-select",
  "path": "../node_modules/aurelia-slickgrid/dist/lib/multiple-select",
  "main": "multiple-select",
  "resources": ["multiple-select.css"]
},
{
   "name": "jquery-ui-dist",
   "path": "../node_modules/jquery-ui-dist",
   "main": "jquery-ui"
},
{
  "name": "slickgrid",
  "main": "slick.grid",
  "path": "../node_modules/slickgrid",
  "deps": [
    "jquery",
    "jquery-ui-dist"
  ]
},
{
  "name": "jszip",
  "path": "../node_modules/jszip/dist",
  "main": "jszip.min"
},
{
  "name": "excel-builder-webpack",
  "path": "../node_modules/excel-builder-webpack",
  "main": "src/excel-builder",
  "deps": [
    "jszip",
    "lodash"
  ]
}
If you use i18n, you will also need these
{
  "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"
},

3. CSS / SASS Styles

Load the default Bootstrap theme style or scroll down for SASS customization.

CSS

Default compiled css (if you use the plain Bootstrap Theme CSS, you could simply add it to your index.html file and be done with it).

Aurelia-CLI
<link rel="stylesheet" type="text/css" href="scripts/css/font-awesome.min.css">
<link rel="stylesheet" type="text/css" href="../node_modules/flatpickr/dist/flatpickr.min.css">
<link rel="stylesheet" type="text/css" href="../node_modules/aurelia-slickgrid/dist/lib/multiple-select/multiple-select.css">

<!-- Slickgrid Bootstrap theme, unless you use SASS import -->
<link rel="stylesheet" type="text/css" href="../node_modules/aurelia-slickgrid/dist/styles/css/slickgrid-theme-bootstrap.css">
WebPack
import 'bootstrap/dist/css/bootstrap.css';
import 'font-awesome/css/font-awesome.css';
import 'flatpickr/dist/flatpickr.min.css';
import 'aurelia-slickgrid/dist/lib/multiple-select/multiple-select.css';
import 'aurelia-slickgrid/dist/lib/multiple-select/multiple-select.js';

// if you use CSS instead of SASS
import 'aurelia-slickgrid/dist/styles/css/slickgrid-theme-bootstrap.css';

SASS (scss)

You could also compile the SASS files with your own customization, for that simply take any of the _variables.scss (without the !default flag) variable from the file and make sure to import the Bootstrap Theme afterward. For example, you could modify your style.scss with the following changes:

/* for example, let's change the mouse hover color */
$cell-odd-background-color: lightyellow;
$row-mouse-hover-color: lightgreen;

/* make sure to add the @import the SlickGrid Bootstrap Theme AFTER the variables changes */
@import '../node_modules/aurelia-slickgrid/dist/styles/sass/slickgrid-theme-bootstrap.scss';

4. Include it in your App

Aurelia main.js or main.ts

Make the plugin available globally in your main.js file.

Aurelia-CLI
export function configure(aurelia) {
  aurelia.use.plugin('aurelia-slickgrid');
  aurelia.start().then(() => aurelia.setRoot());
}
WebPack (add the PLATFORM.moduleName)
export function configure(aurelia) {
  aurelia.use.plugin(PLATFORM.moduleName('aurelia-slickgrid'));
  aurelia.start().then(() => aurelia.setRoot());
}

5. Install/Setup I18N for Localization (optional)

To provide locales other than English (default locale), you have 2 options that you can go with. If you only use English, there is nothing to do (you can still change some of the texts in the grid via option 1.)

  1. Using Custom Locale, that is when you use only 1 locale (other thank English)... this is a new feature starting from version 2.10.0 and up.
  2. Using Localization with I18N, that is when you want to use multiple locales dynamically.

6. Create a basic grid

View

<aurelia-slickgrid 
    grid-id="grid1" 
    column-definitions.bind="columnDefinitions" 
    grid-options.bind="gridOptions" 
    dataset.bind="dataset"
    grid-height="400" 
    grid-width="800">
</aurelia-slickgrid>

ViewModel

export class Example1 {
  gridOptions;
  columnDefinitions;
  dataset = [];

  constructor() {
    // define the grid options & columns and then create the grid itself
    this.defineGrid();
  }

  attached() {
    // populate the dataset once the grid is ready
    this.getData();
  }

  /* Define grid Options and Columns */
  defineGrid() {
    this.columnDefinitions = [
      { id: 'title', name: 'Title', field: 'title', sortable: true, minWidth: 100 },
      { id: 'duration', name: 'Duration (days)', field: 'duration', sortable: true, minWidth: 100 },
      { id: '%', name: '% Complete', field: 'percentComplete', sortable: true, minWidth: 100 },
      { id: 'start', name: 'Start', field: 'start', minWidth: 100 },
      { id: 'finish', name: 'Finish', field: 'finish', minWidth: 100 },
      { id: 'effort-driven', name: 'Effort Driven', field: 'effortDriven', sortable: true, minWidth: 100 }
    ];
    this.gridOptions = {
      enableAutoResize: false
    };
  }

  getData() {
    // mock a dataset
    this.dataset = [];
    for (let i = 0; i < 1000; i++) {
      const randomYear = 2000 + Math.floor(Math.random() * 10);
      const randomMonth = Math.floor(Math.random() * 11);
      const randomDay = Math.floor((Math.random() * 29));
      const randomPercent = Math.round(Math.random() * 100);

      this.dataset[i] = {
        id: i,
        title: 'Task ' + i,
        duration: Math.round(Math.random() * 100) + '',
        percentComplete: randomPercent,
        start: `${randomMonth}/${randomDay}/${randomYear}`,
        finish: `${randomMonth}/${randomDay}/${randomYear}`,
        effortDriven: (i % 5 === 0)
      };
    }
  }
}

7. Client samples

There are multiple demos (WebPack, RequireJS, CLI, ...) that you can clone and refer to (2 of them are actually used to update the GitHub demo pages and are updated frequently). So to get you started, you can clone the aurelia-slickgrid-demos repo.

8. Explore the Wiki page content

The last step is really to explore all the pages that are available in this Wiki, all the documentation will be place in here and so you should visit it often. For example a good starter is to look at the following

  • for all the Grid Options, take a look at Wiki - Grid Options
  • Formatters
  • Editors
  • Filters
  • Grid Menu
  • ... and much more, just explorer the Wikis through the sidebar index (on your right)
    • it gets updated very frequently, we usually mention any new/updated wikis in any new version release

9. How to load data with Fetch-Client or Http-Client?

You might notice that all demos are made with mocked dataset that are embedded in each examples, that is mainly for demo purposes, but you might be wondering how to connect this with an FetchClient? Easy... just replace the mocked data, assigned to the dataset property, by your FetchClient call and that's it. The dataset property can be changed at any time, which is why you can use local data and/or connect it to a Promise or an async call with FetchClient (internally it's just a SETTER that refreshes the grid). See Example 22 for a demo showing how to load a JSON file with FetchClient.

10. Missing Features? (fear not)

What if Aurelia-Slickgrid is missing feature(s) versus the original SlickGrid? Fear not and directly use the SlickGrid and DataView objects that are expose from the start through Event Emitters. For more info continue reading on Wiki - SlickGrid & DataView objects and Wiki - Grid & DataView Events

10. Bootstrap support

Aurelia-Slickgrid supports both Bootstrap 3 and Bootstrap 4, you can see a demo of each one below.

12. Having some issues?

After reading all this HOW TO, what if you have an issue with the grid? Please start by searching any related issues. If you can't find anything in the issues log and you made sure to also look through the multiple wiki pages as well, then go ahead and fill in a new issue and we'll try to help.

Final word

This project is Open Source and is, for the most part, mainly done in spare time. So please be respectful when creating issues (and fill in the issue template) and I will try to help you out. If you like my work, you can also buy me a coffee ☕️, some part of the code happens when I'm at StarBucks... Thank you!

Clone this wiki locally
You can’t perform that action at this time.