Routing Documentation for WebApp Package

Home documentation

This documentation provides an overview of the routing configuration used in the WebApp package example. The routing functions define the paths, methods, and controllers that handle incoming HTTP requests to the server.

Overview

The getWebRoute function dynamically generates a list of routes for the web application. Each route is associated with specific paths, request methods, and controller actions. The routes are organized hierarchically, allowing for nested paths and complex routing structures.

Import Statements

import 'package:webapp/wa_route.dart';
import '../controllers/auth_controller.dart';
import '../controllers/home_controller.dart';

These imports bring in the necessary classes and controllers used for routing. The wa_route.dart file provides the core routing functionalities, while the auth_controller.dart and home_controller.dart files contain the logic for handling various routes.

Function: getWebRoute

The getWebRoute function returns a Future<List<WebRoute>>, which represents a list of all the web routes available in the application.

Parameters

• WebRequest rq: The request object that carries information about the incoming HTTP request. It is passed to controllers to access request data.

Controllers

The following controllers are instantiated within the getWebRoute function:

• HomeController: Handles the majority of the routes, managing the homepage, forms, language switching, and more.
• AuthController: Manages authentication-related routes, such as login, logout, and protected areas that require specific permissions.
• IncludeJsController: Responsible for serving JavaScript includes.

Routes Configuration

The routes are configured using instances of the WebRoute class, which define the paths, methods, and corresponding actions for each route.

Example Routes

Here’s a breakdown of the routes defined within the getWebRoute function:

1. Base Route: /
   • Methods: All request methods are accepted (GET, POST, etc.).
   • Controller: HomeController
   • Children: This route has several child routes nested under it.
2. WebSocket Route: /ws
   • Methods: All request methods are accepted.
   • Action: homeController.socket
   • Purpose: Handles WebSocket connections.
3. JavaScript Include: /app/includes.js
   • Methods: All request methods are accepted.
   • Action: includeController.index
   • Purpose: Serves JavaScript includes for the frontend.
4. Example Route: /example
   • Children:
     • Form GET: /example/form
       • Methods: GET only.
       • Action: homeController.exampleForm
     • Form POST: /example/form
       • Methods: POST only.
       • Action: authController.loginPost
     • Protected Panel: /example/panel
       • Methods: All methods.
       • Action: homeController.exampleAuth
       • Permissions: Requires admin permission.
5. Language Switching: /fa/*
   • Extra Paths: /en/*, /nl/*
   • Action: homeController.changeLanguage
6. Info Route: /info
   • Extra Path: /api/info
   • Action: homeController.info
7. Logout Route: /logout
   • Methods: All methods.
   • Action: authController.logout

Route Attributes

• path: The URL path that triggers the route.
• methods: Specifies the HTTP methods (GET, POST, etc.) that the route responds to.
• rq: The WebRequest object, which is passed to the route’s action.
• index: The function or method that will be executed when the route is accessed.
• auth: The authentication controller that handles access control for the route.
• permissions: A list of required permissions for accessing the route.

Example: Nested Routing

The /example route demonstrates how nested routing works:

WebRoute(
  path: 'example',
  rq: rq,
  index: () => rq.redirect('/'),
  children: [
    WebRoute(
      path: 'form',
      methods: RequestMethods.ONLY_GET,
      rq: rq,
      index: homeController.exampleForm,
    ),
    WebRoute(
      path: 'panel',
      methods: RequestMethods.ALL,
      rq: rq,
      auth: authController,
      index: homeController.exampleAuth,
      permissions: ['admin'],
    ),
    // Additional nested routes...
  ],
),

Dynamic Paths and Redirects

Routes like /example/form handle both GET and POST methods separately, allowing different actions based on the request type. Additionally, routes can redirect users, as seen with rq.redirect('/').

Conclusion

The getWebRoute function is a powerful and flexible way to define the routing structure for your web application. It supports hierarchical and dynamic routing, authentication, and permission management, making it suitable for building complex web applications. By customizing and extending these routes, you can adapt the WebApp package to fit the specific needs of your project.