WebView class

Marks a class as a web view component specialized for rendering HTML, CSS, or JavaScript content.

WebView is a specialized form of Controller annotation designed exclusively for server-side view rendering. While regular Controller classes can handle both REST API endpoints and view rendering, classes annotated with WebView are specifically optimized for generating dynamic web content and must extend either RenderableView or RenderableWebView.

Key Characteristics

  • View-Focused: Dedicated to rendering HTML, CSS, and JavaScript content
  • Dynamic Context: Accesses request data through ViewContext including session attributes, path variables, query parameters, and headers
  • Template Support: Can work with template engines or return raw HTML
  • Content Type: Defaults to "text/html" content type

Implementation Requirements

Classes annotated with @WebView must extend one of:

Dynamic Context Access

The ViewContext provides access to various request data sources:

  • Session Data: context.getSessionAttribute("key")
  • Path Variables: context.getPathVariable("name")
  • Query Parameters: context.getQueryParam("id")
  • Request Headers: context.getHeader("content-type")
  • Request Attributes: context.getAttribute("data")

Example: Direct HTML Rendering

@WebView("/home") // Becomes /api/home if context path is configured
class HomePage extends RenderableView {
  @override
  String render(ViewContext context) {
    final session = context.getSessionAttribute("userSession");
    final userName = context.getPathVariable("name");
    final theme = context.getQueryParam("theme") ?? "light";
    
    return """
    <html>
      <head>
        <title>Welcome</title>
        <link rel="stylesheet" href="/styles/$theme.css">
      </head>
      <body>
        <h1>Hello, $userName!</h1>
        <p>Welcome to Jetleaf Web Framework!</p>
        <p>Session ID: ${session?.id}</p>
      </body>
    </html>
    """;
  }
}

Example: Template-Based Rendering

@WebView("/users/{id}/profile")
class UserProfileView extends RenderableWebView {
  @override
  PageView render(ViewContext context) {
    final userId = context.getPathVariable("id");
    final userSession = context.getSessionAttribute("currentUser");
    final preview = context.getQueryParam("preview") == "true";
    
    return PageView("user-profile.html")
      ..addAttribute("userId", userId)
      ..addAttribute("userSession", userSession)
      ..addAttribute("isPreview", preview);
  }
}

Common Use Cases

  • Dynamic Web Pages: Generating HTML content with server-side data
  • Email Templates: Rendering dynamic email content for notifications
  • Report Generation: Creating HTML reports with live data
  • Dashboard Views: Building admin interfaces with real-time data
  • Form Processing: Handling form submissions and rendering results

URL Path Handling

The route parameter supports:

  • Static Paths: /home, /about, /contact
  • Path Variables: /users/{id}, /products/{category}/{id}
  • Context Path Integration: Automatically prefixed with application context path
  • Context Path Override: Use ignoreContextPath to disable context path prefixing

Framework Integration

  • Automatic Registration: Discovered and registered by controller scanners
  • Request Mapping: Routes HTTP requests to appropriate view renderers
  • Content Negotiation: Supports different content types through configuration
  • Error Handling: Integrates with framework error page system

Comparison with REST Controllers

Aspect WebView REST Controller
Primary Purpose HTML View Rendering JSON/XML API Responses
Return Type String or PageView Response or Domain Object
Content Type text/html (default) application/json (typical)
Data Access ViewContext for request data Method parameters with annotations
Base Class Must extend RenderableView/RenderableWebView No specific base class required

Parameters

  • route: The URL path pattern that maps to this view component
  • ignoreContextPath: When true, excludes the application context path from the route

Best Practices

  • Use descriptive route patterns that reflect the view's purpose
  • Leverage template engines for complex HTML generation
  • Implement proper error handling for missing data
  • Consider security implications when rendering user data
  • Use CSS and JavaScript appropriately for dynamic behavior
Annotations
  • @Target.new({TargetKind.classType})

Constructors

WebView(String route, [bool ignoreContextPath = false, HttpMethod method = HttpMethod.GET])
Marks a class as a web view component specialized for rendering HTML, CSS, or JavaScript content.
const

Properties

annotationType → Type
Returns the annotation _type of this annotation.
no setter
hashCode → int
Returns a hash code consistent with equality definition.
no setterinherited
ignoreContextPath → bool
Whether to not include the context path from environment (if available) when accessing this controller.
final
method → HttpMethod
The http method for this web view, usually defaults to GET
final
route → String
The URL route pattern that maps HTTP requests to this view component.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

equals(Object other) → bool
Checks whether the given object is logically equivalent to this annotation.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
Returns a string representation of this WebView annotation.

Operators

operator ==(Object other) → bool
Checks if this annotation is equal to another object.
inherited