Git repo structure update

One of the great challenges of maintaining any complex project is that of organisation and DataTables is no exception. The project is primarily split between the core library, extensions and plug-ins. This modular approach for adding features to DataTables works well, but where it currently proves to be difficult is the integration with the various styling libraries supported by DataTables.

DataTables provides its own stylesheets, but it can also make use of the styles offered as part of Bootstrap, Zurb Foundation and jQuery UI ThemeRoller. This ability to be styled by many different frameworks is a fundamental aspect of DataTables and it should be as simple as possible to use DataTables in these environments.

Currently it is not - but this post will discuss how this will be addresses in up coming versions of DataTables. If you have been digging around in the various DataTables Git repositories you might have already seen some of these changes - this blog post will clarify exactly what those changes are and why they are being made.

I expect this blog post to act as a reference and guidance document during the work involved in updating DataTables and all of its extensions, so it is rather "dry and boring", but the work presented here does form a key part of DataTables' future.

The current state

At the moment, to use DataTables with any of the supported styling libraries you need to include the required Javascript libraries in your code and also the DataTables integration files for your style library.

The integration files work by setting defaults in the Javascript files and augmenting the style library options to match what DataTables needs.

Generally this approach works very well, as can be seen by the fact that DataTables supports three completely different styling libraries as well as its own default styles. However, there are two areas where this often goes wrong:

• For developers using the software, it isn't always clear that the default DataTables styles should not be included as well as the integration styles
• For DataTables developers updating the integration files, it is separated and not release specific to the various extensions. For example the Bootstrap integration for TableTools is embedded into the general integration file, so it might not get updated at the same time as TableTools or the releases might be out of sync.

The solution

The solution is to move the integration options for each component into its host library and provide a set of rules that the file names should follow. This ensures that developers have access to the software that they need to update immediately, releases are atomic and there is a consistent method of including the required files for each styling library.

The downside to this approach is that it increases the number of files that are required quite significantly if you use a large number of extensions. However, this is outweighed by the fact that the consistent naming provides the ability to programmatically combine files - more on this topic in a future blog post!

For the remainder of this post I will focus only on the dry details of the repository file structure.

File name rules

1. File names are hierarchical, with the most significant software name on the left
2. Each plug-in adds its own name to the hierarchy (on the right), unless it is identical the previous item in the hierarchy
3. jQuery is top of the hierarchy tree
4. The hierarchy is dot separated
5. The file name is limited to just the last two elements in the hierarchy.
6. Style framework integration files have the framework name appended as the last element in the hierarchy
7. DataTables provided styles count as a framework (the Javascript defaults are suited for their style framework, so there is never the need for a Javascript DataTables integration file!)
8. The extension .min is used to represented a minified file (appended before the file extension)
9. The file name will always have an extension (e.g. .css or .js).
10. The file name is camelCase - i.e. all lower-case except where two words have been combined

Example - DataTables

Consider the case of DataTables - it is a plug-in for jQuery so its main Javascript file is called jquery.dataTables.js. The Bootstrap integration file would be called jquery.dataTables.bootstrap.js, but rule 5 truncates this to dataTables.bootstrap.js. So the DataTables Javascript directory would consist of:

• jquery.dataTables.js
• dataTables.bootstrap.js
• dataTables.foundation.js
• dataTables.jqueryui.js

For styling the CSS files are similar to the integration files, so we have:

• jquery.dataTables.css
• dataTables.bootstrap.css
• dataTables.foundation.css
• dataTables.jqueryui.css

Example - Responsive

Let's now consider the Responsive extension. For Responsive there is no need for Javascript integration files, so we simply have:

• dataTables.responsive.js

For the CSS we do require integration files so we have:

• responsive.dataTables.css
• responsive.bootstrap.css
• responsive.foundation.css
• responsive.jqueryui.css

Repository status

At the time of writing this post, only the DataTablesSrc, FixedColumns and Responsive repositories have been updated to conform to these new rules.

As development on DataTables continues, the other repositories will follow shortly.