2. Document Library Pro settings
The Document Library Pro plugin settings pages (Documents → Settings) let you configure your document libraries. You can also configure the main settings in the plugin setup wizard, which opens when you first activate the plugin and can be relaunched from the settings page.
Use the following video and the written information below to learn about the settings and how to use them. Please note that we have added some extra options since creating the video, which are documented below.
Tip: The options on the plugin settings page set the defaults for all of your document libraries. If needed, you can override most of the options using the shortcode options. This allows you to choose different settings for each list of documents on your site.
General tab
The General tab contains options which will affect all your document libraries, where you are using the table or the grid layout.
License key
Enter your license key here. This is essential for the plugin to work.
Document library
Control the behavior of the links to your documents.
Link to document
If you have included a link field in the document library, then the 'Link to document' option will display a link to the document. Use the link destination option below to choose whether this link goes to the document itself, or to the single document page.
If the document library includes a link field but 'Link to document' is disabled, then the following will happen:
- If the Preview option (below) is enabled then the preview button will appear, with no link to the actual document.
- If Preview is disabled then nothing will appear. This may look strange if you are using the table layout because the link column will be empty, so we recommend removing the link column from the 'Document Tables' tab of the settings page.
Link style
If you have enabled document links, then this option controls the appearance of the links in the link field:
- Button with text (the default) - a button containing the 'Link text' which you can set below.
- Button with icon and text - a button containing the 'Link text' which you can set below, plus a download icon.
- Button with icon - a button containing a download item and no text.
- Download icon only - a download icon with no text, which is not within a button.
- File type icon - automatically displays an icon representing the file type, or a generic icon for uncommon file types.
- Text link - a text-only link.
Link text
If the link style is set to 'button' or 'text link' then you can control the text that appears in the link field. The default is 'Download'.
Link destination
Choose what happens when someone clicks on a link to the document. This only affects the links in the 'Link' field of the document library, and not other clickable fields such as the document title.
- Direct access - this is the default and opens the document, rather than taking users to the single document page.
- Open single document page - takes users to the single document page, from which they can click on a link to the actual document if required.
Link target
Choose whether or not you would like documents to open in a new browser tab. This only affects the links in the 'Link' field of the document library, and not other clickable fields such as the document title.
Clickable fields
Choose whether users can access the single document page by clicking on other fields in the document library. The following fields can be formatted as links: id, title, doc_categories, doc_tags, doc_author, image, and any custom taxonomy.
Enter all to add links to all possible fields, none to disable all links, or add a comma separated list (without spaces) of the specific fields that should be clickable.
Document data
Document fields
Select which fields you would like to use for your documents. These fields will be displayed on the single document page if you are using it; on the Add/Edit Document page; and also the front end document submission form. The content, excerpt and featured image can also be displayed in your document lists.
- Content - This field can be used for a description of the document, or to add the full content of the document if you want it to be available online without having to download it.
- Excerpt - Use this field for a brief summary of the document.
- Featured image - Upload an image if you plan to include an image in the document library.
- Comments - Allow visitors to add comments for each document, just like they can with WordPress blog posts.
- Custom fields - Enable the default WordPress custom fields feature so that you can add additional fields for your customers.
- Authors - Record the author of the document (note: this is different from the WordPress user who added the document).
In addition to these fields, your documents will have all the standard WordPress fields such as the title, content, date, author, document categories, and document tags.
If you would like to store extra information about your documents then we have provided an article about how to do this.
Document slug
Change the URL structure of your individual document pages by typing in your custom slug in the text field.
For example, you can change the default slug from https://documentlibrary.barn2.com/document/diversity-policy to any other custom slug such as https://documentlibrary.barn2.com/policies/diversity-policy.
Document library page
Select which page you wish to use as your main document library page (if required).
When you install the plugin, it automatically creates a page called ‘Document Library’ and selects it here. You can select a different page if required.
The plugin will add the shortcode [doc_library] to whichever page is selected here. It lists all your documents using the default options. You can customize these settings below, or directly in the shortcode for more fine-grained control.
You can click the 'View page' link to visit the selected page in the front end.
Search page
If you have used a widget or shortcode to add a standalone document search box anywhere on your site, then you need a page to display the results on. A 'Document Search Results' page has been automatically generated for you, and is selected here. If you prefer, then you can select a different page to use for the document search results.
Default layout
Here's a video we made about all of the main layout and display options available in Document Library Pro. Read below for written instructions.
Choose the default layout for your lists of documents. The options are:
- Table - This is the default option and lists documents in a tabular layout with multiple columns of information. There are options for the table layout on the 'Document Tables' tab of the settings page.
- Grid - Displays documents in a tile-based grid layout. The options for the grid layout are on the 'Document Grid' tab of the settings page.
Document preview
Document preview
Enable this option to enable users to preview documents in a lightbox before (or instead of) downloading them. The preview link will appear in the link field of the document library, and also on the single document page.
Preview style
Choose a style for the preview buttons:
- Button with text
- Button with icon and text
- Button with icon
- Icon only
- Text link
Preview button text
If you have chosen the 'Button with text', 'Button with icon and text' or 'Text link' style for the preview buttons, then you can replace the default 'Preview' text with any other text of your choice.
Folders
Enable this option to structure your document libraries into category-based folders.
If you have multi-level categories then it will work like this:
- All the top-level categories will be listed as closed folders when the page first loads.
- When a user clicks on a folder, it will open to contain documents that are only in that top-level category; with folders underneath for the sub-categories.
- When the user clicks on a sub-category folder, they will see any documents which are only in that sub-category; or they will see any sub-sub categories listed as folders underneath.
Sorting folders
Sort the folders by folder name, category ID, category slug, category order (menu order), and the number of terms. Select the sorting direction to choose the sorting order (i.e. ascending or descending).
Open folders
By default, the folders will be closed on when the document library first loads so that customers can click on a folder name to open it. You can change this so that any or all of the folders are loaded open by default. The options are:
none- all folders are closed.open- all folders are open.- specific categories - enter a comma separated list of the category ID's of the folders that you want to display open by default.
Customize folder icon
Enable this to display some hidden options to restyle the folder icon which appears to the left of each collapsible category in the document library:
- Top-level folder color - Choose a color for the main folders (i.e. your top level document library categories). The default is yellow.
- Subfolder color - Choose a color for the lower level folders which appear when the customer views a folder which has sub-categories. The default is black.
- Closed and open folder icon - If you would like to replace the default folder icons then you can do this by pasting the code for an SVG file containing the replacement logo. The plugin uses SVG's because these are retina icons instead of images, which is better for performance and compatibility on different devices.
Library content
Image lightbox
If you have included images in the document library then enabling this option will make the featured image open in a lightbox/popup when someone clicks on it.
If you untick this box then clicking on an image will link visitors to the document instead. You can disable this behavior using the clickable fields option, above.
Shortcodes
Tick this box if you want content added by other shortcodes to appear within the text fields in the document library.
For example, you might be using a button shortcode to add other types of button; embedded audio or media players; icon shortcodes; etc. Alternatively, you might have added the content of a document using the Gutenberg editor and want to display the fully formatted information on the document library page.
Excerpt length
If you are displaying the document excerpt in the library, then this option controls the number of words that will appear. Enter a whole number.
Content length
If you are displaying the document content in the library, then this option controls the number of words that will appear. Enter a whole number.
Search
Search box
Positions, shows or hides the keyword search box.
Reset button
Positions, shows or hides the reset button which lets customers reset the table after performing a search or filter.
Note: If you are using the Folders layout then the reset button cannot be hidden. This is because the reset button is essential for returning to the folder view if the search box is enabled.
Document library controls
Search filters
This option controls whether or not filter dropdowns will appear above the document library. You can add filters for document categories, tags, author or any custom taxonomy.
- Disabled – no filters will be displayed.
- Enabled – shows all possible filters based on the contents of the document library. (This will only display filters if some of your document content fields are filterable, e.g. if the library contains categories, tags or custom taxonomies.)
- Custom – add a comma separated list (without spaces) of which filters to add.
Page length
Positions, shows or hides the ‘Show [x] documents’ dropdown.
Number of documents
Documents per page
Enter a whole number to control how many documents appear on each page of the library. If there are more documents than the number of rows per page then pagination links will appear linking to the other pages.
Pagination type
Choose a style for the pagination buttons.
Pagination position
Positions, shows or hides the pagination buttons.
Totals
Positions, shows or hides the label which displays the number of documents (e.g. ‘Showing 1 to 10 of 50 documents’).
Sorting
Sort by
Choose an option for how the documents will be sorted when it first loads. (If you are using the table layout then visitors can also sort the document library by clicking on any column header.)
Sort direction
Choose whether the documents will be ordered in ascending or descending order.
Front end document submission
The following options control what happens when people submit documents via the front end submission form:
- Enable admin email - Enable this to send an email to the administrator (as set under Settings → General) whenever a new document is submitted.
- Enable moderation - Enable this to hold newly submitted documents for moderation by an administrator. If the email is enabled then this will include instructions on how to approve it. The document will not be added to the library until after it has been approved.
Version control
Enable the version control option to track previous versions of a downloadable document. When you enable version control, the following happens:
- A new 'Replacing files' option appears underneath, which allows you to choose what happens to previous versions:
- When replacing a file, keep the original in the Media Library - Enable this to keep all versions of a file so that you can view them and roll back to them if needed in the future.
- When replacing a file, delete the old version from the Media Library - Enable this to automatically remove old versions from the Media Library whenever you replace a document.
- A new 'Version editor' section appears on the Edit Document screen. You can use this to view previous versions, rename versions, and so on.
Document Tables tab
These options set defaults for your document tables. If you are only using the grid layout then you can ignore them.
Columns
Add a comma separated list (without spaces) of the columns to appear in the table.
The available columns are: id, title, content, excerpt, image, date, date_modified, doc_author, doc_categories, doc_tags, file_size, file_type, status, link, or any custom field or taxonomy.
Example: title,content,date
Image size
This option controls the size of the featured image in the image column. Enter the required image size in pixels, e.g. 50×70 will set the image to 50 pixels wide by 70 pixels high.
Document links (table layout only)
Accessing documents
Choose from the following options to control how users will access the document:
- Link to document - Display a button/icon/text link (depending on the 'Link style', below) linking to the document.
- Multi-select checkboxes - Display a checkbox next to each document so that users can download multiple items at once.
- Both - Display a link to the document and a checkbox.
Multi-download button
If you have enabled the 'Multi-select checkboxes' in the 'Accessing documents' option above, then you can choose whether to display the 'Download Selected Documents' button above or below the table, or both.
Multi-download button text
This option lets you replace the 'Download Selected Documents' text in the multi-download button with any other text of your choice.
Loading & performance
Lazy load
Tick this box if you want to load the contents of the document library table one page at a time, or if you want the list of documents to load after the rest of the content on your page. This option boosts performance for big document libraries but there are some limitations, so please read the full article about lazy load.
Document limit
Enter a whole number to specify the maximum number of documents that can appear in the table.
Warning: If you are not using the lazy load option then increasing this number could cause performance issues or even server crashes. For big document libraries, we recommend activating lazy load so that only one page of documents are loaded at a time. If you do this then the document limit option is not applicable.
Caching
This option allows the contents of your document tables to be cached to improve performance and speed up page load times.
If you tick the 'Caching' box then you can also set the 'Cache Expires After' time to control how often the cache is cleared. Enter a whole number of hours.
Design
Default
The table styles (e.g. font size and color) will automatically be inherited from your theme.
Custom
Enable this option to override the default styling. You can change the styling of the following elements of the tables:
- External, header and body borders - Color and width
- Header background - Color
- Header text - Color and size
- Main background - Color
- Alternating background - Color
- Body text - Color and size
- Spacing - Controls the amount of padding to add around the contents of each cell in the table
To change the color, select from the color picker or add any hexadecimal color value (e.g. #757575). To change the size, use the up/down arrows or enter the size in pixels. Tip: If you want to add an RGB color then you can use a color convertor to get the right value.
You can add more styling using additional CSS.
Document Grid tab
These options set defaults for the document layout. If you are only using the table layout then you can ignore them.
Library content
Display
Enable all the fields that you wish to display in the grid of documents.
The available columns are: image, title, file type, file size, download count, categories, excerpt/content, document link, and custom fields.
Tip: If you want to display additional information then we recommend using the table layout instead.
Number of Columns
Select the number of columns from the dropdown list to limit the grid layout columns on the page. You can select Auto-size to make the grid columns adjust depending on the device screen and page spacing.
Design
Background color
If you are displaying file type icons instead of images at the top of each tile then you can change the background color that appears behind them.
To change the color, select from the color picker or add any hexadecimal color value (e.g. #757575). Tip: If you want to add an RGB color then you can use a color convertor to get the right value.
Category background color
If you are displaying document categories in each tile then you can also change the color that appears behind the category names.
You can add more styling using additional CSS.
Single Document
Select the fields to display on the single document page by enabling the checkboxes.
The available fields are: excerpt, featured image, comments, categories, tags, authors, file type, custom fields, and download count.
Next steps
The plugin settings page lets you set defaults for the most widely used options. You can override these and use additional options directly in the document library shortcode. Please see the complete list of shortcode options.
Next, it's time to start adding documents to your document library!
Adding Documents