Skip to content

Latest commit

 

History

History
97 lines (58 loc) · 7.07 KB

Readme.md

File metadata and controls

97 lines (58 loc) · 7.07 KB
Raw

Lombiq Data Tables for Orchard Core

Lombiq.DataTables NuGet Lombiq.DataTables.Samples NuGet Lombiq.DataTables.Tests.UI NuGet

About

An Orchard Core wrapper around the DataTables library for displaying tabular data from custom data sources.

Note that this module has an Orchard 1 version in the dev-orchard-1 branch.

Do you want to quickly try out this project and see it in action? Check it out in our Open-Source Orchard Core Extensions full Orchard Core solution and also see our other useful Orchard Core-related open-source projects!

How to use

You can find a sample module with a commented walkthrough in this repository. Check it out here!

Static Content With Tag Helper

In the most basic form you can use DOM sourced data with the <datatable> tag helper.

Asynchronous Content With a Custom Provider

The Lombiq_DataTable shape can display sortable, searchable, paginated data, but you must make your own data provider by extending DataTableDataProviderBase or either of the abstract base classes provided by us (JsonResultDataTableDataProvider, IndexBasedDataTableDataProvider). The latter is for complex database queries that would take a long time to calculate on demand, are tied to one or more content items and can be indexed ahead of time.

Once you have your data provider, it must be registered using services.AddDataTableDataProvider<TProvider>(), or if it's index-based then using services.AddIndexBasedDataTableProvider<TIndex, TGenerator, TMigration, TProvider>().

If you need an admin page with just one data table you don't need to define a view, just link to /Admin/DataTable/{providerName}/{queryId?}.

You can find an example using LinqToDb queries do display a table of deleted content items at DeletedContentItemDataTableDataProvider.cs.

If you want a display a table of deleted content items, we already happen to have a provider for that called DeletedContentItemDataTableDataProvider.

Client-side Extensibility

With Shape

For configuring the setup logic or global customization you can override the Lombiq.DataTable.Resources shape, for example in your theme. This is displayed before the Lombiq.DataTable shape, but after the basic configurations have been initialized (note: not applicable to the <datatable> tag helper).

Here you can edit the window.dataTableResources object. It contains the following properties:

  • options: a regular DataTables options object. For example use window.dataTableResources.options.dom to set the table layout for your theme.
  • created: a callback (function (wrapperElementJQuery, plugin)) that's executed after the plugin has been initialized. This is the ideal place for adding custom controls.

With Events

You can use all the regular DataTables events, but we've also implemented some custom ones. While DataTables events use the .dt namespace, these use the .lombiqdt namespace to avoid future conflict. They target the same DataTable element.

  • popstate.lombiqdt: fired after a history back/forward between different states of the table. The event is { plugin: jQueryPlugin, state: { providerName, data, order }, cancel: false }. Change cancel to true if you don't want to load this history.
  • createstate.lombiqdt: fired before a new DataTable history state is placed. The event is { plugin, state } and you can alter the state object from the event handler.
  • preXhr.lombiqdt: fired inside the options.ajax function right before the web request is sent out. The event is { plugin, requestData, isHistory }. You can change requestData here.

Vue.js Alternative

You may say, I Can't Believe It's Not DataTable! but it really is not. Use the <icbin-datatable> component for scenarios where you need something that matches the look and feel of DataTables and is a reusable Vue component with MVVM style logic.

<div id="my-app-id" class="my-app">
    <icbin-datatable v-model="data"
                     :columns="columns"
                     :text="text"
                     @@special="onSpecial">
        <div>Content here goes between the page length picker and the table.</div>
    </icbin-datatable>
</div>
  • data: a serialized array of VueModel (v-model here refers to the data property and the update event).
  • columns: a serialized array of DataTableColumnDefinition.
  • text: an object of keys and display texts (i.e. string-string dictionary). Its expected properties are: lengthPicker, displayCount, previous, next.
  • onspecial: a function that receives a cell that has the VueModel.Special property and can edit it.

For additional properties and notes on the events take a look at the comments in the component.

Note: Use @Json.Serialize() to automatically camelCase the data for JS.

Dependencies

This module has the following dependencies:

Troubleshooting

Visual Studio 2022

If you get the IntelliSense-only error TS6053 File "(...)/types/types.d.ts" not found. The file is in the program because: The root file specified for compilation_ you need to disable automatic type acquisition. This problem isn't present in VS2019 or third party IDEs, and it's cause by the Javascript Language Service. Solution:

  1. From the menu select Tools → Options.
  2. From the sidebar select Text Editor → JavaScript/Typescript → Project → General.
  3. Scroll down and uncheck Enable automatic type acquisition (TS 4.1 or later).

Contributing and support

Bug reports, feature requests, comments, questions, code contributions and love letters are warmly welcome. You can send them to us via GitHub issues and pull requests. Please adhere to our open-source guidelines while doing so.

This project is developed by Lombiq Technologies. Commercial-grade support is available through Lombiq.