search

cos-archives / hgrid

[UNMAINTAINED] A Javascript-based hierarchical grid that can be used to manage and organize file/folder-like data
Apache License 2.0
23 stars 14 forks source link

readme

hgrid.js

Build Status

HGrid logo

HGrid.js is a Javascript-based hierarchical grid that can be used to manage and organize files and folders. It allows you to create custom filebrowser widgets that can support file uploads, asynchronous loading, search, and more.

Full documentation to come

Get it now

With bower

bower install hgrid

Manual download

Installation

Include jQuery and HGrid.

<link rel="stylesheet" href="https://github.com/cos-archives/hgrid/blob/dev/dist/hgrid.css" type="text/css" />

NOTE: The images directory should be in the same directory as hgrid.css.

<script src="https://github.com/cos-archives/hgrid/raw/dev//code.jquery.com/jquery-1.10.2.js"></script>
<script src="https://github.com/cos-archives/hgrid/raw/dev/path/to/hgrid.min.js"></script>

You can also load HGrid as an AMD module with a module loader such as RequireJS. See this wiki page.

Quickstart

The input data is an array of objects with name, kind (either "folder" or "item"), and children properties. children is an array of objects of the same form.

Example:

var files = [
    {name: 'Documents', kind: 'folder',
    children: [
      {name: 'mydoc.txt', kind: 'item'},
    ]},
    {name: 'Music', kind: 'folder',
    children: [
      {name: 'psycho-killer.mp3', kind: 'item'}
    ]}
]

To create a new grid:

var myGrid = new HGrid('#myGrid', {data: files, width: 500, height: 200});

// Or, with jQuery
$('#myGrid').hgrid({data: files, width: 500, height: 200});

Loading Data From A Server

You can pass a URL to the data option to load JSON data from a server.

var myGrid = new HGrid('#myGrid', {
  data: '/get/my/data'
});

// You can also pass $.ajax options
var grid = new HGrid('#myGrid' {
  data: '/get/my/data',
  ajaxOptions: {
    success: function(data) {alert('Huzzah!');}
  }
});

The ajaxOptions will be used for every request sent to the server.

Lazy-loading

You can lazily fetch folder contents from a server by specifying the fetchUrl option.

var grid = new HGrid('#myGrid', {
  data: '/grid/data/',  // Where to get the initial data
  fetchUrl: function(folder) {
    return '/grid/data/' + folder.name;
  }
});

Rows and Columns

Using Predefined Column Schemas

HGrid comes with a few predefined column schemas.

Usage:

var grid = new HGrid('#myGrid', {
  columns: [HGrid.Col.Name,
            HGrid.Col.ActionButtons]
  ...
});

Modifying Predefined Column Schemas

// Customize the column header text
HGrid.Col.Name.text = "Item Name"
var grid = new HGrid('#myGrid', {
  columns: [HGrid.Col.Name]
});

Custom Column Schemas, Sorting

Column schemas are just objects that have--at a minimum--the following properties:

To make a column sortable, provide sortable=true and a sortkey on which to sort the data.

NOTE: Column schemas can additionally take any Slickgrid column options.

Examples:

// Custom column schemas
var myCustomNameColumn = {
  text: 'Name',
  folderView: '<div class="folder {{cssClass}}">{{ name }}</div?>' // Using a microtemplate
  itemView: '<div class="file {{cssClass}}">{{ name }}</div?>'
  sortable: true,
  sortkey: 'name', // property of item object on which to sort on
  indent: true  // Indent based on item depth
};

var filesizeColumn = {text: 'Filesize',
  // Using a function that receives `row` containing all the item information
  itemView: function(row) {return row.filesize.toString(); },
  folderView: function(row) {return '';} // Folders don't have a file size
  sortable: true, sortkey: 'size'
};

var grid = new HGrid('#myGrid', {
  columns: [myCustomNameColumn, filesizeColumn],
  ...
});

Additional schema options

Helper functions

Actions

TODO

See examples/custom-buttons.html for an example with custom actions.

File management

TODO

var grid = new HGrid('#myGrid', {
  data: files,
  uploads: true,
  columns: [HGrid.Col.Name,
            HGrid.Col.ActionButtons]  // Provides file-related buttons
                                          // (Upload, Download, Delete)
  maxFilesize: 10,  // MB
  // Mimetypes or file extensions
  acceptedFiles: ['image/*', 'application/pdf', '.py'],
  uploadMethod: function(row) {
    return row.uploadMethod || 'post';
  },
  // Can be a string or a function that returns where to send request for upload
  uploadUrl: function(row) {  // row => {id: 3, name: 'My bucket', kind: 'folder'}
    return 'files/' + row.id;
  },
  uploadHeaders: {'My-Header': 'is awesome'},
  // Returns where to send request for deletion
  deleteUrl: function(row) {
    return 'files/' + row.id + '/remove';
  },
  deleteMethod: 'delete',
  downloadUrl: function(row) {
    return 'download/' + row.name;
  }
});

Callback Options

Event Callbacks

Asynchronous Loading of Data

Upload-related Callbacks

Permissions-related Callbacks

Adding other listeners

The init option is useful for attaching additional listeners to the grid.

var grid = new HGrid('#myGrid', {
  data: files,
  init: function() {
    this.element.on('mycustomevent', function(event) {alert('custom event triggered')});
  }
});

Other Options

TODO

Styling the Grid

Default CSS Classes

Overriding Slickgrid or Dropzone options

You can pass initial options to the Slickgrid or Dropzone constructors like so:

var grid = new HGrid('#myGrid', {
  data: files,
  dropzoneOptions: {
    parallelUploads: 5
  },
  slickgridOptions: {
    editable: true
  }
});

Accessing SlickGrid and DropZone objects directly

myGrid.grid // => The Slick.Grid object
myGrid.dropzone  // => The Dropzone object

Dependencies

Certain modules of SlickGrid are bundled with HGrid internally.

Development

Hgrid depends on NodeJS for package management and Grunt for automation.

Getting started

To install all development dependencies needed for development, run

$ npm install
$ bower install

in the project root's root directory.

Tests

Run tests with grunt.

$ grunt

Tests are written using the QUnit framework.

Tests are located in tests/tests.js.

Releasing