Lazy load option for large document libraries
The lazy load option in Document Library Pro uses AJAX to speed up the list of documents for sites with large numbers of documents.
What is lazy load?
By default, Document Library Pro will load all of the data into the table when it is first displayed on screen. If you have more rows than can fit on a single page of results (e.g. you are showing 20 rows per page and you have 30 results) then it will create multiple pages with pagination links at the bottom of the table. However, all the documents on all the pages are loaded at the same time.
For large numbers of documents, this can cause a hit on performance as all matching documents need to be fetched from the database and then formatted by Document Library Pro. This can cause slower page load times and - for very large data sets - may even result in a server or database error when attempting to load the table.
If you’re worried about performance, then we recommend enabling the “lazy load” option. This will load the documents one page at a time via AJAX rather than all at once. As the user navigates between the pages of results, they will see a “Processing” message displayed (briefly) while the next documents are loaded from the database.
How to enable lazy load
To use lazy load, either enable it on the plugin settings page or add
lazy_load="true" to the Document Library Pro shortcode.
How to disable lazy load
To deactivate lazy load, either disable it on the plugin settings page or add
lazy_load="false" to the Document Library Pro shortcode.
Implications of using lazy load
Enabling lazy load means that all post fetching, searching, and sorting is handled by the server rather than in the browser. As a result, lazy loaded tables behave differently from non-lazy loaded tables:
- The filter dropdowns work differently:
- They will display all possible items, regardless of the content of the table. For example, a ‘Topic’ filter will display all the topics that you use anywhere on your website (excluding any empty topics that don't have any documents) - including topics that aren't used for the documents in the current table. If you are concerned about this then we recommend creating a unique taxonomy for the documents in each table on your site, and only display filter dropdowns for the taxonomies relating to those documents.
- They will work independently of one another. When you select an item from one filter, the content of the other filter will not update. All possible items will still be displayed in each filter, regardless of what is selected in the other filters.
- The search box works differently - instead of searching the contents of the table, the search box above the table looks in the post title, excerpt and the full content of the post (regardless of whether these are present as columns in the table). The search box does not look in any other columns of the table, such as attributes, custom fields, taxonomies, etc. If you want to search by other data then we recommend one of the following workarounds:
- Add the extra data to the title, excerpt or content fields so that it will be searchable in lazy load. Please note that the search box will still look in the title, excerpt and content fields even if these aren't columns in your table.
- If you want people to be able to find documents by category, tag or custom taxonomy, then you can list these as filter dropdowns above the table instead of using the search box.
- Table sorting is limited - you can only sort the table by ID, name, price, or date. The
sort_byoption is also limited - please see the sort_by documentation for details.
- The search_on_click feature only works for tags, categories and taxonomies, but not authors. This means that users can't click on an author to filter the table.
Why does lazy load work differently?
The above differences are due to the way in which WordPress interacts with the database, and are unavoidable.
The searching in a non-lazy loaded table is handled client-side, directly in the browser. The plugin simply looks at the contents of the HTML on the current page, and displays the appropriate results.
In contrast, the searching in a lazy loaded table uses the native search function of WordPress itself, which is handled by the server when the documents are retrieved from the database. A lazy loaded table doesn't know which documents are in the table (because only the current page of the table has been loaded), so it's not possible to look within the table to search, sort, filter, etc. and the plugin must do this using other methods. WordPress itself has pre-indexed all the data in the
wp_documents database table, which includes the post title, excerpt and content. That's why a lazy loaded table can quickly search by title, excerpt and content, but unfortunately not by other fields such as categories.