Location subtree Query Type

This Query Type is used to build queries that fetch from the Location subtree.

Identifier SiteAPI:Location/Subtree
Own conditions
Inherited Location conditions
Common Content conditions
Common query parameters

Examples

Subtree of the calendar type Location contains event type Locations. On the full view for calendar fetch all pending events from its subtree up to depth of 3, sort them by their start date and paginate them by 10 per page using URL query parameter page:

ezpublish:
    system:
        frontend_group:
            ng_content_view:
                full:
                    calendar:
                        template: '@ezdesign/content/full/calendar.html.twig'
                        match:
                            Identifier\ContentType: calendar
                        queries:
                            pending_events:
                                query_type: SiteAPI:Location/Subtree
                                max_per_page: 10
                                page: '@=queryParam("page", 1)'
                                parameters:
                                    content_type: event
                                    relative_depth:
                                        lte: 3
                                    field:
                                        start_date:
                                            gt: '@=timestamp("today")'
                                    sort: field/event/start_date asc
{% set events = ng_query( 'pending_events' ) %}

<h3>Pending events</h3>

<ul>
{% for event in events %}
    <li>{{ event.content.name }}</li>
{% endfor %}
</ul>

{{ pagerfanta( events, 'twitter_bootstrap' ) }}

Own conditions

exclude_self

Defines whether to include Location defined by the location condition in the result set. If null is used as a value, the condition won’t be added.

  • value type: boolean, null
  • value format: single
  • operators: none
  • target: none
  • required: false
  • default: true

Examples:

# do not include the subtree root Location, this is also default behaviour
exclude_self: true
# include the subtree root Location
exclude_self: false

location

Defines the root Location of the Location subtree.

Note

This condition is required. It’s also automatically set to the Location instance resolved by the view builder if the query is defined in the view builder configuration.

  • value type: Location
  • value format: single
  • operators: none
  • target: none
  • required: true
  • default: not defined

Examples:

# this is also automatically set when using from view builder configuration
location: '@=location'
# fetch from subtree of the parent Location
location: '@=location.parent'
# fetch from subtree of the parent Location's parent Location
location: '@=location.parent.parent'

relative_depth

Defines depth of the Location in the tree relative to the Location defined by location condition. If null is used as a value, the condition won’t be added.

  • value type: integer, null
  • value format: single, array
  • operators: eq, in, gt, gte, lt, lte, between
  • target: none
  • required: false
  • default: not defined

Examples:

# identical to the example below
relative_depth: 2
relative_depth:
    eq: 2
# identical to the example below
relative_depth: [2, 3]
relative_depth:
    in: [2, 3]
# multiple operators are combined with logical AND
relative_depth:
    in: [2, 3]
    gt: 1
    lte: 3
relative_depth:
    between: [2, 4]

Inherited Location conditions

depth

Defines absolute depth of the Location in the tree. If null is used as a value, the condition won’t be added.

  • value type: integer, null
  • value format: single, array
  • operators: eq, in, gt, gte, lt, lte, between
  • target: none
  • required: false
  • default: not defined

Examples:

# identical to the example below
depth: 3
depth:
    eq: 3
# identical to the example below
depth: [3, 4, 8]
depth:
    in: [3, 4, 8]
# multiple operators are combined with logical AND
depth:
    in: [3, 4, 5]
    gt: 4
    lte: 8
depth:
    between: [4, 7]

main

Defines whether returned Locations are main Locations or not. Use true to get main Locations, false to get non-main Locations and null to get both (which is also the default behaviour).

  • value type: boolean, null
  • value format: single
  • operators: eq
  • target: none
  • required: false
  • default: not defined

Examples:

# identical to the example below
main: true
main:
    eq: true
# get both main and non-main Locations
main: ~

priority

Defines the priority of the Location. If null is used as a value, the condition won’t be added.

  • value type: integer, null
  • value format: single
  • operators: gt, gte, lt, lte, between
  • target: none
  • required: false
  • default: not defined

Examples:

# multiple operators are combined with logical AND
depth:
    gt: 4
    lte: 8
depth:
    between: [4, 7]

visible

Defines condition on visibility status of the returned Locations. Use true to get back only visible Locations (the default behaviour), false to get back only hidden or invisible Locations and null to get both.

Warning

Default value of this condition can be affected by the siteaccess configuration.

  • value type: boolean, null
  • value format: single
  • operators: eq
  • target: none
  • required: false
  • default: as defined by show_hidden_items configuration option (the opposite from it’s value, resolved as visible: true by default)

Examples:

# identical to the example below
visible: false
visible:
    eq: false
# get both visible and hidden or invisible Locations
visible: ~

Common Content conditions

content_type

Defines ContentType of the Content by the identifier. If null is used as a value, the condition won’t be added.

  • value type: string, null
  • value format: single, array
  • operators: eq, in
  • target: string ContentType identifier
  • required: false
  • default: not defined

Examples:

# identical to the example below
content_type: article
content_type:
    eq: article
# identical to the example below
content_type: [image, video]
content_type:
    in: [image, video]

field

Defines conditions on Content fields.

  • value type: integer, string, boolean
  • value format: single, array
  • operators: eq, in, gt, gte, lt, lte, between, like, contains
  • target: string Field identifier
  • required: false
  • default: not defined

Examples:

field:
    date_field:
        not:
            gt: 'today +5 days'
    price:
        between: [100, 200]
        not: 155

is_field_empty

Defines conditions on whether the Content fields are empty or not. If null is used as a value, the condition won’t be added.

Note

IsEmptyField criterion is supported only by Solr search engine, so this condition can be used only with the FindService. In order to use it configure the query with parameter use_filter set to false.

  • value type: boolean, null
  • value format: single
  • operators: eq
  • target: string Field identifier
  • required: false
  • default: not defined

Examples:

is_field_empty:
    image: false
    video: true
# allow both empty and non-empty fields, which is also the default behaviour
is_field_empty:
    audio: ~

creation_date

Defines the creation (first publication) date of the Content as a timestamp or time string as accepted by PHP function strtotime.

  • value type: integer, string
  • value format: single, array
  • operators: eq, in, gt, gte, lt, lte, between
  • target: none
  • required: false
  • default: not defined

Examples:

# identical to the example below
creation_date: 1535117737
creation_date:
    eq: 1535117737
# identical to the example below
creation_date: [1435117737, 1535117737]
creation_date:
    in: [1435117737, 1535117737]
# multiple operators are combined with logical AND
creation_date:
    gt: '29 June 1991'
    lte: '5 August 1995'
creation_date:
    gt: 'today'
creation_date:
    between: ['-1 week 2 days 4 hours 2 seconds', 'today']

modification_date

Defines the modification (last publication) date of the Content as a timestamp or time string as accepted by PHP function strtotime.

  • value type: integer, string
  • value format: single, array
  • operators: eq, in, gt, gte, lt, lte, between
  • target: none
  • required: false
  • default: not defined

Examples:

# identical to the example below
modification_date: 1535117737
modification_date:
    eq: 1535117737
# identical to the example below
modification_date: [1435117737, 1535117737]
modification_date:
    in: [1435117737, 1535117737]
# multiple operators are combined with logical AND
modification_date:
    gt: '29 June 1991'
    lte: '5 August 1995'
modification_date:
    gt: 'today'
modification_date:
    between: ['-1 week 2 days 4 hours 2 seconds', 'today']

section

Defines Section of the Content by the identifier. If null is used as a value, the condition won’t be added.

  • value type: string, null
  • value format: single, array
  • operators: eq, in
  • target: none
  • required: false
  • default: not defined

Examples:

# identical to the example below
section: standard
section:
    eq: standard
# identical to the example below
section: [standard, restricted]
section:
    in: [standard, restricted]

state

Defines ObjectState of the Content by the ObjectStateGroup and ObjectState identifiers.

Note

Content can only exist in single ObjectState from the same ObjectStateGroup.

  • value type: string ObjectState identifier
  • value format: single
  • operators: eq
  • target: string ObjectStateGroup identifier
  • required: false
  • default: not defined

Examples:

# identical to the example below
state:
    ez_lock: not_locked
state:
    ez_lock:
        eq: not_locked
# multiple states are combined with logical AND
# identical to the example below
state:
    ez_lock: locked
    approval: rejected
state:
    ez_lock:
        eq: locked
    approval:
        eq: rejected

Common query parameters

limit

Defines the maximum number of items to return. If null is used as a value, the limit will be set to the default value.

Note

This parameter will not be used if you execute the query from Twig using ng_query function. In that case Pargerfanta pager is used with semantic parameters page and max_per_page. To execute the query directly use ng_raw_query Twig function instead.

  • value type: integer, null
  • value format: single
  • required: false
  • default: 25

Examples:

limit: 10

offset

Defines the offset for search hits, used for paging the results. If null is used as a value, the offset will be set to the default value.

Note

This parameter will not be used if you execute the query from Twig using ng_query function. In that case Pargerfanta pager is used with semantic parameters page and max_per_page. To execute the query directly use ng_raw_query Twig function instead.

  • value type: integer, null
  • value format: single
  • required: false
  • default: 0

Examples:

offset: 20

sort

  • value type: string, SortClause, Location
  • value format: single, array
  • required: false
  • default: not defined

Here you can use any SortClause implementation or a Site API Location object. Using a Location object is the same a using sort clauses that are defined on it:

sort: "@=location"

The example above is a shortcut to the example below:

sort: "@=location.innerLocation.getSortClauses()"

If you define your query in the view configuration, you won’t be able to directly instantiate a SortClause there. For that reason we provide a way to define the sort clause as a string instead. With this format a subset of commonly used SortClauses is supported. Sort direction is defined as asc for ascending and desc for descending. In can be omitted, in which case it will default to asc.

Strings can be used to define multiple sort clauses through an array of definitions:

sort:
    - depth asc
    - modified desc

Following sort clauses are available through string definition:

Location depth

String depth enables sorting by Location’s depth:

sort: depth
sort: depth asc
sort: depth desc

Content Field

String in form of of field/[content_type]/[field] enables sorting by any Content Field. For example by Field with identifier title in ContentType with identifier article:

sort: field/article/title
sort: field/article/title asc
sort: field/article/title desc

Content modification date

String modified enables sorting by the Content modification date:

sort: modified
sort: modified asc
sort: modified desc

Content name

String name enables sorting by the Content name:

sort: name
sort: name asc
sort: name desc

Location priority

String priority enables sorting by the Location priority:

sort: priority
sort: priority asc
sort: priority desc

Content publication date

String published enables sorting by the Content publication/creation date:

sort: published
sort: published asc
sort: published desc