Skip to content

D
django-rest-framework
Commit 12c363c1 by Tom Christie
Options

TemplateHTMLRenderer, StaticHTMLRenderer

parent 44207a34
Showing with 70 additions and 17 deletions
docs/api-guide/renderers.md
...@@ -106,12 +106,12 @@ If you are considering using `XML` for your API, you may want to consider implem ...@@ -106,12 +106,12 @@ If you are considering using `XML` for your API, you may want to consider implem
**.format**: `'.xml'` **.format**: `'.xml'`
## HTMLRenderer ## TemplateHTMLRenderer
Renders data to HTML, using Django's standard template rendering. Renders data to HTML, using Django's standard template rendering.
Unlike other renderers, the data passed to the `Response` does not need to be serialized. Also, unlike other renderers, you may want to include a `template_name` argument when creating the `Response`. Unlike other renderers, the data passed to the `Response` does not need to be serialized. Also, unlike other renderers, you may want to include a `template_name` argument when creating the `Response`.
The HTMLRenderer will create a `RequestContext`, using the `response.data` as the context dict, and determine a template name to use to render the context. The TemplateHTMLRenderer will create a `RequestContext`, using the `response.data` as the context dict, and determine a template name to use to render the context.
The template name is determined by (in order of preference): The template name is determined by (in order of preference):
...@@ -119,27 +119,49 @@ The template name is determined by (in order of preference): ...@@ -119,27 +119,49 @@ The template name is determined by (in order of preference):
2. An explicit `.template_name` attribute set on this class. 2. An explicit `.template_name` attribute set on this class.
3. The return result of calling `view.get_template_names()`. 3. The return result of calling `view.get_template_names()`.
An example of a view that uses `HTMLRenderer`: An example of a view that uses `TemplateHTMLRenderer`:
class UserInstance(generics.RetrieveUserAPIView): class UserInstance(generics.RetrieveUserAPIView):
""" """
A view that returns a templated HTML representations of a given user. A view that returns a templated HTML representations of a given user.
""" """
model = Users model = Users
renderer_classes = (HTMLRenderer,) renderer_classes = (TemplateHTMLRenderer,)
def get(self, request, *args, **kwargs) def get(self, request, *args, **kwargs)
self.object = self.get_object() self.object = self.get_object()
return Response({'user': self.object}, template_name='user_detail.html') return Response({'user': self.object}, template_name='user_detail.html')
You can use `HTMLRenderer` either to return regular HTML pages using REST framework, or to return both HTML and API responses from a single endpoint. You can use `TemplateHTMLRenderer` either to return regular HTML pages using REST framework, or to return both HTML and API responses from a single endpoint.
If you're building websites that use `HTMLRenderer` along with other renderer classes, you should consider listing `HTMLRenderer` as the first class in the `renderer_classes` list, so that it will be prioritised first even for browsers that send poorly formed `ACCEPT:` headers. If you're building websites that use `TemplateHTMLRenderer` along with other renderer classes, you should consider listing `TemplateHTMLRenderer` as the first class in the `renderer_classes` list, so that it will be prioritised first even for browsers that send poorly formed `ACCEPT:` headers.
**.media_type**: `text/html` **.media_type**: `text/html`
**.format**: `'.html'` **.format**: `'.html'`
See also: `StaticHTMLRenderer`
## StaticHTMLRenderer
A simple renderer that simply returns pre-rendered HTML. Unlike other renderers, the data passed to the response object should be a string representing the content to be returned.
An example of a view that uses `TemplateHTMLRenderer`:
@api_view(('GET',))
@renderer_classes((StaticHTMLRenderer,))
def simple_html_view(request):
data = '<html><body><h1>Hello, world</h1></body></html>'
return Response(data)
You can use `TemplateHTMLRenderer` either to return regular HTML pages using REST framework, or to return both HTML and API responses from a single endpoint.
**.media_type**: `text/html`
**.format**: `'.html'`
See also: `TemplateHTMLRenderer`
## BrowsableAPIRenderer ## BrowsableAPIRenderer
Renders data into HTML for the Browseable API. This renderer will determine which other renderer would have been given highest priority, and use that to display an API style response within the HTML page. Renders data into HTML for the Browseable API. This renderer will determine which other renderer would have been given highest priority, and use that to display an API style response within the HTML page.
...@@ -207,7 +229,7 @@ In some cases you might want your view to use different serialization styles dep ...@@ -207,7 +229,7 @@ In some cases you might want your view to use different serialization styles dep
For example: For example:
@api_view(('GET',)) @api_view(('GET',))
@renderer_classes((HTMLRenderer, JSONRenderer)) @renderer_classes((TemplateHTMLRenderer, JSONRenderer))
def list_users(request): def list_users(request):
""" """
A view that can return JSON or HTML representations A view that can return JSON or HTML representations
...@@ -215,9 +237,9 @@ For example: ...@@ -215,9 +237,9 @@ For example:
""" """
queryset = Users.objects.filter(active=True) queryset = Users.objects.filter(active=True)
if request.accepted_media_type == 'text/html': if request.accepted_renderer.format == 'html':
# TemplateHTMLRenderer takes a context dict, # TemplateHTMLRenderer takes a context dict,
# and additionally requiresa 'template_name'. # and additionally requires a 'template_name'.
# It does not require serialization. # It does not require serialization.
data = {'users': queryset} data = {'users': queryset}
return Response(data, template_name='list_users.html') return Response(data, template_name='list_users.html')
......
rest_framework/renderers.py
...@@ -139,13 +139,24 @@ class YAMLRenderer(BaseRenderer): ...@@ -139,13 +139,24 @@ class YAMLRenderer(BaseRenderer):
return yaml.dump(data, stream=None, Dumper=self.encoder) return yaml.dump(data, stream=None, Dumper=self.encoder)
class HTMLRenderer(BaseRenderer): class TemplateHTMLRenderer(BaseRenderer):
""" """
A Base class provided for convenience. An HTML renderer for use with templates.
Render the object simply by using the given template. The data supplied to the Response object should be a dictionary that will
To create a template renderer, subclass this class, and set be used as context for the template.
the :attr:`media_type` and :attr:`template` attributes.
The template name is determined by (in order of preference):
1. An explicit `.template_name` attribute set on the response.
2. An explicit `.template_name` attribute set on this class.
3. The return result of calling `view.get_template_names()`.
For example:
data = {'users': User.objects.all()}
return Response(data, template_name='users.html')
For pre-rendered HTML, see StaticHTMLRenderer.
""" """
media_type = 'text/html' media_type = 'text/html'
...@@ -188,6 +199,26 @@ class HTMLRenderer(BaseRenderer): ...@@ -188,6 +199,26 @@ class HTMLRenderer(BaseRenderer):
raise ConfigurationError('Returned a template response with no template_name') raise ConfigurationError('Returned a template response with no template_name')
class StaticHTMLRenderer(BaseRenderer):
"""
An HTML renderer class that simply returns pre-rendered HTML.
The data supplied to the Response object should be a string representing
the pre-rendered HTML content.
For example:
data = '<html><body>example</body></html>'
return Response(data)
For template rendered HTML, see TemplateHTMLRenderer.
"""
media_type = 'text/html'
format = 'html'
def render(self, data, accepted_media_type=None, renderer_context=None):
return data
class BrowsableAPIRenderer(BaseRenderer): class BrowsableAPIRenderer(BaseRenderer):
""" """
HTML renderer used to self-document the API. HTML renderer used to self-document the API.
......
rest_framework/tests/htmlrenderer.py
...@@ -3,12 +3,12 @@ from django.test import TestCase ...@@ -3,12 +3,12 @@ from django.test import TestCase
from django.template import TemplateDoesNotExist, Template from django.template import TemplateDoesNotExist, Template
import django.template.loader import django.template.loader
from rest_framework.decorators import api_view, renderer_classes from rest_framework.decorators import api_view, renderer_classes
from rest_framework.renderers import HTMLRenderer from rest_framework.renderers import TemplateHTMLRenderer
from rest_framework.response import Response from rest_framework.response import Response
@api_view(('GET',)) @api_view(('GET',))
@renderer_classes((HTMLRenderer,)) @renderer_classes((TemplateHTMLRenderer,))
def example(request): def example(request):
""" """
A view that can returns an HTML representation. A view that can returns an HTML representation.
...@@ -22,7 +22,7 @@ urlpatterns = patterns('', ...@@ -22,7 +22,7 @@ urlpatterns = patterns('',
) )
class HTMLRendererTests(TestCase): class TemplateHTMLRendererTests(TestCase):
urls = 'rest_framework.tests.htmlrenderer' urls = 'rest_framework.tests.htmlrenderer'
def setUp(self): def setUp(self):
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment