hgrid.js

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

Standalone (includes SlickGrid): Uncompressed | Minified
No bundled dependencies: Uncompressed | Minified
hgrid.css: Uncompressed | Minified
Images

Installation

Include jQuery and HGrid.

<link rel="stylesheet" href="dist/hgrid.css" type="text/css" />

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

<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="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.

HGrid.Col.Name: Included by default. Formats files and folders with proper indent, icon, and name field.
HGrid.Col.ActionButtons: Provides "Download" and "Delete" buttons for files and "Upload" button for folders.

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:

text: The text to show in the column header
folderView: Either a function that renders the HTML for a folder or a microtemplate.
itemView: Either a function that render the HTML for a file or a microtemplate.

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

indent: Either a boolean or number of pixels to indent each row. Number of indents will be calculated based on an item's depth.
showExpander: function(row, args): Boolean or function that returns a boolean whether to show the expander button or not.
isName: Boolean indicating whether the column is the name column.

Helper functions

HGrid.Fmt.withIndent(row, html, [indentWidth]): Adds an indenting span based on the a row's depth property.
HGrid.Fmt.asItem(row, html): Surrounds html with <div class="hg-item" data-id=123>
HGrid.Fmt.button(row, buttonDef): Render a button. A buttonDef is an Object that specifies how a button will be rendered. It may include the following properties: text (button's text), cssClass (a string, the CSS class to apply to the button), action (a registered HGrid action, e.g. 'download'), and/or attributes (string of additional HTML attributes, e.g. 'data-id="some-id"').
HGrid.Fmt.buttons(row, buttonDefs): Render a series of buttons. buttonDefs is an Array of button definition Objects.
HGrid.Fmt.tpl(template, data): Microtemplating function.

Actions

TODO

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

File management