--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/pyams_template/doctests/README.rst Tue Nov 26 10:09:41 2019 +0100
@@ -0,0 +1,103 @@
+======================
+pyams_template package
+======================
+
+This doctests are based on z3c.template doctests.
+
+First let's show how to produce content from a view:
+
+ >>> from pyramid.testing import setUp, tearDown
+ >>> config = setUp()
+
+ >>> import os, tempfile
+ >>> temp_dir = tempfile.mkdtemp()
+
+ >>> content_template = os.path.join(temp_dir, 'content-template.pt')
+ >>> with open(content_template, 'w') as file:
+ ... _ = file.write('<div>Base template content</div>')
+
+We can now register a view class implementing an interface:
+
+ >>> from zope.interface import implementer, Interface
+ >>> from pyams_template.interfaces import IContentTemplate, IPageTemplate
+
+ >>> class IMyView(Interface):
+ ... """View marker interface"""
+
+ >>> @implementer(IMyView)
+ ... class MyView:
+ ... template = None
+ ... def __init__(self, context, request):
+ ... self.context = context
+ ... self.request = request
+ ... def __call__(self):
+ ... if self.template is None:
+ ... template = config.registry.getMultiAdapter((self, self.request),
+ ... IContentTemplate)
+ ... return template()
+ ... return self.template()
+
+Let's now call the view and check the output:
+
+ >>> from pyramid.testing import DummyRequest
+ >>> root = object()
+ >>> request = DummyRequest()
+ >>> view = MyView(root, request)
+
+Since the template is not yet registered, rendering may fail:
+
+ >>> view()
+ Traceback (most recent call last):
+ ...
+ zope.interface.interfaces.ComponentLookupError: ...
+
+So let's now register the template; this is commonly done using "template_config" decorator, or
+using ZCML:
+
+ >>> from pyams_template.template import TemplateFactory
+ >>> factory = TemplateFactory(content_template, 'text/html')
+ >>> factory
+ <pyams_template.template.TemplateFactory object at ...>
+
+ >>> from pyramid.interfaces import IRequest
+ >>> config.registry.registerAdapter(factory, (Interface, IRequest), IContentTemplate)
+ >>> config.registry.getMultiAdapter((view, request), IPageTemplate)
+ <PyramidPageTemplateFile .../content-template.pt>
+
+ >>> print(view())
+ <div>Base template content</div>
+
+Now we can register another template for this view:
+
+ >>> my_template = os.path.join(temp_dir, 'my-template.pt')
+ >>> with open(my_template, 'w') as file:
+ ... _ = file.write('<div>This is my template</div>')
+ >>> factory = TemplateFactory(my_template, 'text/html')
+ >>> config.registry.registerAdapter(factory, (IMyView, IRequest), IContentTemplate)
+ >>> print(view())
+ <div>This is my template</div>
+
+It's generally easier to use a decorator to register templates:
+
+ >>> from pyramid.view import view_config
+ >>> from pyams_template.template import template_config
+
+ >>> my_other_template = os.path.join(temp_dir, 'my-other-template.pt')
+ >>> with open(my_other_template, 'w') as file:
+ ... _ = file.write('<div>This is my template for view 2</div>')
+
+ >>> @template_config(template=my_other_template)
+ ... class MyView2(MyView):
+ ... """Simple view subclass"""
+
+In testing mode we always have to register template manually because venusian can't scan test
+unit:
+
+ >>> factory = TemplateFactory(my_other_template, 'text/html')
+ >>> config.registry.registerAdapter(factory, (MyView2, IRequest), IContentTemplate)
+
+ >>> view = MyView2(root, request)
+ >>> print(view())
+ <div>This is my template for view 2</div>
+
+ >>> tearDown()
--- a/src/pyams_template/doctests/README.txt Tue Nov 26 10:09:26 2019 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,4 +0,0 @@
-======================
-pyams_template package
-======================
-