# Paths and matchers

## Patterns

The value of the `path` attribute can be either a glob pattern or a full regular expression (Java regular expressions, which are very similar to Perl 5 regular expressions).

| Value              | Description                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Glob               | This is the default but can also be set explicitly with the  `matcher` attribute set to glob (or `oxf:glob-matcher` for backward compatibility) on the `<page>` element. This supports the wildcards "`*`" and "?". as well as character classes, as [documented here](https://svn.apache.org/repos/asf/jakarta/oro/tags/oro-2.0.9-dev-1/docs/api/org/apache/oro/text/GlobCompiler.html). |
| Regular expression | This is enabled with the  `matcher` attribute set to regexp (or oxf:perl5-matcher for backward compatibility) on the `<page>` element. This enables full Java/Perl 5 regular expressions.                                                                                                                                                                                                 |

Simple examples of glob:

* `/about/company.html`matches exactly this URL
* `about/*` matches any URL that starts with `about/`
* `*.gif` matches any URL that ends with `.gif`
* `a?c` matches `aac`, `abc`, `etc`.

A default value for the `matcher` attribute can also be placed on the element:

```markup
<controller xmlns="http://www.orbeon.com/oxf/controller" matcher="regexp">
    ...
</controller>
```

*COMPATIBILITY NOTE: Prior to Orbeon Forms 4.0, expression matchers were fully configurable via XPL processors. Starting Orbeon Forms 4.0, only Java/Perl 5 regular expressions and glob expressions are supported.*

## Matching files and pages with regular expressions

Groups of files can be matched using a single `<files>` element with the regexp matcher:

```markup
<files
  path="/doc/[^.]*\.html"
  matcher="regexp"/>
```

A matcher can also be specified on a `<page>` element:

```markup
<page
  path="/forms/([_A-Za-z\-0-9]+)/page/([0-9]{1,3})"
  matcher="regexp"/>
```

When using a matcher that allows for groups, the part of the path matched by those groups can be extracted as documented above with the `<setvalue>` element. This is only supported with the regexp matcher.

## Restricting HTTP methods

\[SINCE Orbeon Forms 2017.2]

The `methods` attribute restricts which HTTP methods are allowed on the page or service. It is a space-separated list of HTTP method names. `#all` can be explicitly used to indicate that all HTTP methods are allowed.

By default, all HTTP methods are allowed.

This example requires that the incoming request be an HTTP `POST`, or the controller returns a "404 Not Found" status code:

```markup
<service
    path="/fr/service/([^/^.]+)/([^/^.]+)/(duplicate)"
    methods="POST"
    model="request-parameters.xpl"
    view="services/duplicate.xhtml"/>
```

*NOTE: This is independent from page or service authorization.*

## Parametrizing the `model` and `view` attributes

The result of matches can be referred to directly in the `model` and `view` attributes using the notation `${_group-number_}`:

```markup
<page
  path="/forms/([_A-Za-z\-0-9]+)/page/([0-9]{1,3})"
  matcher="regexp"
  model="oxf:/forms/${1}/model.xpl"
  view="oxf:/forms/${1}/view-${2}.xhtml"/>
```

In this case, if the path contains: `/forms/my-form/page/12`:

* The model file read will be `oxf:/forms/my-form/model.xpl`
* The view file `oxf:/forms/my-form/view-12.xhtml`

Parametrizing `model` and `view` attributes this way often allows greatly reducing the size of page flows that contain many similar pages.

## Navigating to pages that use matchers

When a `result` element directs flow to a page that uses matchers and `<setvalue>` elements, the PFC attemps to rebuild the destination path accordingly. Consider the following example:

```markup
<page id="source" path="/">
    <action>
        <result page="destination" transform="oxf:xslt">
            <form xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xsl:version="2.0">
                <username>orbeon</username>
                <blog-id>12345</blog-id>
            </form>
        </result>
    </action>
</page>
```

```markup
<page
  id="destination"
  path="/user/([^/]+)/blog/([^/]+)"
  matcher="regexp"
  view="blogs/${1}/blog-${2}.xhtml">
    <setvalue ref="/form/username" matcher-group="1"/>
    <setvalue ref="/form/blog-id" matcher-group="2"/>
</page>
```

In this example, accessing the `source` page directly causes navigation to the `destination` page. Using the following information:

* The internal XML submission
* The destination page's matcher groups
* The `<setvalue>` elements

The PFC reconstructs the path to `/user/orbeon/blog/12345`. This path is used to request the `destination` page. In this case, the `view` attribute evaluates to `blogs/orbeon/blog-12345.xhtml`.

*NOTE: Navigation to pages that use matchers but that do not provide an internal XML submission or* `<setvalue>` *elements will cause the requested path to have its literal value, in the example above* `/user/([^/]+)/blog/([^/]+)`*. It is not advised to perform navigation this way.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.orbeon.com/xml-platform/controller/paths-matchers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.