<commit_before># AjaxTableRails

AjaxTableRails is a super simple, super lightweight library if all you want is fast, JSON-loaded tables with ajax sorting, pagination, and filtering. It provides just enough to get you going and doesn't do anything fancy. It is also still very much in early development, so there are probably bugs.

## Usage

### Dependencies

Rails and JQuery. C'est ca. If you want to use the Javascript without Rails, feel free.

### Install ajax_table_rails gem

Add `ajax_table_rails` to your `Gemfile` and run `bundle install`

````
gem 'ajax_table_rails'
````

### Include javascript assets

Add the following to your `app/assets/javascripts/application.js`:

````
//= require ajaxtable
````

### Basic usage

#### Table structure

Your table should look like this:

````
<table data-source="<%= users_path(format: :json)%>" id="users-table">
  <thead>
    <tr>
      <th data-sort-column="name">Name</th>
      <th data-sort-column="email">Email</th>
      <th>Actions</th>
    </tr>
  </thead>
  <tfoot>
    <td colspan="3">&nbsp;</td>
  </tfoot>
  <tbody>
  </tbody>
</table>
````

Records are inserted into the `tbody` and record count and pagination are inserted into the `tfoot`.

**Data Attributes**

| Attribute | Description |
| --------- | ----------- |
| table data-source | JSON path for your table data |
| th data-sort-column | Matches database column you'd like to sort against. |

#### Filtering results

You can optionally specify a form that will be bound to your table for simple table searching and reseting.

````
<form id="users-search">
  <input class="ajax-table-search-input">
  <a href="#" class="ajax-table-reset">x</a>
  <input type="submit" value="Search">
</form>
````

The `ajax-table-search-input` and `ajax-table-reset` class names are required. Alternatively, you can call search and reset manually (see Advanced Usage, below).

#### Init that!

````
$(function() {
  $('#users-table').ajaxTable({ searchForm: '#users-search' });
});
````

#### Build your controller

Call `set_ajax_table` in a `before_action` to set your sorting criteria, then setup the query in a JSON response block.

`set_ajax_table` populates `@order`, `@page`, and `@search`, which you can use directly in your query. I use [kaminari](https://github.com/amatsuda/kaminari) for pagination and either a custom scope or [pg_search](https://github.com/Casecommons/pg_search) for searching, but you can use whatever you like.

````
before_action -> {
  set_ajax_table(columns: %w[name email], default_column: "name", default_direction: "desc")
}, only: [:index]

def index
  respond_to do |format|
    format.html {}
    format.json {
      @users = User.order(@order).page(@page)
      @users = @users.search(@search) if @search.present?
      @total_count = @users.except(:order, :limit, :offset).count
    }
  end
end
````

**Data attributes**

| Attribute | Description |
| --------- | ----------- |
| columns | Whitelist of sortable columns |
| default_column | Your default sort column (if unspecified, defaults to `id`) |
| default_direction | Your default sort direction (if unspecified, deaults to `asc`) |

#### Build your JSON

You need to render two JSON nodes: `rows` for your records, and `pagination` for your pagination details.

````
json.rows(@users) do |user|
  json.extract!(user, :name, :email)
  json.action link_to("Edit", edit_user_path(user), class: "btn")
end
json.pagination do
  json.per_page User.default_per_page
  json.count @users.size
  json.total_count @total_count
end
````

### Advanced usage

#### Custom settings

AjaxTableRails is built with Bootstrap and FontAwesome in mind, as well as some other defaults that may make you unhappy. You may want to override the classes used for pagination and sorting, as well as some other bits and bops. Here's what a full customization looks like (default values shown):
<commit_msg>Doc update<commit_after># AjaxTableRails

AjaxTableRails is a super simple, super lightweight library if all you want is fast, JSON-loaded tables with ajax sorting, pagination, and filtering. It provides just enough to get you going and doesn't do anything fancy. It is also still very much in early development, so there are probably bugs.

## Usage

### Dependencies

Rails and JQuery. C'est ca. If you want to use the Javascript without Rails, feel free.

### Install ajax_table_rails gem

Add `ajax_table_rails` to your `Gemfile` and run `bundle install`

````
gem 'ajax_table_rails'
````

### Include javascript assets

Add the following to your `app/assets/javascripts/application.js`:

````
//= require ajaxtable
````

### Basic usage

#### Table structure

Your table should look like this:

````
<table data-source="<%= users_path(format: :json)%>" id="users-table">
  <thead>
    <tr>
      <th data-sort-column="name">Name</th>
      <th data-sort-column="email">Email</th>
      <th>Actions</th>
    </tr>
  </thead>
  <tfoot>
    <td colspan="3">&nbsp;</td>
  </tfoot>
  <tbody>
  </tbody>
</table>
````

Records are inserted into the `tbody` and record count and pagination are inserted into the `tfoot`.

**Data Attributes**

| Attribute | Description |
| --------- | ----------- |
| table data-source | JSON path for your table data |
| th data-sort-column | Matches database column you'd like to sort against. |

#### Filtering results

You can optionally specify a form that will be bound to your table for simple table searching and reseting.

````
<form id="users-search">
  <input class="ajax-table-search-input">
  <a href="#" class="ajax-table-reset">x</a>
  <input type="submit" value="Search">
</form>
````

The `ajax-table-search-input` and `ajax-table-reset` class names are required. Alternatively, you can call search and reset manually (see Advanced Usage, below).

#### Init that!

````
$(function() {
  $('#users-table').ajaxTable({ searchForm: '#users-search' });
});
````

#### Build your controller

Call `set_ajax_table` in a `before_action` to set your sorting criteria, then setup the query in a JSON response block.

`set_ajax_table` populates `@order`, `@page`, and `@search`, which you can use directly in your query. I use [kaminari](https://github.com/amatsuda/kaminari) for pagination and either a custom scope or [pg_search](https://github.com/Casecommons/pg_search) for searching, but you can use whatever you like.

````
before_action -> {
  set_ajax_table(columns: %w[name email], default_column: "name", default_direction: "desc")
}, only: [:index]

def index
  respond_to do |format|
    format.html {}
    format.json {
      @users = User.order(@order).page(@page)
      @users = @users.search(@search) if @search.present?
      @total_count = @users.except(:order, :limit, :offset).count
    }
  end
end
````

**Data attributes**

| Attribute | Description |
| --------- | ----------- |
| columns | Whitelist of sortable columns |
| default_column | Your default sort column (if unspecified, defaults to `id`) |
| default_direction | Your default sort direction (if unspecified, deaults to `asc`) |

#### Build your JSON

You need to render two JSON nodes: `rows` for your records, and `pagination` for your pagination details.

````
json.rows(@users) do |user|
  json.name h(user.name)
  json.email h(user.email)
  json.action link_to("Edit", edit_user_path(user), class: "btn")
end
json.pagination do
  json.per_page User.default_per_page
  json.count @users.size
  json.total_count @total_count
end
````

**Note:** AjaxTableRails will pass through any HTML you submit, so remember to `h` or `sanitize` that user-generated content.

### Advanced usage

#### Custom settings

AjaxTableRails is built with Bootstrap and FontAwesome in mind, as well as some other defaults that may make you unhappy. You may want to override the classes used for pagination and sorting, as well as some other bits and bops. Here's what a full customization looks like (default values shown):

{'fraction_non_alphanumeric': 0.13897662665824384, 'fraction_numerical': 0.00025268477574226153, 'mean_word_length': 4.117000646412411, 'pattern_counts': {'":': 0, '<': 53, '<?xml version=': 0, '>': 55, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6448741', 'n_tokens_mistral': 2447, 'n_tokens_neox': 2342, 'n_words': 882}