The $dotcontent Velocity Viewtool is used to pull individual content items or lists of content from the content repository via Velocity, using Lucene queries.
The following example shows how the dotcontent Viewtool is mapped in the toolbox.xml file:
<tool>
<key>dotcontent</key>
<scope>request</scope>
<class>com.dotcms.rendering.velocity.viewtools.content.ContentTool</class>
</tool>
Methods
There are many different methods to pull content using the $dotcontent tool. More information on each method can be found below.
| Method | Return Type | Content Returned |
|---|---|---|
$dotcontent.pull() | List of content objects | All content which matches the specified Lucene query |
$dotcontent.pullPerPage() | List of content objects | All content matching the specified query, paginated |
$dotcontent.pullRelatedField() | List of content objects | Related content matching the specified parameters. |
$dotcontent.pullRelated() | List of content objects | Deprecated; use pullRelatedField(). Related content matching the specified parameters. |
$dotcontent.pullPersonalized() | List of content objects | Content matching the specified parameters, personalized for individual users |
$dotcontent.query() | List of ids and inodes | The identifiers and inodes (only) of all content matching the specified query |
$dotcontent.count() | Integer | A count (only) of how many content items match the specified query |
$dotcontent.find() | Single content object | An individual content item specified by identifier |
$dotcontent.load() | Single content object | Similar to find(), but loads lazily. |
$dotcontent.loadType() | Single content type object | JavaScript Only. Returns an object representing a Content Type. |
Pull
The basic multi-item pull operation. For more information, see Pulling and Displaying Content.
| Argument | Type | Details |
|---|---|---|
| Query | String | Lucene Query |
| Offset | Integer | Optional. Indicates the number of results to skip; useful for building your own pagination. Defaults to -1. |
| Limit | Integer or Numeric String | The number of items to return. A value of 0 returns the maximum of 10,000 results. |
| Sort | String | Comma separated list of sort parameters comprised of an indexed variable, a space, and then either asc for ascending or desc for descending. |
Examples:
## $dotcontent.pull(String query, int offset, int limit, String sort)
$dotcontent.pull("+contentType:Blog", -1 , 0, "modDate desc")
## $dotcontent.pull(String query, int limit, String sort)
$dotcontent.pull("+contentType:Blog", 5, "modDate desc")
## $dotcontent.pull(String query, string limit, String sort)
$dotcontent.pull("+contentType:Blog", "10", "modDate desc")
Pull Per Page
pullPerPage() is similar to pull(), but simplifies the pagination process slightly by handling the offset math itself; just specify how many items are on each page, and which page you're on.
| Argument | Type | Details |
|---|---|---|
| Query | String | Lucene Query |
| Current Page | Integer | Indicates which page of results to return, with 1 as the first page. |
| Contents Per Page | Integer | The number of items to return per page. A value of 0 returns the maximum of 10,000 results. |
| Sort | String | Comma separated list of sort parameters comprised of an indexed variable, a space, and then either asc for ascending or desc for descending. |
Examples:
## Just the one method format:
## $dotcontent.pullPerPage(String query, int currentPage, int contentsPerPage, String sort)
$dotcontent.pullPerPage("+contentType:htmlpageasset" , 20, 3, "modDate desc")
Pull Related Field
Pulls all related content specified in the given Relationship field. For more information, see Pull and Display Related Content.
| Argument | Type | Details |
|---|---|---|
| Contentlet Identifier | String | The id of the contentlet containing the relatonship field. |
| Field Variable | String | The relationship field in the format ContentType.Field |
| Condition | String | Lucene Query specifying additional limits on which content should be shown. Can be null. |
| Limit | Integer | Optional. The number of items to return per page. A (default) value of 0 returns the maximum of 10,000 results. |
| Offset | Integer | Optional. Indicates the number of results to skip; useful for building your own pagination. Defaults to -1. |
| Sort | String | Optional. Comma separated list of sort parameters comprised of an indexed variable, a space, and then either asc for ascending or desc for descending. |
Examples:
## pullRelatedField(String contentletIdentifier, String fieldVariable, String condition, int limit, int offset, String sort)
$dotcontent.pullRelatedField("a7df3f39-a18a-4b16-b369-aa9d7acb0b27", "Blog.author", null, 0, 0, "modDate desc")
## pullRelatedField(String contentletIdentifier, String fieldVariable, String condition, int limit, String sort)
$dotcontent.pullRelatedField("a7df3f39-a18a-4b16-b369-aa9d7acb0b27", "Blog.author", "+BlogAuthor.lastName:Smith", 0, "modDate desc")
## pullRelatedField(String contentletIdentifier, String fieldVariable, String condition, String sort)
$dotcontent.pullRelatedField("a7df3f39-a18a-4b16-b369-aa9d7acb0b27", "Blog.author", "+BlogAuthor.lastName:Smith", "modDate desc")
## pullRelatedField(String contentletIdentifier, String fieldVariable, String condition)
$dotcontent.pullRelatedField("a7df3f39-a18a-4b16-b369-aa9d7acb0b27", "Blog.author", null)
Pull Related (Deprecated)
Note: Support for legacy relationships is long deprecated and will be removed soon. Please use standard relationship fields, which can either be called as properties of a contentlet (
$con.relField) or throughpullRelatedField().
## $dotcontent.pullRelated(String relationshipName, String contentletIdentifier,
## String condition, boolean pullParents, int limit, String sort)
$dotcontent.pullRelated('myRelationship', 'asbd-asd-asda-asd', '+myField:someValue', false, 5, 'modDate desc')
Pull Personalized
Pulls content that is automatically sorted according to personalized info stored in the visitor object. For more information, see Pull Personalized Content.
| Argument | Type | Details |
|---|---|---|
| Query | String | Lucene Query |
| Limit | Integer or Numeric String | The number of items to return. A value of 0 returns the maximum of 10,000 results. |
| Offset | Integer | Optional. Indicates the number of results to skip; useful for building your own pagination. Defaults to -1. |
| Secondary Sort | String | Optional. Comma separated list of sort parameters comprised of an indexed variable, a space, and then either asc for ascending or desc for descending. |
Examples:
## $dotcontent.pullPersonalized(String query, int limit, int offset, String secondarySort)
$dotcontent.pullPersonalized("+contentType:Blog", 0, -1, "modDate desc")
## $dotcontent.pullPersonalized(String query, int limit, String secondarySort)
$dotcontent.pullPersonalized("+contentType:Blog", 0, "modDate desc")
## $dotcontent.pullPersonalized(String query, String limit, String secondarySort)
$dotcontent.pullPersonalized("+contentType:Blog", "5", "modDate desc")
## $dotcontent.pullPersonalized(String query, int limit)
$dotcontent.pullPersonalized("+contentType:Blog", 15)
## $dotcontent.pullPersonalized(String query, String limit)
$dotcontent.pullPersonalized("+contentType:Blog", "10")
Query
Returns a list of objects containing identifiers and inodes of matching content objects; does not return the full objects.
| Argument | Type | Details |
|---|---|---|
| Query | String | Lucene Query |
| Limit | Integer | The number of items to return. A value of 0 returns the maximum of 10,000 results. |
| Sort | String | Optional. Comma separated list of sort parameters comprised of an indexed variable, a space, and then either asc for ascending or desc for descending. |
Examples:
## $dotcontent.query(String query, int limit, String sort)
$dotcontent.query("+contentType:Blog", 0, "modDate desc")
## $dotcontent.query(String query, int limit)
$dotcontent.query("+contentType:Blog", 0)
Count
Returns an integer count of the number of content items matching the query.
| Argument | Type | Details |
|---|---|---|
| Query | String | Lucene Query |
Examples:
## $dotcontent.count(String query)
$dotcontent.count("+contentType:Blog")
Find
Fetches a single contentlet by identifier or inode. For more information, see Load Individual Contentlet from Identifier or Inode.
| Argument | Type | Details |
|---|---|---|
| Identifier Or Inode | String | Accepts either one. |
Examples:
## $dotcontent.find(String inodeOrIdentifier)
$dotcontent.find("a7df3f39-a18a-4b16-b369-aa9d7acb0b27")
Load
Fetches a single contentlet by identifier or inode. Functions much like find(), but returns an object that loads lazily — i.e., at the time of access rather than on page load.
| Argument | Type | Details |
|---|---|---|
| Identifier Or Inode | String | Accepts either one. |
Examples:
## $dotcontent.load(String inodeOrIdentifier)
$dotcontent.load("a7df3f39-a18a-4b16-b369-aa9d7acb0b27")
Load Type (JavaScript API Only)
Fetches a single object representing a Content Type by identifier or variable.
| Argument | Type | Details |
|---|---|---|
| Identifier Or Variable | String | Accepts either one. |
Examples:
// dotcontent.loadType(String idOrVar);
const contentType1 = dotcontent.loadType("799f176a-d32e-4844-a07c-1b5fcd107578");
// dotcontent.loadType(String idOrVar);
const contentType1 = dotcontent.loadType("Blog");
Content Limit on Pull
For all pull methods the default limit is 10,000 pieces of content. (Attempts to specify a number higher than 10,000 result in the maximum available contentlets being pulled.) However, this limit can be circumvented using the method below.
Bypass Pagination
To see as many content items as you would like above 10,000 without pagination, use the Scroll API to fetch a larger list of elements.
