Add additional documentation.

This adds additional documentation for using the CEL interceptor's _overlays_ feature.

Includes examples of before and after, and using the values from a binding.

docs/eventlisteners.md

@@ -321,15 +321,50 @@ spec:
 
 ### CEL Interceptors
 
-CEL Interceptors parse expressions to filter requests based on JSON bodies and
-request headers, using the [CEL](https://github.com/google/cel-go) expression
-language. Please read the
-[cel-spec language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md)
-for more details on the expression language syntax.
+CEL Interceptors can be used to filter or modify incoming events, using the
+[CEL](https://github.com/google/cel-go)  expression language.
 
-In addition to the standard
-[CEL expression language syntax](https://github.com/google/cel-spec/blob/master/doc/langdef.md),
-Triggers supports these additional [CEL expressions](./cel_expressions.md).
+Please read the [cel-spec language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md) for
+more details on the expression language syntax.
+
+The `cel-trig-with-matches` trigger below filters events that don't have an
+`'X-GitHub-Event'` header matching `'pull_request'`.
+
+It also modifies the incoming request, adding an extra key to the JSON body,
+with a truncated string coming from the hook body.
+
+<!-- FILE: examples/eventlisteners/cel-eventlistener-interceptor.yaml -->
+
+```YAML
+apiVersion: tekton.dev/v1alpha1
+kind: EventListener
+metadata:
+  name: cel-listener-interceptor
+spec:
+  serviceAccountName: tekton-triggers-example-sa
+  triggers:
+    - name: cel-trig-with-matches
+      interceptors:
+        - cel:
+            filter: "header.match('X-GitHub-Event', 'pull_request')"
+            overlays:
+            - key: extensions.truncated_sha
+              expression: "truncate(body.pull_request.head.sha, 7)"
+      bindings:
+      - name: pipeline-binding
+      template:
+        name: pipeline-template
+    - name: cel-trig-with-canonical
+      interceptors:
+        - cel:
+            filter: "header.canonical('X-GitHub-Event') == 'push'"
+      bindings:
+      - name: pipeline-binding
+      template:
+        name: pipeline-template
+```
+In addition to the standard expressions provided by CEL, Triggers supports some
+useful functions for dealing with event data [CEL expressions](./cel_expressions.md).
 
 The body/header of the incoming request will be preserved in this Interceptor's
 response.
@@ -365,9 +400,11 @@ spec:
         name: pipeline-template
 ```
 
-If no filter is provided, then the overlays will be applied to the body. With a
-filter, the `expression` must return a `true` value, otherwise the request will
-be filtered out.
+The `filter` expression must return a `true` value if this trigger is to
+be processed, and the `overlays` applied.
+
+Optionally, no `filter` expression can be provided, and the `overlays` will be
+applied to the incoming body.
 
 <!-- FILE: examples/eventlisteners/cel-eventlistener-no-filter.yaml -->
 
@@ -391,6 +428,101 @@ spec:
         name: pipeline-template
 ```
 
+#### Overlays
+
+The CEL interceptor supports "overlays", these are CEL expressions that are
+applied to the body before it's returned to the event-listener.
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: EventListener
+metadata:
+  name: example-with-overlays
+spec:
+  serviceAccountName: tekton-triggers-example-sa
+  triggers:
+    - name: cel-trig
+      interceptors:
+        - cel:
+            overlays:
+            - key: extensions.truncated_sha
+              expression: "truncate(body.pull_request.head.sha, 7)"
+            - key: extensions.branch_name
+              expression: "truncate(body.ref.split, '/')[2]"
+      bindings:
+      - name: pipeline-binding
+      template:
+        name: pipeline-template
+```
+
+In this example, the bindings will see two additional fields:
+
+Assuming that the input body looked something like this:
+```json
+{
+  "ref": "refs/heads/master",
+  "pull_request": {
+    "head": {
+      "sha": "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
+    }
+  }
+}
+```
+The output body would look like this:
+```json
+{
+  "ref": "refs/heads/master",
+  "pull_request": {
+    "head": {
+      "sha": "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
+    },
+  },
+  "extensions": {
+    "truncated_sha": "6113728",
+    "branch_name": "master"
+  }
+}
+```
+The `key` element of the overlay can create new elements in a body, or,
+overlay existing elements.
+
+For example, this expression:
+
+```yaml
+- key: body.pull_request.head.short_sha
+  expression: "truncate(body.pull_request.head.sha, 7)"
+```
+Would see the `short_sha` being inserted into the existing body:
+
+```json
+{
+  "ref": "refs/heads/master",
+  "pull_request": {
+    "head": {
+      "sha": "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
+      "short_sha": "6113728"
+    },
+  }
+}
+```
+It's even possible to replace existing fields, by providing a key that matches
+the path to an existing value.
+
+Anything that is applied as an overlay can be extracted using a binding e.g.
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: TriggerBinding
+metadata:
+  name: pipeline-binding
+spec:
+  params:
+  - name: gitrevision
+    value: $(body.extensions.branch_name)
+  - name: branch
+    value: $(body.pull_request.head.short_sha)
+```
+
 ## Examples
 
 For complete examples, see