# Lookups
Lookups allow you to fill in foreign key values through a dialog where a user can select one item from a list of items.
Lookups are defined in the schema as following.

```json
"lookups": [
    {
        "id": 0,
        "name": "Site Lookup",
        "mapping": {
            "siteId": "id",
            "siteCode": "code",
            "siteDescription": "descriptions"
        },
        "perspective": 0,
        "view": 0,
        "remote": "site-resource"
    }
],
```

The lookup id is a required property and used to reference a lookup on the dataset.
The name property is not required but gives you a label to remind you what this lookup is suppose to do.

## Mapping
Mapping defines how data is transfered from the lookup selected model to the model that executes the lookup.
The mapping is defined as model.field: lookup.field. In the example above the code field from the lookup will be copied over to the siteCode of the model.

## Perspective
The lookup uses visualization to display the information. This provides a lot of flexability to the lookup on how to display lookup information.
The view schema defining the lookup can decide that grouping to apply if any and how the data should be displayed.
Perspectives allow multiple views so if you would like to provide different views for a lookup you can. Either way you need to define the default view id, normally 0.


```json
{
    "id": 0,
    "name": "model",
    "fields": [
        {
            "name": "id"
        },
        {
            "name": "siteId"
        },
        {
            "name": "siteCode",
            "lookup": 0
        },
        {
            "name": "siteDescription"
        }
    ]
}
```

As you can see above the "siteCode" field references the site lookup through the site lookup id "0".

## Doing the lookup
If you are using the dynamic for / schema mechanism you don't need to worry about how to call for a lookup as this will be done for you.
If however you are in a situation where you want to call a lookup manually for a given field you can do so by using the doLookup function on the model.

```js
this.model.doLookup("siteCode");
```

Note that a lookup must ber defined in the schema for that field.

## Get lookup records
Lookups use the standard datasource mechanism to fetch records. if the datasource is set to remote you use the datasource method passed to the dataset factory to fetch the data.

If a you return null or a empty array, a error message will be shown stating that no records were found.
If a single record is return either as a model object or a array with a single model in it, that model will be applied as per the definition.
If multiple records are returned, the lookup dialog will show for the user to make a selection from.

## Messages
Messages like the records not found will be sent to pragma-messages if you have it as part of your application.
If you are not using the "pragma-messages" custom control then you need to trap the messages yourself by subscribing to the event aggregation:

```js
window.eventEmitter.on("show-message", this.showMessageHandler);
```

## pragma-lookups
For any of this to work you need to add the "pragma-lookup" custom element to your application.\
This can be done globally using the app.html file.
```html
<pragma-lookup></pragma-lookup>
```

## Preview
The lookup allows you to show a preview UI secon on the right.
To allow for this you need to define the remote property that will be used to fetch the appropriate schema to populate this space.

```js
    "preview": {
        "remote": "StaffMember",
        "id-field": "id"
    }

```

When selecting a item in the lookup and preview is enabled, we need to be able to fetch the record to show in the preview UI.
To allows us to do that you need to define the field name to be used as the id. In the case when this is a composite, it is normally best to define a Id property on the relevant model that does the composite concatonation.

The generic component does not know hot to fetch the relevant schema or model for preview.
To allow us to fetch these things the preview element has two properties.

1. getPreviewSchema
1. getPreviewModel

these are callback pointers that you can hook up functions to do the work.
It is assumed that these functions are async.