1. Document Library Pro
  2. Document Library Options

Listing specific documents by category, tag, and more

Document Library Pro will list all documents on your document library page - either listed in a single table, or structured into category-based folders. You can also use the [doc_library] shortcode to list specific documents only. This page describes the shortcode options which you can choose to control which documents are listed in each table on your site.

You can list documents with a specific category, tag, status, custom taxonomy term, custom field or date (year, month or day). You can also show or hide specific documents based on their ID, and exclude certain categories.

Document category

The doc_category option lets you choose which documents are listed.

You should specify the category slug or ID – this can be found under the Documents → Categories menu in the WordPress dashboard. You can also specify multiple categories to display – either separated by commas or by a plus sign (+). If you use commas it means “documents in this Category A or Category B”. If you use a plus, it means “documents in Category A and Category B”.

For example, to display documents which are in the “design” category or in the “print” category, use: [doc_library doc_category="design,print"]

To display documents which are in the “design” category and in the “print” category, use: [doc_library doc_category="design+print"]

Can I list categories and sub-categories separately?

The default shortcode displays documents in a single list, regardless of whether they are in a parent category or child category. You can enable the folders option to structure the document into nested folders based on their categories and sub-categories.

Alternatively, you can manually list documents as categories and sub-categories by adding multiple shortcodes to the page. Each table should list documents from a different category or subcategory, and you can divide up the page by adding the category name as a subheading above each table. For example, this will be useful if you want all the tables to be visible without having to click on a folder to open them one at a time; or if you're using a page builder plugin to structure your page into tabs, toggles or accordions and want to list documents from a different category in each section.

Document tag

The doc_tag option selects documents based on their document library tags. If you’re displaying pages or other custom post types, this option has no effect and you need to use the ‘term‘ option instead (see below).

Use the tag slug or tag ID – you can find this in WordPress under the Documents → Tags menu.

As with categories, you can use one tag or several tags, and you can use commas or a plus sign to denote how tags should be checked. Using commas means “documents with this tag OR that tag”; using the plus sign (+) means “documents with this tag AND that tag”. You can’t mix and match commas and pluses – it’s one or the other.

Example 1: Display documents with tag “awesome”: [doc_library doc_tag="awesome"][/no_shortcodes]

Example 2: Display documents with tags “cool”, “awesome” or “good”: [no_shortcodes][doc_library doc_tag="cool,awesome,good"]

Example 3: documents with tags “cool”, “awesome” and “good”: [doc_library doc_tag="cool+awesome+good"]

Custom taxonomy term

The term option creates a table that only lists documents with the the specified term or terms. The taxonomy that you specify here doesn’t have to be a column in your table.

Use the format: term="<taxonomy slug>:<term slug or ID>". You can enter one term or multiple terms and, as with categories and tags, you can separate terms using a comma (,) or a plus sign (+) to denote whether the documents have any of the terms specified or all of them.

You need to prefix this option with the slug of the taxonomy followed by a colon. For example, to display documents that are tagged with the year “2021”, we would use:
[doc_library columns="title,content" term="year:2021"]

To display documents with multiple terms, separate terms by a plus sign (AND) or a comma (OR). If you are selecting from several custom taxonomies, you need to add the taxonomy slug before each term.

The following example will display documents with a document_type of policy or memo:
[doc_library term="document_type:policy,memo"]

The following example will display documents with a document_type of memo and a document_status of approved:
[doc_library term="document_type:policy+document_status:approved"]

If you haven't created your custom taxonomies yet, check out our article on how to do this.

Custom field

The cf option is used to select documents based on a custom field value. You should use the format cf="<field name>:<field value>" when using this option. As with the above options you can enter one custom field to check, or several, and can separate them using a comma or a plus sign (see categories or tags for more details).

For example, if you wanted to display the documents for cars which are either blue OR are Audis, you would use:
[doc_library cf="color:blue,make:audi"]

If you wanted to list documents with either of two values from the same custom field (for example cars that are blue or red) then you would use:
[doc_library cf="color:blue,color:red"]

However if you wanted to select the blue Audis (i.e. have color = blue AND make = audi) you would use:
[doc_library cf="color:blue+make:audi"]

If you haven't created your custom taxonomies yet, check out our tutorial on how to do this.

Custom fields added using the Toolset plugin

If you're using Toolset to create your custom fields, then you need slightly different syntax to display them in the document library.

Toolset adds wpcf- to the start of the custom field name, so if you create a custom field called 'color' with a value of 'blue' then the correct syntax will be wpcf-color:blue. This means that if you want to create a table displaying documents with a custom field value of 'blue' then you would need to add it as follows:
[doc_library cf="cf:wpcf-color:blue"]

Status

The status option displays documents in the table based on their status.

The default status is publish. The other options are draft, pending, future, private or any. Pending documents are those pending a review. Future documents are those scheduled to be published at a future date. Private documents have their visibility set to Private which means they can only be viewed by the document author or other administrators.

You can also use a list of document statuses separated by commas, for example:
[doc_library columns="title,author,doc_categories" status="publish,draft"]

See also: How to automatically expire documents and remove them from the library on a certain date.

Display documents based on when they were published

The following three options control which documents are displayed based on the date they were published.

Please note that these options use the year when you published the document post on your website, which may be different from when your organization published the document internally (for example). You can change the publish date for each document, either by using 'Quick Edit' on the main list of documents; or in the 'Publish' section in the top right corner of the 'Edit Document' screen.

Year

The year option can be set to limit documents to a specific year. E.g.[doc_library year="2021"]

Month

Selects documents from a specific month. You should use a number here between 1 and 12. You can combine this with the year or day options if you want more fine-grained control, e.g. [doc_library year="2021" month="11"]

Day

Selects documents from a specific day in the month. You should use a number between 1 and 31, and as above, you can combine this with the year or month options, e.g.[doc_library month="4" day="25"]

Author

The author option displays documents from a specific author. Use the author ID or a list of IDs.

Please note that this option uses the author of the document post on your website, who must be a user on your website. This may be different from the author of the original document. You can change the author on the 'Edit Document' screen.

If you wish to list documents from an author who is not a user on your WordPress site, then you can create a custom field and use the cf: option instead.

Example[doc_library author="1,4"]

Exclude

The exclude option can be used to exclude documents from your library based on their database ID. You can enter one ID or a list or IDs.

Example: [doc_library columns="title,content" post_type="page" exclude="23"]

Include

The include option can be used to show only specific documents in your table. You can enter one post ID or a list or IDs separated by commas. Note that include and exclude are mutually exclusive – if you set one, the other will be ignored.

Example displaying 4 specific documents: [doc_library include="23,45,67,90"]

Exclude document category

The exclude_doc_category option is used to exclude entire categories of documents from your table. You can use category IDs or slugs, and it can be one category or a comma-separated list.

Example: [doc_library exclude_doc_category="3,6"]
Example: [doc_library exclude_doc_category="design"]

Exclude taxonomy term

The exclude_term option is used to exclude documents with a specific taxonomy term. You can use taxonomy term IDs or slugs, and it can be one category or a comma-separated list.

Example: [doc_library exclude_term="label:staff"]
Example: [doc_library exclude_term="label:3,6"]
Example: [doc_library exclude_term="label:staff,region:devon"]

Was this article helpful?

Related Articles

Still need help?
If searching the knowledge base hasn't answered your question, please contact support.