Welcome to the Finch Routing Guide! This guide will walk you through the steps to configure routing in your Finch application. Whether you're a seasoned developer or just starting, Finch offers a robust set of tools to simplify server-side web app development.

FinchRoute

The FinchRoute class is used to define a route in your Finch application. It contains all the necessary properties to define a route. Here is an example of how to use it:

FinchRoute(
  path: '/',
  index: () async => rq.renderString(text: 'Hello World'),
);

Properties:

• path: The path of the route. It can contain variables in the form of {variableName}. For example, /users/{id}.
• index: The function to be called when the route is matched. It should return a Future<String>.
• methods: The HTTP methods that the route should respond to. It is a list of String. For example, ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD', 'CONNECT', 'TRACE'].
• controller: The controller to be used for the route. It should be an instance of Controller.
• children: The child routes of the current route. It is a list of FinchRoute.
• extraPath: Additional paths for the route. It is a list of String. For example, ['/home', '/index'].
• apiDoc: The function to generate API documentation for the route. It should return a Future<ApiDoc>.
• auth: The authentication controller to be used for the route. It should be an instance of AuthController.
• permissions: The permissions required for the route. It is a list of String. For example, ['admin'].
• widget: The widget to be rendered for the route. It should be a String representing the path to the widget.
• params: The default parameters to be passed to the widget. It is a Map<String, Object?>.
• title: The title of the page. It is a String.
• excludePaths: The paths to be excluded from the route. It is a list of String.
• hosts: The hosts that the route should respond to. It is a list of String. For example, ['example.com', 'www.example.com'].
• ports: The ports that the route should respond to. It is a list of int. For example, [80, 443].

Example of a simple route definition:

FinchRoute(
  key: 'route.users',
  path: '/users',
  index: () async => rq.renderJson(data: {'message': 'Users list'}),
  methods: Methods.ONLY_GET,
  hosts: ['example.com'], // or ['*'] for all hosts
  ports: [80, 443], // or [] for all ports
);

Example of a route with a controller:

FinchRoute(
  key: 'route.users',
  path: '/users',
  controller: UserController(),
  methods: Methods.ONLY_GET,
  hosts: ['example.com'], // or ['*'] for all hosts
  ports: [80, 443], // or [] for all ports
);

Example of a route with child routes:

FinchRoute(
  key: 'route.users',
  path: '/users',
  controller: UserController(),
  methods: Methods.ONLY_GET,
  hosts: ['example.com'], // or ['*'] for all hosts
  ports: [80, 443], // or [] for all ports
  children: [
    FinchRoute(
      key: 'route.users.show',
      path: '/{id}',
      index: () async => rq.renderJson(data: {'message': 'User details'}),
      methods: Methods.ONLY_GET,
    ),
  ],
);

Example of a route with authentication and permissions:

FinchRoute(
  key: 'route.users',
  path: '/users',
  controller: UserController(),
  methods: Methods.ONLY_GET,
  hosts: ['example.com'], // or ['*'] for all hosts
  ports: [80, 443], // or [] for all ports
  auth: AppAuthController(),
  permissions: ['admin'],
);

AppAuthController is a class that extends AuthController. You can find an example of it in the example directory.

API Routing

Finch provides a convenient way to define API routes. You can use /api path of FinchApp to define an API route. Here is an example of how to use it:

app.get(
  path: '/api/users',
  controller: UserController(),
);

Parameters Routing

for defining parameters in the path, you can use the {} syntax. For example, /users/{id}. You can access the parameters in the index function using the rq.get method. For example, rq.getParam('id').