Making a Grid

View on github

Get Code

Making a Grid

Here is what the construction of a GrapheneDataGrid looks like,

var options = {
//Make Desired options
el : 'myContainer',
data : [
{column1 : "myData"},
{column1 : "This is an array"}
],
schema : [
{type:'text', name:'column1', label:'This is Column1', required: 'true'}
]
};
//Pass into Grid
var first_grid = new GrapheneDataGrid(options);

The example above displays the only options required to make a grid.
The required options are:
- el : The html element where the grid will be located
- data : The data to populate the grid with
- schema : How the data will be displayed in the grid
We will go over every available option in detail below.

(Object) Options

(Object) options : This is the only parameter passed into GrapheneDataGrid:

 var grid_constructor = new GrapheneDataGrid(options)

Some Key Notes about options:
- Options is an Object, meaning it has multiple key value pairs
- You only have to pass in three of the total options,
  - 1. el (Where the Data is displayed)
  - 2. data (The data to be displayed)
  - 3. schema (How the data is displayed)
- Many of the options below have default values (which will be noted in the documentation below) which is why they are not required to create a grid

(HTML Element) el:

This is the HTML Element where the grid will be displayed. Both HTML Classes and ID's are valid containers

<body>
<div id="myIDContainer"></div>
<div class="myClassContainer"></div>
</body>
<script>
//ID example
options = {  el : document.getElementByID('myIDContainer')  }
//Class Example
options = {  el : document.getElementsByClassName('myClassContainer')[0]  }
</script>

(Array) data:

(Array) data = [ {Data Object 1}, {Data Object 2}, ... ];
This is an array of Objects where each object represents one row in the table.
Note all objects are independent of each other, so they could all contain the same data values.

<script>
var options = {
data : [ 
//First Column of Data
{name : "value", number : 1},
//Second Column of Data
{name : "value", number : 2}
]
}
</script>

* See the section "schema" below for an example of the 'data' field *

(Array) schema:

(Array) schema = [ { //Column #1 display format }, { //Column #2 display format }, ... ]
Schema determines how each data object will be read in and displayed visually.
Schema is based on gforms, all possible values of schema can be found here: gforms Fields Doc
Try out the demo section of gforms to get a grasp of how different forms will display: gforms Demo Page
The name:value pairs of the objects are extremely important. For the data's values to be displayed the name value must match one of the name values of the schema (See Below)

Code:

<script>
var options = {
data : [ 
//First Column of Data
{number : 1, string : "value"},
//Second Column of Data
{number : 2, string : "value"},
//Third Column of Data
{number : 3, string : "value"}
],
schema : [
    {type:'text', name:'number', label:'Numbers'},
    {type:'text', name:'string', label:'Strings'}
],
//The first row of data will be labeled 'Numbers', and will read the key-value 'number' from the data Objects.
//the second row of data will be labeled 'Strings', and will read the key-value 'string' from the data Objects.
filter: false
}
var Grid = new GrapheneDataGrid(options);

</script>

Result:

(ColumnName) sort:

(Name) sort = //Name of column taken from schema
If you pass a value into sort, then the column will be automatically sorted in decreasing order when the table loads.
See Example Below, which is a grid with the option: sort: 'number':

(Array[ColumnNames]) multiEdit:

(Array[ColumnNames]) multiEdit = [ ColumnName1, ColumnName2 ]
Default: []
multiEdit allows multiple models to be edited at the same time under the following conditions:
- Only columns included in the multiEdit array may be edited.
- Every selected model must have the same value in its respective column
Example: Select all columns below and press edit

Code:


    var multiedit_options = {
        el: '#multieditgrid',
        data : [
        {number : 3, string : "value"},
        {number : 2, string : "value"},
        {number : 1, string : "value"}
        ],
        filter: false,
        multiEdit: ['string'],
        upload: false, download:false, columns:false, entries:[], search:false,
        schema : [
        {type:'text', name:'number', label:'Numbers'},
        {type:'text', name:'string', label:'Strings'}
        ]
        }
        multiEditGrid = new GrapheneDataGrid(multiedit_options);

(Array[Integers]) entries:

(Array of Integers) entries = [ 25,50,75]
Allows user to change the number of models displayed. The initial number of models displayed is set by 'count'. Read more on 'count' below
Default: [25,50,100]

(Integer) count:

(Integer) count = 25
Defines the number of models that will be displayed when the grid first loads.
Default: 25

(Boolean) search:

(Boolean) search = True //or False
Defines if a search bar is present or not. Search bar is located at the top right of the datagrid if enabled.
Default: True

(Boolean) filter:

(Boolean) filter = True //or False
Defines columns may be filtered by the user or not. Filter bars are located at the top of every column if enabled.
Default: True

(Boolean) columns:

(Boolean) columns = True //or False
Enables or disables the ability to select which columns are currently displayed.
Default: True

(Boolean) upload:

(Boolean) upload = True //or False
Enables or disables the ability to upload .csv files into the datagrid.
Default: True

(Boolean) download:

(Boolean) download = True //or False
Enables or disables the ability to download the current data populating the datagrid into a .csv file.
Default: True

Functionality and Events

Summary: GrapheneDataGrid allows for custom create, edit, and delete functionality along with the ability to create custom actions.
Actions is another Option that can be passed into the GrapheneDataGrid. Actions can remove or replace any default datagrid action: Create, Edit, or Delete.
Custom actions can be defined using actions as well.
Default value of actions is below:


    actions: [
        {name: "create", type: "success", min: 0, label: 'New'}, "|",
        {name: "edit", type: "primary", min: 1, max: 1, label: 'Edit'}, "|",
        {name: "delete", type: "danger", min: 1, max: 1, label: 'Delete'}
        ],

NOTE: The "|" seperates the buttons into button groups, which helps visually display items. "|" is not the required syntax, you can use anything that isn't an object (Such as "space" or 345).

(String) name : the defined name of the event
(String) type: the defined type of the event. Examples: "success", "primary", "danger" (See Bootstrap Classes) for more
(Integer) min: the minimum number of models that must be selected for this action to be available for use.
(Integer) max: the minimum number of models that can be selected for this action to be available for use.
All of these values are adjustable.

Events are what gives actions their functionality.
When an event is triggered on the datagrid, such as the 'create' event, a defined function associated with that event is triggered.
To map a grid event to a function, append the following to any datagrid creation:
.on( Eventname, function(e) )
Eventname is the name of the triggered event and function(e) is a function to be executed. The e parameter is an object containing the event and information associated with the event, such as the datagrid that the event was triggered on. Any defined function can also be put in place of function(e).
NOTE that if you define a function the first parameter will always be the event object.
NOTE the variable name doesn't have to be e, e is shorthand for event, that is simply what we prefer to use.
See the Example below on how to add functionality to a datagrid:

Code:


        var custom = function(e){
            var a = document.getElementById('toggleclass');
            a.innerText = "Custom Commands Rock!";
            }
        var events_grid = new GrapheneDataGrid({
            el : '#eventsgrid',
            data : [
                { middlename: "Scott"},
                { middlename: "Tim"}
            ],
            search: false,
            schema : [{type: 'text', name : 'middlename', label : 'Someones Middle Name'}],
            actions: [
                {name: "create", type: "success", min: 0, label: ' New'}, "|",
                {name: "customevent", type: "primary", min: 0, label: ' Custom'}, "|",
                {name: "delete", type: "danger", min: 1, max: 1, label: ' Delete'}
                ],
        }).on('customevent', custom)
            .on('create', function(e){
                e.preventDefault();
                //Create Some Stuff!
            });

- In this code the 'delete' event has the default functionality because no function is explicitly mapped to it. Try it out by selecting a model! (Click on a checkbox on the left-side of the grid)
- The 'new' event has custom functionality mapped to it. Note the 'preventDefault()' function. This will stop any default behaviors from occuring while you map your custom functions. Try it out!
- Finally, we have the 'custom'. We made the function custom(e) which will ad some text to an HTML element. Try it out!

NOTE: We removed the 'edit' event.

Grid:

Tenses

Events such as 'create' have Two Stages.

In-Creation Stage. This stage occurs the instant an event is triggered.
Example: 'create'
- The 'create' event will be triggered at the instant the event is called. This allows for manipulations to be made to data before the object is created.
Post-Creation StageThis stage occurs immeadiately after the corresponding In-Creation Stage event is finished.
Example: 'created' : The corresponding In-Creation Stage event would be 'create'
- The 'created' event will trigger after 'create' finishes. This allows for data validation and displaying both error and success messages.

(Event) create

Pressing the 'new' button by default will trigger a modal (window pop-up) to appear on the screen prompting the creation of a new table model.
The 'create' event is triggered when save is pressed on the model. Try: .on('create', function(e){ e.preventDefault() } to prevent default behavior and define your own create function.
Example: new GrapheneDataGrid( ... ).on('create', function(e){ //DOSTUFF })

(Event) created

The 'created' event is triggered after a model has been created and visually displayed in the DataGrid.
Triggers after the 'create' event.
Example: new GrapheneDataGrid( ... ).on('created', function(e){ //DOSTUFF })

(Event) model:created

The 'model:created' event is similar to the 'created' event. It is triggered after a model has been created and visually displayed in the DataGrid.
The difference between 'model:created' and 'created' is that the first parameter of the function triggerd by 'model:created' contains a reference to the newly created model.
Use the new model's reference to change the visual display of the model in the grid.
Use 'model:created' to trigger a function that will persistently store the new model, such as in a .csv file or a database.
Example: new GrapheneDataGrid( ... ).on('model:created', function(e){ //DOSTUFF })

(Event) edit

'edit' is called the instant the edit button is selected.
Default: allows one model to be edited at a time. Editing allows values to be updated.
Use .on('edit', function(e){ e.preventDefault() } to stop default behavior and define a custom edit function.
See 'actions' to learn more about adjusting 'edit's default settings.
Example: new GrapheneDataGrid( ... ).on('edit', function(e){ //DOSTUFF })

(Event) edited

The 'edited' event is triggered after a model has been created and visually displayed in the DataGrid.
Triggers after the 'edit' event.
Example: new GrapheneDataGrid( ... ).on('edited', function(e){ //DOSTUFF })

(Event) model:edit

'model:edit is triggered at the same time as 'edit'.
The differences are:

'model:edit' contains a reference to the model that is currently being edited.
If multiple models are selected to be edited (this is possible by changing the defualt behavior has been changed to allow multiple models to be edited), 'model:edit' will be called for each selected model.

Example: new GrapheneDataGrid( ... ).on('model:edit', function(e){ //DOSTUFF })

(Event) model:edited

'model:edited' contains a reference to the model that has finished being edited.
In other words, after you edit a model and press save, this event triggers.
Example: new GrapheneDataGrid( ... ).on('model:edited', function(e){ //DOSTUFF })

(Event) delete

'delete' is triggered once the delete button has been pressed.
Default: Deletes one, and only one, model from the table, removing it from the tables data as well as visually.
Use 'delete' to call functions that update external data sources, such as databases or .csv sheets.
Note: You can call e.preventDefault() to prevent default behavior
Example: new GrapheneDataGrid( ... ).on('delete', function(e){ //DOSTUFF })

(Event) deleted

'deleted' is triggered once a model has been deleted.
Use this to display Success or Error messages for deletion
Example: new GrapheneDataGrid( ... ).on('deleted', function(e){ //DOSTUFF })

(Event) model:delete

'model:delete' is similar to 'delete' as they are both triggered once the delete button is pressed;
However, 'model:delete' additionally contains a reference to the model to be deleted.
Use 'model:delete' when:
- You want a reference to the model you are deleting or
- you have overidden the default delete functionality to delete multiple models at once, and would like references to each model.
Note: See 'delete' for default deletion functionality.
Example: new GrapheneDataGrid( ... ).on('model:delete', function(e){ //DOSTUFF })

(Event) model:deleted

'model:deleted' is similar to 'deleted' as they are both triggered once a model has been deleted;
However, 'model:deleted' additionally contains a reference to the model that was deleted.
Note: See 'deleted' for information on its functionality.
Example: new GrapheneDataGrid( ... ).on('model:deleted', function(e){ //DOSTUFF })

Making a Grid

We will go over every available option in detail below.

(Object) Options

(HTML Element) el:

(Array) data:

(Array) schema:

Code:

Result:

(ColumnName) sort:

(Array[ColumnNames]) multiEdit:

Code:

(Array[Integers]) entries:

(Integer) count:

(Boolean) search:

(Boolean) filter:

(Boolean) columns:

(Boolean) upload:

(Boolean) download:

Functionality and Events

Code:

Grid:

Tenses

(Event) create

(Event) created

(Event) model:created

(Event) edit

(Event) edited

(Event) model:edit

(Event) model:edited

(Event) delete

(Event) deleted

(Event) model:delete

(Event) model:deleted