Dotcontent Viewtool

Last Updated: Jul 19, 2024
documentation for the dotCMS Content Management System

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.

MethodReturn TypeContent Returned
$dotcontent.pull()List of content objectsAll content which matches the specified Lucene query
$dotcontent.pullPerPage()List of content objectsAll content matching the specified query, paginated
$dotcontent.pullRelatedField()List of content objectsRelated content matching the specified parameters.
$dotcontent.pullRelated()List of content objectsDeprecated; use pullRelatedField(). Related content matching the specified parameters.
$dotcontent.pullPersonalized()List of content objectsContent matching the specified parameters, personalized for individual users
$dotcontent.query()List of ids and inodesThe identifiers and inodes (only) of all content matching the specified query
$dotcontent.count()IntegerA count (only) of how many content items match the specified query
$dotcontent.find()Single content objectAn individual content item specified by identifier
$dotcontent.load()Single content objectSimilar to find(), but loads lazily.
$dotcontent.loadType()Single content type objectJavaScript Only. Returns an object representing a Content Type.

Pull

The basic multi-item pull operation. For more information, see Pulling and Displaying Content.

ArgumentTypeDetails
QueryStringLucene Query
OffsetIntegerOptional. Indicates the number of results to skip; useful for building your own pagination. Defaults to -1.
LimitInteger or
Numeric String
The number of items to return. A value of 0 returns the maximum of 10,000 results.
SortStringComma 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.

ArgumentTypeDetails
QueryStringLucene Query
Current PageIntegerIndicates which page of results to return, with 1 as the first page.
Contents Per PageIntegerThe number of items to return per page. A value of 0 returns the maximum of 10,000 results.
SortStringComma 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.

ArgumentTypeDetails
Contentlet IdentifierStringThe id of the contentlet containing the relatonship field.
Field VariableStringThe relationship field in the format ContentType.Field
ConditionStringLucene Query specifying additional limits on which content should be shown. Can be null.
LimitIntegerOptional. The number of items to return per page. A (default) value of 0 returns the maximum of 10,000 results.
OffsetIntegerOptional. Indicates the number of results to skip; useful for building your own pagination. Defaults to -1.
SortStringOptional. 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 through pullRelatedField().

## $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.

ArgumentTypeDetails
QueryStringLucene Query
LimitInteger or
Numeric String
The number of items to return. A value of 0 returns the maximum of 10,000 results.
OffsetIntegerOptional. Indicates the number of results to skip; useful for building your own pagination. Defaults to -1.
Secondary SortStringOptional. 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.

ArgumentTypeDetails
QueryStringLucene Query
LimitIntegerThe number of items to return. A value of 0 returns the maximum of 10,000 results.
SortStringOptional. 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.

ArgumentTypeDetails
QueryStringLucene 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.

ArgumentTypeDetails
Identifier Or InodeStringAccepts 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.

ArgumentTypeDetails
Identifier Or InodeStringAccepts 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.

ArgumentTypeDetails
Identifier Or VariableStringAccepts 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.

On this page

×

We Dig Feedback

Selected excerpt:

×