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.upload boolean Whether to include the upload button (default is true)
picker.uploadPath string The path where any uploaded files should be placed.
picker.uploadType string Specifies the type QName for any uploaded nodes.
picker.filterMode string search Specifies how node filter will operate. The default option is "search", will perform a simple search on the title and type of the node. The other option is fullText, which will do a full-text search of the nodes
picker.icon boolean true If true, will display the default attachment as an icon next to each option in the picker.
maxFileSize integer Restricts the maximum size of a file to be uploaded.

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"
    }
}

Say if we want to restrict the size of files that get uploaded to be less than 2048 bytes:

{
    "type": "node-picker",
    "label": "My Node Pikcer",
    "maxFileSize": 4096
}