FAQ

Do I have to call global_init() before decorating routes?

No. Explicit template paths are only used at request time, and auto-named templates are resolved at the first request. Decorate routes at import and call global_init() from main() if that reads better to you.

Why does my second global_init() call do nothing?

cache_init defaults to True, which makes later calls no-ops while the engine is initialized. Pass cache_init=False, or call clear() first. See Configuration.

Can one handler render different templates?

Yes. Build the alternative with response('other.pt', ...) and return it. A returned Response passes through the decorator untouched. See Rendering outside handlers.

How do I return a 404 outside a decorated handler?

not_found() only works inside @template handlers. Elsewhere, return response('errors/404.pt', status_code=404, message='...'). See Friendly 404 pages.

Why did my 404 page come back as HTML from an XML endpoint?

not_found() always renders as text/html with status 404. For another format, build the response yourself with response().

Can I use .html files instead of .pt?

Yes. The loader ignores the extension. Auto-naming looks for .html first and then .pt.

My Alpine.js or htmx attributes break the template

Pass restricted_namespace=False to global_init(). See Writing templates.

Can Chameleon and Jinja2 templates coexist in one app?

Yes. Nothing in this package touches Robyn’s Jinja2 support. Use @template or ChameleonTemplate for Chameleon pages and Robyn’s JinjaTemplate for the rest, and migrate at whatever pace suits you.

Does it work with chameleon-partials?

Yes, with no extra configuration. Initialize both packages with the same template folder and pass render_partial through the model. See Writing templates.

How do I test a handler?

Call it directly and assert on the returned Response. No server needed. See Testing your handlers.

Is the API stable?

Not yet. The project is in alpha. The surface is small and the current names are expected to stay, but there are no guarantees until 1.0.

Where is the template language documented?

At chameleon.readthedocs.io. The cheat sheet covers the parts you need day to day.