Node Picker

ID: node-picker

The node-picker field type renders a modal picker for a node. The modal picker allows you to filter nodes as well as paginate, sort and inspect nodes. The picker supports single node and multi-node selection depending on how the field is configured.

Sample configuration:

{
    "type": "node-picker"
}

The node picker should be modeled on top of either an object or an array field. The former is used for selection of a single node whereas the latter is used for selection of multiple nodes. The node selections are stored as object(s) and have a structure like this:

{
    "id": "1df59b00c7225162e9cd",
    "ref": "node://e86bb3527527046fc911/fcce75b88fa241485bca/b8ee3218cd279e7e834c/1df59b00c7225162e9cd",
    "title": "Templates",
    "qname": "o:1df59b00c7225162e9cd",
    "typeQName": "n:node"
}

Options

The following options may be specified for the control:

Option Type Default Description
picker.typeQName string Constrains the node list to a given type (i.e. my:article)
picker.typeQNames array Constrains the node list to several types (i.e. ["my:article", "my:press-release"])
picker.includeChildTypes boolean false Automatically includes inherited child definitions of definitions provided via typeQName or typeQNames
picker.query object Allows you to constrain the query to a custom query expression
picker.uploadPath string The path where any uploaded files should be placed.
picker.uploadType string Specifies the type QName for any uploaded nodes.

Example: Customized Node Picker #1 (articles and press releases)

This picker shows articles and press releases.

{
    "type": "node-picker",
    "picker": {
        "typeQNames": ["my:article", "my:press-release"]
    }
}

Example: Customized Node Picker #2 (using a custom query)

This picker shows how to use a custom query. We query for articles and press releases that were authored by Joe Smith and were created between 2014 and 2016.

{
    "type": "node-picker",
    "picker": {
        "query": {
            "_type": ["my:article", "my:press-release"],
            "_system.created_by": "joesmith",
            "_system.created_on.year": {
                "$gte": 2014,
                "$lte": 2016
            }
        }
    }
}

Example: Customized Node Picker #3 (including inherited types)

Suppose you have a content type hierarchy like this -

my:thing
    my:article
    my:newsitem

In this case, the type my:article inherits from my:thing. The type my:newsitem also inherits from my:thing.

In this example, let's assume we want our node picker to let us choose from either Things, Articles or News Items. One way to do this would be to use the typeQNames property to tell the picker about these three content types explicitly, like this:

{
    "type": "node-picker",
    "picker": {
        "typeQNames": ["my:thing", "my:article", "my:newsitem"]
    }
}

In this way, we can be very specific about what types the picker should let us choose from. However, there may be cases where we want to have the picker automatically let us choose from any child types for Thing. That way, if we add new sub-types of Thing in the future, the picker will automatically let us choose them.

We can provide an equivalent configuration using the includeChildTypes setting, like this:

{
    "type": "node-picker",
    "picker": {
        "typeQNames": ["my:thing"],
        "includeChildTypes": true
    }
}

Or:

{
    "type": "node-picker",
    "picker": {
        "typeQName": "my:thing",
        "includeChildTypes": true
    }
}

Suppose we want our node picker to let us pick from nodes of type my:image. We also want it to allow us to upload files to the /Images directory. All uploaded files should be of type my:image.

{
    "type": "node-picker",
    "picker": {
        "typeQName": "my:image",
        "uploadPath": "/Images",
        "uploadType": "my:image"
    }
}