{"id":9696,"library":"documenttemplate","title":"Document Templating Markup Language (DTML)","description":"DocumentTemplate is a Python library implementing the Document Templating Markup Language (DTML), originally developed for the Zope application server. It allows for dynamic generation of HTML, XML, or other text documents using a tag-based templating system. The current version is 5.3, with releases typically tied to bug fixes or Python version compatibility updates.","status":"active","version":"5.3","language":"en","source_language":"en","source_url":"https://github.com/zopefoundation/DocumentTemplate","tags":["templating","dtml","zope","html-generation"],"install":[{"cmd":"pip install documenttemplate","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"note":"While 'from DocumentTemplate.document import HTML' is technically correct for the class's module, 'from DocumentTemplate import HTML' is the public and simpler way to access the HTML template class, as it's re-exported at the package root.","wrong":"from DocumentTemplate.document import HTML","symbol":"HTML","correct":"from DocumentTemplate import HTML"},{"note":"Used for loading templates from files rather than strings.","symbol":"DTMLFile","correct":"from DocumentTemplate import DTMLFile"}],"quickstart":{"code":"from DocumentTemplate import HTML\nimport os\n\ntemplate_source = \"\"\"\n<h1>Hello <dtml-var name=\"user_name\">!</h1>\n<p>Your lucky number is <dtml-var name=\"lucky_number\">.</p>\n<dtml-if expr=\"lucky_number > 5\">\n  <p>That's a big number!</p>\n<dtml-else>\n  <p>That's a small number.</p>\n</dtml-if>\n<p>Using environment: <dtml-var expr=\"request.environ.get('TEST_ENV_VAR', 'N/A')\"></p>\n\"\"\"\n\n# Prepare context dictionary\ncontext = {\n    'user_name': 'Registry User',\n    'lucky_number': 7,\n    'request': {\n        'environ': {\n            'TEST_ENV_VAR': os.environ.get('TEST_ENV_VAR', 'DEFAULT_TEST_VALUE')\n        }\n    }\n}\n\n# Create template instance\ntemplate = HTML(template_source)\n\n# Render the template\nrendered_output = template.render(**context)\nprint(rendered_output)","lang":"python","description":"This quickstart demonstrates how to define a DTML template string, prepare a context dictionary, and render the template using the `HTML` class. It includes examples of variable substitution, conditional logic (`dtml-if`), and accessing nested context data like environment variables."},"warnings":[{"fix":"Update your code to call `template.render(**context)` instead of `template(**context)`. Ensure all arguments are passed as keywords.","message":"The primary rendering method for templates changed from direct invocation (`template(**context)`) to an explicit `render()` method (`template.render(**context)`). Additionally, all arguments to `render`, `eval`, and `manage_edit` are now keyword-only.","severity":"breaking","affected_versions":"5.0.0 and newer"},{"fix":"Upgrade your Python environment to Python 3.10 or a newer compatible version (e.g., 3.11, 3.12).","message":"Support for Python versions older than 3.10 was dropped. This includes Python 2.7, 3.5, 3.6, 3.7, 3.8, and 3.9.","severity":"breaking","affected_versions":"5.0.0 and newer"},{"fix":"Update any environment variables used for DocumentTemplate configuration by removing the `DT_` prefix.","message":"The `DT_` prefix for environment variables used to configure DocumentTemplate was removed. Environment variables are now expected without this prefix (e.g., `CACHE_SIZE` instead of `DT_CACHE_SIZE`).","severity":"deprecated","affected_versions":"5.0.0 and newer"},{"fix":"Always refer to the official DocumentTemplate documentation or Zope DTML references for correct syntax and features. Avoid assuming similarities with other templating engines.","message":"DTML syntax is unique and differs significantly from more modern templating languages like Jinja2, Django Templates, or Mako. It uses `dtml-` prefixed tags and a specific expression syntax, which can lead to confusion if familiar with other systems.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"For DocumentTemplate 5.0+, use the `render()` method: `template.render(**context)`.","cause":"Attempting to render a template by calling the instance directly (e.g., `template(context)`), which was the method in versions prior to 5.0.","error":"TypeError: 'HTML' object is not callable"},{"fix":"Ensure that your context dictionary includes a key matching the variable name. For nested access (e.g., `request.user.name`), verify all intermediate keys exist in the context.","cause":"The variable specified in a `dtml-var` tag (e.g., `name=\"my_var\"`) does not exist in the context dictionary provided to the template.","error":"dtml-var: name '...' not found"},{"fix":"Review your template source to ensure all block-level DTML tags have their matching closing tags. Pay close attention to spelling and capitalization.","cause":"A block-level DTML tag, such as `dtml-if`, `dtml-in`, or `dtml-unless`, was opened but not properly closed with its corresponding `dtml-endif`, `dtml-endin`, or `dtml-endunless` tag.","error":"ValueError: Missing closing tag for dtml-if (or other dtml- block tag)"}]}