Metadata-Version: 2.1
Name: z3c.jbot
Version: 2.2
Summary: Drop-in template overrides.
Home-page: https://github.com/zopefoundation/z3c.jbot
Author: Zope Foundation and Contributors
Author-email: zope-dev@zope.dev
License: ZPL-2.1
Keywords: page template override
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Zope
Classifier: Framework :: Zope :: 3
Classifier: Framework :: Zope :: 5
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE.rst
Requires-Dist: setuptools
Requires-Dist: zope.pagetemplate
Requires-Dist: zope.component
Requires-Dist: zope.configuration
Requires-Dist: zope.security
Requires-Dist: zope.publisher
Provides-Extra: test
Requires-Dist: Zope; extra == "test"
Requires-Dist: Products.BTreeFolder2; extra == "test"
Requires-Dist: Products.CMFCore; extra == "test"
Requires-Dist: plone.resource; extra == "test"

Overview
========

The ``z3c.jbot`` (or "Just a bunch of templates") package allows easy
customization of existing templates and images. It works on Zope 2 and
Zope 3.

The Chameleon rendering engine is supported.

Use of this package adds a small (2-3 ms per request on Plone) to the
total application response time.

Usage
-----

To override a particular file, first determine its *canonical
filename*. It's defined as the path relative to the package within
which the file is located; directory separators are replaced with
dots.

Example:

  Suppose you want to override: /plone/app/layout/viewlets/logo.pt

  You would use the filename:   plone.app.layout.viewlets.logo.pt

Simply drop the file in a directory and register that directory for
use with jbot using a ZCML-directive::

  <include package="z3c.jbot" file="meta.zcml" />

  <browser:jbot
      directory="<path>"
      layer="<layer>" />

Templates in views, viewlets and portlets
-----------------------------------------

Any template that is defined as a class-attribute can be overriden
using jbot, e.g. those used in views, viewlets and portlets. The
template overrides may be registered for any request layer or only a
specific layer.

CMF objects
-----------

Any skin-object (e.g. images, templates) on the file system (directory
views) can be overridden.

Plone resources
---------------

If `plone.resource` is installed, it's possible to use jbot to
override filesystem resources.

Deprecation warnings
--------------------

Imagine this situation:

* You have a ``base`` package with a page template ``original.pt``.
* Someone else overrides this in a project specific package by creating a file ``base.original.pt``.
* Now for some reason you rename the template to ``new.pt``.
* The template override in the project no longer works and the other person starts asking questions or complaining.

To solve this problem, you can register that a template path is deprecated.
First add a dictionary to the ``base`` package, let's say in a file ``utils.py``::

  deprecated_templates = {
      "base.original.pt": "base.new.pt",
  }

In your ``configure.zcml`` you add::

  <configure
      xmlns="http://namespaces.zope.org/zope"
      xmlns:zcml="http://namespaces.zope.org/zcml"
      >
  ...
    <configure zcml:condition="have jbot-deprecations">
      <include package="z3c.jbot" file="meta.zcml" />
      <browser:jbotDeprecated dictionary=".utils.deprecated_templates" />
    </configure>
  </configure>

The result is:

1. The old override ``base.original.pt`` works for the new location as well.
2. The user gets a warning that they should use ``base.new.pt`` instead.

Author
------

Malthe Borch <mborch@gmail.com>

Changes
=======

2.2 (2025-02-12)
----------------

- Add ``jbotDeprecated`` directive with ``dictionary`` as single argument.
  This can be used when you move templates and want an existing jbot
  override for the old template path to still work.
  [maurits]

- Add a ``jbot-deprecations`` ZCML feature to conditionally set deprecations.
  [ale-rt]

- Drop support for Python 3.8.

2.1 (2024-11-29)
----------------

- Add support for Python 3.12, 3.13.

- Drop support for Python 3.7.

- Fix error when Plone site is not yet set as in first index_html call on Zope.
  [bsuttor]


2.0 (2023-05-04)
----------------

- Add support for Python 3.9, 3.10, 3.11.

- Drop support for Python 2.7, 3.5, 3.6.


1.1.1 (2021-08-18)
------------------

- Fix error in find_zope2_product: "TypeError: expected str, bytes or os.PathLike object, not list".
  [jensens]


1.1.0 (2020-09-20)
------------------

- Added support for static resource registered using the "static"
  directive of `plone.resource`.
  [malthe]


1.0.0 (2020-08-25)
------------------

- Breaking: Remove long deprecated backward compatibility imports of getSite and setHooks.
  [jensens]

- Fix #8:  Broken on Windows (non case-sensitive filesystem).
  [jensens]

- Fix tests to run on ``windows``.
  [jensens]

- Add Github Actions testrunners for ``ubuntu``, ``windows``.
  [jensens]

- Run tests with Zope 4.5.
  [jensens]

- Breaking: Add and test/support for Python 3.8. Drop support for Python 3.5.
  [jensens]


0.8 (2018-11-07)
----------------

- Added support for Python 3.5, 3.6, 3.7; dropped support for 2.6.
  [ale-rt, pbauer]

- Fix: Be sure ignored templates will reread from disk.
  [ale-rt]

- Standardize namespace __init__

- Fix issue where zope.browserpage.viewpagetemplatefile.ViewPageTemplateFile
  was not using jbot overrides.
  [davisagli]

0.7.1 (2012-01-09)
------------------

- Fixed an issue where multiple registrations against the same layer
  would cause only one registration (decided randomly) to have effect.

  The lookup code now uses the specification resolution order to query
  for override registrations in order of specialization.
  [malthe]

0.7 (2012-01-05)
----------------

- Fixed issue where templates being patched by ``five.pt`` would not
  get properly jbotted.

- Use ``five.pt`` if available. [malthe]

- Fixed an issue where tests would fail on Zope 2.10. [malthe]

0.6.3 (2010-09-07)
------------------

- Fixed compatibility with Plone 3.x. [malthe]

0.6.2 (2010-02-17)
------------------

- Downgrade log messages to debug level. In normal operation they don't contain
  any valuable information. [hannosch]

- Prefer zope.site over zope.app.component if it is available. [hannosch]

0.6.1 (2010-02-09)
------------------

- Fix bungled release [optilude]

0.6.0 (2010-02-09)
------------------

- Zope 2.12 compatibility. [malthe]

- Added support for automatic configuration. [malthe]

- Fixed layer specialization ordering. [malthe]

0.5.3 (2009-10-31)
------------------

- ZCML-directive is now called ``jbot``. [malthe]

0.5.2 (2009-10-23)
------------------

- Fixed issue where an exception would be raised if a view was not an
  acquirer, while the context was. [gweis]

0.5.1 (2009-10-19)
------------------

- Acquisition-wrap template instance, if applicable. This fixes an
  issue on Zope 2.10 where legacy code would break.

0.5 (2009-10-16)
----------------

- Added support for CMF skin objects.

0.4 (2009-10-15)
----------------

- Added Chameleon-support.

- Reimplemented override logic; the total usage cost is now reduced to
  an insignificant amount. Meanwhile, only templates that are defined
  as class-attributes (e.g. on views, viewlets and portlets) can be
  overriden.

0.3 (2009-09-26)
----------------

- Improved test coverage.

- Refactored code, improving performance.

- Fixed issue with multiple layers.

0.2 (2008-07-14)
----------------

- Added layer support.

0.1 (2007-11-27)
----------------

- Initial public release.
