From 65efee35549add2f5ca668349d25dfd7bf60a665 Mon Sep 17 00:00:00 2001 From: Allan Jardine Date: Tue, 25 Jun 2013 09:56:00 +0100 Subject: [PATCH] Docs - The new XML container for the examples has been updated to have the content of the tag as markdown rather than XML / XHTML. I think this will probably be easier long term. --- examples_src/basic_init/alt_pagination.xml | 21 ++++- examples_src/basic_init/complex_header.xml | 14 +++- examples_src/basic_init/dom.xml | 81 +++++++++++++++---- examples_src/basic_init/filter_only.xml | 17 ++-- examples_src/basic_init/flexible_width.xml | 10 ++- examples_src/basic_init/hidden_columns.xml | 25 ++++-- examples_src/basic_init/index.xml | 8 +- examples_src/basic_init/language.xml | 10 ++- examples_src/basic_init/multi_col_sort.xml | 41 ++++------ examples_src/basic_init/multiple_tables.xml | 12 ++- examples_src/basic_init/scroll_x.xml | 22 +++-- examples_src/basic_init/scroll_xy.xml | 17 ++-- examples_src/basic_init/scroll_y.xml | 20 +++-- examples_src/basic_init/scroll_y_infinite.xml | 25 ------ examples_src/basic_init/scroll_y_theme.xml | 14 ++-- examples_src/basic_init/state_save.xml | 15 +++- examples_src/basic_init/table_sorting.xml | 12 ++- examples_src/basic_init/themes.xml | 12 ++- examples_src/basic_init/zero_config.xml | 8 +- 19 files changed, 246 insertions(+), 138 deletions(-) delete mode 100644 examples_src/basic_init/scroll_y_infinite.xml diff --git a/examples_src/basic_init/alt_pagination.xml b/examples_src/basic_init/alt_pagination.xml index cf8a66c8..0466b6a5 100644 --- a/examples_src/basic_init/alt_pagination.xml +++ b/examples_src/basic_init/alt_pagination.xml @@ -14,10 +14,23 @@ $(document).ready(function() { } ); ]]> - -

The page controls which are used by default in DataTables (forward and backward buttons only) are great for most situations, but there are cases where you may wish to customise the controls presented to the end user. This is made simple by DataTables through its extensible pagination mechanism. There are two types of pagination controls built into DataTables: two_button (default) and full_numbers. To switch between these two types, use the paginationType initialisation parameter. You can add additional types of pagination control by extending the $.fn.dataTableExt.oPagination object.

+The example below shows the full_numbers type of pagination, where 'first', 'previous', 'next' and 'last' buttons are presented, as well as the five pages around the current page.

- +The default page control presented by DataTables (forward and backward buttons with up to 7 page numbers in-between) is fine for most situations, but there are cases where you may wish to customise the options presented to the end user. This is done through DataTables' extensible pagination mechanism, the `dt-init paginationType` option. + +There are four built-in options for which pagination controls DataTables should show: + +* `simple` - 'Previous' and 'Next' buttons only +* 'simple_numbers` - 'Previous' and 'Next' buttons, plus page numbers +* `full` - 'First', 'Previous', 'Next' and 'Last' buttons +* `full_numbers` - 'First', 'Previous', 'Next' and 'Last' buttons, plus page numbers + +The language strings of 'First', 'Previous' etc can be optionally through the internationalisation options of DataTables; `dt-init first`, `dt-init previous` etc. + +Additional options for the buttons that are shown can be added through the use of pagination type plug-ins. Furthermore, how the buttons are actually shown can be altered through the use of plug-in pagination renderers. + +The example below shows the `full_numbers` type of pagination. + +]]> diff --git a/examples_src/basic_init/complex_header.xml b/examples_src/basic_init/complex_header.xml index 4262987d..18b5bcf1 100644 --- a/examples_src/basic_init/complex_header.xml +++ b/examples_src/basic_init/complex_header.xml @@ -5,15 +5,21 @@ -Complex headers (row and colspans) +Complex headers (rowspan and colspan) - -When using tables to display data, you will often wish to display column information in groups. DataTables fully supports colspan and rowspans in the header, assigning the required sorting listeners to the TH element suitable for that column. Each column must have one TH cell (and only one) which is unique to it for the listeners to be added. The example shown below has the core browser information grouped together. - + diff --git a/examples_src/basic_init/dom.xml b/examples_src/basic_init/dom.xml index 33d02604..d769a949 100644 --- a/examples_src/basic_init/dom.xml +++ b/examples_src/basic_init/dom.xml @@ -14,20 +14,71 @@ $(document).ready(function() { } ); ]]> - -

When customising DataTables for your own usage, you might find that the default position of the feature elements (filter input etc) is not quite to your liking. To address this issue DataTables takes inspiration from the CSS 3 Advanced Layout Module and provides the dom initialisation parameter which can be set to indicate where you which particular features to appear in the DOM. You can also specify div wrapping containers (with classes) to provide complete layout flexibility. The syntax available is:

-
    -
  • l - Length changing
    • -
  • f - Filtering input
    • -
  • t - The table!
    • -
  • i - Information
    • -
  • p - Pagination
    • -
  • r - pRocessing
    • -
  • < and > - div elements
    • -
  • <"class" and > - div with a class
    • -
  • Examples: <"wrapper"flipt>, <lf<t>ip>
    • -
-

In the example below I've moved the table information to the top of the table, and all the interaction elements to the bottom, each wrapper in a container div.

- +` - div elements +* `<"#id"` and `>` - div with an id +* `<"class"` and `>` - div with a class +* `<"#id.class"` and `>` - div with an id and class + +Example 1: + +``` +<"wrapper"flipt> +``` + +This results in the following DOM structure: + +``` +
+ {filter} + {length} + {info} + {paging} + {table} +
+``` + + +Example 2: + +``` +ip> +``` + +This results in the following DOM structure: + +``` +
+ {length} + {filter} +
+ {table} +
+ {info} + {paging} +
+``` + +All options (with the exception of the `t` (table) option can be specified multiple times, for if you want to show the same control multiple times (pagination at the top and bottom of the table for example). + +Furthermore, note that additional `dt-init dom` options can be added to DataTables through the use of plug-ins. + +In the example below, the table information is moved to the top of the table, and all the interaction elements to the bottom, each wrapper in a container `div`.

+ + +]]> diff --git a/examples_src/basic_init/filter_only.xml b/examples_src/basic_init/filter_only.xml index 605ed6a3..5ff62a75 100644 --- a/examples_src/basic_init/filter_only.xml +++ b/examples_src/basic_init/filter_only.xml @@ -9,18 +9,17 @@ - -Disabling features that you don't wish to use for a particular table is easily done by setting a variable in the initialisation object. In the following example only the filter feature is left enabled (although I've explicitly declared it as enabled). - + diff --git a/examples_src/basic_init/flexible_width.xml b/examples_src/basic_init/flexible_width.xml index c2f34386..801cff49 100644 --- a/examples_src/basic_init/flexible_width.xml +++ b/examples_src/basic_init/flexible_width.xml @@ -12,10 +12,12 @@ $(document).ready(function() { } ); ]]> - -

Often you may want to have your table resize dynamically with the page. Typically this is done by assigning width:100% in your CSS, but this presents a problem for Javascript since it can be very hard to get that relative size, rather than the absolute pixels. As such, if you apply the width attribute to the HTML table tag, this will be used as the width for the table (overruling any CSS styles).

+This example shows a table width width="100%" and the container is also flexible width, so as the window is resized, the table will also resize dynamically.

- +Often you may want to have your table resize dynamically with the page. Typically this is done by assigning `width:100%` in your CSS, but this presents a problem for Javascript since it can be very hard to get that relative size rather than the absolute pixels. As such, if you apply the `width` attribute to the HTML table tag, it will be used as the width for the table (overruling any CSS styles). + +This example shows a table with `width="100%"` and the container is also flexible width, so as the window is resized, the table will also resize dynamically. + +]]> diff --git a/examples_src/basic_init/hidden_columns.xml b/examples_src/basic_init/hidden_columns.xml index 51a9ead8..a7af7c19 100644 --- a/examples_src/basic_init/hidden_columns.xml +++ b/examples_src/basic_init/hidden_columns.xml @@ -10,15 +10,30 @@ $(document).ready(function() { $('#example').dataTable( { "columnDefs": [ - { "targets": [ 2 ], "visible": false, "searchable": false }, - { "targets": [ 3 ], "visible": false } + { + "targets": [ 2 ], + "visible": false, + "searchable": false + }, + { + "targets": [ 3 ], + "visible": false + } ] } ); } ); ]]> - -There are times when you might find it useful to display only a sub-set of the information that was available in the original table. For example you might want to reduce the amount of data shown on screen to make it clearer for the user. This hidden data can still be filtered upon allowing the user access to that data (for example 'tag' information for a row entry), or this can be disabled. In the table below both the platform and engine version columns have been hidden, the former is searchable, the latter is not. - + diff --git a/examples_src/basic_init/index.xml b/examples_src/basic_init/index.xml index 2cc6d041..10eab6a1 100644 --- a/examples_src/basic_init/index.xml +++ b/examples_src/basic_init/index.xml @@ -12,8 +12,10 @@ $(document).ready(function() { } ); ]]> - - DataTables has most features enabled by default, so all you need to do to use it with one of your own tables is to call the construction function (as shown below). - + diff --git a/examples_src/basic_init/language.xml b/examples_src/basic_init/language.xml index 0d895750..16578f5d 100644 --- a/examples_src/basic_init/language.xml +++ b/examples_src/basic_init/language.xml @@ -20,8 +20,12 @@ $(document).ready(function() { } ); ]]> - -Changing the language information displayed by DataTables is as simple as passing in a language object to the dataTable constructor. The example above shows a different set of English language definitions to be used, rather than the defaults. - + diff --git a/examples_src/basic_init/multi_col_sort.xml b/examples_src/basic_init/multi_col_sort.xml index 1a4231dc..6ada6539 100644 --- a/examples_src/basic_init/multi_col_sort.xml +++ b/examples_src/basic_init/multi_col_sort.xml @@ -5,39 +5,32 @@ -Multi-column and custom sort +Multi-column sorting b) ? 1 : 0)); - }, - - "string-case-desc": function(a,b) { - return ((a < b) ? 1 : ((a > b) ? -1 : 0)); - } -} ); $(document).ready(function() { - /* Build the DataTable with third column using our custom sort function */ $('#example').dataTable( { - "sorting": [ [0,'asc'], [1,'asc'] ], - "columnDefs": [ { - "targets": [ 2 ], - "type": 'string-case' + columnDefs: [ { + targets: [ 0 ], + dataSort: [ 0, 1 ] } ] } ); } ); ]]> - -

As you would expect with a desktop application, DataTables allows you to sort by multiple columns at the same time. This multiple sorting mechanism is always active if the sort initialiser is true (it is by default) and the end user can activate it by 'shift' clicking on the column they want to add to the sort. You can also pass in an array of information using the sorting initialiser, as I have done in the example below there the first column is sorted as the primary column and the second one then used if the elements in the first column match. As many columns as you wish can be added to the sort.

+DataTables also provides a method to add your own sorting functions, to extend those built into DataTables. This can be very useful if you wish to sort on data formats such as currency and non-Javascript standard date formats (this natural sort algorithm is a popular option). This is achieved by extending the jQuery.fn.dataTableExt object with ascending and descending sort functions. In the example below I've added case sensitive sorting functions.

- +DataTables allows sorting by multiple columns at the same time, which can be activated in a number of different ways: + +* User shift click on a column (added the clicked column as a secondary, tertiary etc sorting column). +* On a per-column basis (i.e. sort by a specific column and then a secondary column if the data in the first column is identical), through the `dt-init dataSort` option. +* Using the `dt-init sorting` option to specify a multiple column sort by default (for example `[ [0,'asc'], [1,'asc'] ]`). +* Through the `dt-api order()` API method. + +The ability for the user to shift click to sort multiple columns can be disabled through the `dt-init sortMulti` option. + +The example below shows the first column having a secondary sort applied to the second column in the table. + +]]> diff --git a/examples_src/basic_init/multiple_tables.xml b/examples_src/basic_init/multiple_tables.xml index 898a8c2b..f051a044 100644 --- a/examples_src/basic_init/multiple_tables.xml +++ b/examples_src/basic_init/multiple_tables.xml @@ -12,8 +12,14 @@ $(document).ready(function() { } ); ]]> - -Using standard jQuery selector syntax with DataTables it is trivial to initialise multiple tables with a single line of Javascript, as shown below. All tables are completely independent, but share the parameters passed thought the initialiser object (for example if you specific the Spanish language file, all tables will be shown in Spanish). - + diff --git a/examples_src/basic_init/scroll_x.xml b/examples_src/basic_init/scroll_x.xml index ec1396e1..9e06a404 100644 --- a/examples_src/basic_init/scroll_x.xml +++ b/examples_src/basic_init/scroll_x.xml @@ -2,23 +2,29 @@ + + th, td { white-space: nowrap; } + #demo { width: 600px; } + - +Scroll - horizontal - -

This DataTables horizontal scrolling example shows horizontal scrolling on a DataTable, which is very useful for when you have a wide table, with a large number of columns to display, but want to constrain it to a limited horizontal display area. To enable x-scrolling simply set the scrollX parameter to be whatever you want the container wrapper's width to be (any CSS measurement is acceptable, or just a number which is treated as pixels). Note also that sScrollXInner is used here to force the table to be wider than is strictly needed. You may or may not want to include this parameter depending on your application.

-

Also shown in this example is the use of a 'collapsing scroll table' by using scrollCollapse. When this parameter is set to true, the table size will 'collapse' down to match the number of rows, if the table height is smaller than the scrollable area.

- + diff --git a/examples_src/basic_init/scroll_xy.xml b/examples_src/basic_init/scroll_xy.xml index 1189c410..4cdf2665 100644 --- a/examples_src/basic_init/scroll_xy.xml +++ b/examples_src/basic_init/scroll_xy.xml @@ -2,22 +2,27 @@ + + th, td { white-space: nowrap; } + #demo { width: 600px; } + -Horizontal and vertical scrolling +Scroll - horizontal and vertical - -In this example you can see DataTables doing horizontal and vertical scrolling at the same time. Note also that pagination is enabled, and the scrolling accounts for this. - + diff --git a/examples_src/basic_init/scroll_y.xml b/examples_src/basic_init/scroll_y.xml index eeb9f606..d48956b2 100644 --- a/examples_src/basic_init/scroll_y.xml +++ b/examples_src/basic_init/scroll_y.xml @@ -5,19 +5,25 @@ - +Scroll - vertical - -This example shows the DataTables table body scrolling in the vertical direction. This can generally be seen as an alternative method to pagination for displaying a large table in a fairly small vertical area, and as such pagination has been disabled here (note that this is not mandatory, it will work just fine with pagination enabled as well!). The example is set up to show grid lines using CSS, which is useful for alignment, both for testing and end user usability. To enable y scrolling simply set the scrollY parameter to be whatever you want the container wrapper's height to be (any CSS measurement is acceptable, or just a number which is treated as pixels). - + diff --git a/examples_src/basic_init/scroll_y_infinite.xml b/examples_src/basic_init/scroll_y_infinite.xml deleted file mode 100644 index c8ba523a..00000000 --- a/examples_src/basic_init/scroll_y_infinite.xml +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - - -Infinite vertical scrolling - - - -

This example shows the DataTables table body scrolling in the vertical direction with infinite scrolling. The idea of infinite scrolling means that data will be added to the table dynamically, as and when needed by the user scrolling the table. A sub-set of the data is loaded initially, and more added as needed (technically of course, it is not "infinite" since it will stop loading data at the end of the data set!). Note that pagination much be enabled for infinite scrolling to work, but the pagination controls will not be shown (they could be, but can cause very confusing user interaction).

- -

DataTables' infinite scroll can be used with any of the four data sources supported, and they do not require any modification to work (including server-side scripts).

- - - diff --git a/examples_src/basic_init/scroll_y_theme.xml b/examples_src/basic_init/scroll_y_theme.xml index 8585ab41..14a98c07 100644 --- a/examples_src/basic_init/scroll_y_theme.xml +++ b/examples_src/basic_init/scroll_y_theme.xml @@ -6,19 +6,21 @@ -Vertical scrolling with jQuery UI ThemeRoller +Scroll - vertical with jQuery UI ThemeRoller - + + +]]> diff --git a/examples_src/basic_init/state_save.xml b/examples_src/basic_init/state_save.xml index 1fe2f9c5..da88c909 100644 --- a/examples_src/basic_init/state_save.xml +++ b/examples_src/basic_init/state_save.xml @@ -12,8 +12,17 @@ $('#example').dataTable( { } ); ]]> - -DataTables can use cookies in the end user's web-browser in order to store it's state after each change in drawing. What this means is that if the user were to reload the page, the table should remain exactly as it was (length, filtering, pagination and sorting). This feature is disabled by default, but can be easily enabled using the stateSave initialisation parameter as shown in this example. Note also that the duration of the cookie can be set using the stateDuration initialisation parameter (which is in seconds). - + diff --git a/examples_src/basic_init/table_sorting.xml b/examples_src/basic_init/table_sorting.xml index badbda02..860c040d 100644 --- a/examples_src/basic_init/table_sorting.xml +++ b/examples_src/basic_init/table_sorting.xml @@ -14,8 +14,14 @@ $(document).ready(function() { } ); ]]> - -With DataTables you can alter the sorting characteristics of the table at initialisation time. Using the sorting initialisation parameter, you can get the table exactly how you want to present the information. The sorting parameter is an array of arrays where the first value is the column to sort on, and the second is 'asc' or 'desc' as required (it is a double array for multi-column sorting). The table below is sorted (descending) by the CSS grade. Note also that the 'Engine version' column is automatically detected as a numeric column and sorted accordingly. - + diff --git a/examples_src/basic_init/themes.xml b/examples_src/basic_init/themes.xml index 6960ab2b..3e579bf9 100644 --- a/examples_src/basic_init/themes.xml +++ b/examples_src/basic_init/themes.xml @@ -16,8 +16,14 @@ $(document).ready(function() { } ); ]]> - -Styling widgets such as DataTables can often take a considerable amount of time to fully integrate it into your site / application, with the demo styles as a base. This holds true for all widgets, and the jQuery UI team have addressed this issue by introducing themes through their excellent ThemeRoller. DataTables has full support for ThemeRoller created themes, all you need to do is enable the jQueryUI flag in the initialisation object, and the required mark-up and classes will be added by DataTables. - + diff --git a/examples_src/basic_init/zero_config.xml b/examples_src/basic_init/zero_config.xml index 2cc6d041..f326e8b4 100644 --- a/examples_src/basic_init/zero_config.xml +++ b/examples_src/basic_init/zero_config.xml @@ -12,8 +12,10 @@ $(document).ready(function() { } ); ]]> - - DataTables has most features enabled by default, so all you need to do to use it with one of your own tables is to call the construction function (as shown below). - +