# The @template decorator A route handler has two jobs: decide what to show, and show it. `@template` takes the second job away entirely. Your handler gathers data and returns a `dict`. The decorator finds the template, renders it, builds the `Response`, and sets the headers. You never see a string of HTML in Python again, and the handler reads like a description of the page rather than a construction of it. # The contract Everything the decorator does follows from one rule about what your handler returns: | Handler returns | What the decorator does | |----|----| | a `dict` | Renders the template with the dict as its variables and returns a 200 `Response` (or the status you configured). | | a Robyn `Response` | Returns it untouched. No template is rendered. This is the escape hatch for redirects and hand-built responses. | | anything else | Raises [ChameleonRobynException](../reference/ChameleonRobynException.md#chameleon_robyn.ChameleonRobynException) at request time. `None`, strings and numbers are all rejected. | Return the dict directly. The decorator copies it before rendering, so returning a shared or module-level dict is safe. # Explicit template path The podcast's episode list is the plainest possible case: ``` python @app.get('/episodes') @chameleon_robyn.template('episodes/list.pt') def episode_list(request): return {'episodes': get_all_episodes()} ``` The path is relative to the folder passed to [global_init()](../reference/global_init.md#chameleon_robyn.global_init). Any file extension works; `.pt` is the convention, and the same site renders a `.xml` feed with the same decorator. # Auto-naming Leave the path out and the decorator names the template after the code that renders it. The rule has three steps: 1. Take the last segment of the handler's module name and the function name. 2. Look for `/.html` under the template folder. 3. If that file does not exist, use `/.pt`. So `index()` in `views/home_views.py` renders `home_views/index.html` if it exists, otherwise `home_views/index.pt`. Your template folder ends up mirroring your view modules, which is a pleasant thing to discover six months later. ``` python # Looks for templates/home_views/index.pt @app.get('/') @chameleon_robyn.template() def index(request): return {'message': 'Hello!'} ``` The parentheses are optional: ``` python @app.get('/') @chameleon_robyn.template def index(request): return {'message': 'Hello!'} ``` Two details are worth knowing: - A script run directly (`python app.py`) has the module name `__main__`, which would make for a strange folder name. The library uses the script's file name instead, so `index()` in `app.py` maps to `app/index.pt`. If no such file exists but `__main__/index.html` or `__main__/index.pt` does, that is used, so apps built on the old behavior keep working. - The name is resolved at the first request, not when the decorator runs. That is what lets you decorate routes at import time and call [global_init()](../reference/global_init.md#chameleon_robyn.global_init) later from `main()`. The file only has to exist by the time the first visitor arrives. # Async handlers Nothing to configure. The decorator notices `async def` and awaits the handler, so the episode page can go to the database like any other coroutine: ``` python @app.get('/dashboard') @chameleon_robyn.template('dashboard.pt') async def dashboard(request): stats = await fetch_stats_from_db() return {'stats': stats} ``` Robyn's typed path parameters pass straight through: ``` python @app.get('/episodes/:episode_id') @chameleon_robyn.template('episodes/detail.pt') async def episode_detail(request, episode_id: int): return {'episode': await get_episode(episode_id)} ``` # Status codes and content types Templates are not only for HTML pages. The podcast feed is a Chameleon template too, and so is a "created" page after a form post: ``` python # Return a 201 after creating a resource @app.post('/items') @chameleon_robyn.template('items/created.pt', status_code=201) async def create_item(request): item = await save_item(request.json()) return {'item': item} # Serve an XML feed @app.get('/feed.xml') @chameleon_robyn.template('episodes/feed.xml', content_type='application/xml') def xml_feed(request): return {'episodes': get_recent_episodes()} ``` The `charset=utf-8` suffix is added to the content type for you. These settings apply to rendered responses only. A pass-through `Response` keeps its own status and headers, and a 404 from [not_found()](../reference/not_found.md#chameleon_robyn.not_found) always renders as `text/html` with status 404. # Redirects and other pass-through responses Sometimes the right answer is not a page at all. Return a Robyn `Response` and the decorator steps aside: ``` python from robyn import Response, Headers @app.get('/old-page') @chameleon_robyn.template('home/index.pt') def old_page(request): return Response( status_code=302, description='', headers=Headers({'Location': '/new-page'}), ) ``` The same rule lets one handler choose between templates at runtime: build the alternative with [`response()`](lower-level-api.md) and return it. # Setting cookies or headers on a rendered page Here is the classic puzzle. A visitor logs in. You want to render the welcome page, which means returning a dict, and you also want to set a session cookie, which means touching the `Response`. You cannot do both from a dict. Or can you? Put a callable under the reserved key `__response_callback__` in the returned dict. After rendering, the decorator calls it with the `Response` it just built: ``` python from robyn import Response @app.post('/account/login') @chameleon_robyn.template('account/welcome.pt') async def login(request): user = await authenticate(request) if not user: return chameleon_robyn.response('account/login_failed.pt', status_code=401) token = create_session_token(user) def set_session_cookie(resp: Response): resp.headers.append('Set-Cookie', f'session={token}; HttpOnly; Path=/') return { 'user': user, '__response_callback__': set_session_cookie, } ``` Rules for the callback: - It is removed from the model before rendering, so the template never sees it, and your dict is not modified. - Change the `Response` in place. The return value is ignored. - It must be callable. Anything else raises [ChameleonRobynException](../reference/ChameleonRobynException.md#chameleon_robyn.ChameleonRobynException). # Decorator order Robyn's route decorator goes on the outside and `@template` goes directly above the function. Robyn reads the handler's signature when the route is registered, and the decorator preserves the original signature, so `request` and path parameters keep flowing exactly as they did before. ``` python @app.get('/episodes') # outermost @chameleon_robyn.template('episodes/list.pt') # directly above the function def episode_list(request): ... ```