LogoLogo
Official SiteAPI Reference
stable/3.0
stable/3.0
  • Cement Developer Guide
  • Release Information
    • What's New!
    • Upgrading
    • ChangeLog
    • Deprecations
  • Getting Started
    • Installation
    • Developer Tools
    • Framework Overview
    • Beginner Tutorial
      • Part 1: Creating Your First Project
      • Part 2: Adding Features
      • Part 3: Extending a Project
      • Part 4: Making Everything Legit
  • Core Foundation
    • Interfaces and Handlers
    • Hooks
    • Configuration Settings
    • Arguments
    • Logging
    • Controllers
    • Output Rendering
    • Caching
    • Mail Messaging
    • Framework Extensions
    • Application Plugins
    • Templating
  • Utilities
    • Filesystem
    • Shell
    • Miscellaneous
  • Extensions
    • Alarm
    • Argparse
    • Colorlog
    • ConfigParser
    • Daemon
    • Dummy
    • Generate
    • Jinja2
    • Json
    • Logging
    • Memcached
    • Mustache
    • Plugin
    • Print
    • Redis
    • Scrub
    • SMTP
    • Tabulate
    • Yaml
    • Watchdog
  • Additional Topics
    • Extending The App Object
    • Unit Testing
    • Cleanup
    • Signal Handling
    • Pipenv
    • Autocomplete
    • Profiling with cProfile
    • Debugging with VSCode
  • Environment Variables
  • Terminology
  • Contributing
  • Privacy Policy
Powered by GitBook
On this page
  • Introduction to the Output Interface
  • Configuration
  • Application Meta Options
  • Rending Output
  • Rendering Output via Templates
  • Template Directory Loading
  • Creating an Output Handler
  1. Core Foundation

Output Rendering

PreviousControllersNextCaching

Last updated 6 years ago

Introduction to the Output Interface

Cement defines an , as well as the default that implements the interface as a placeholder but does not actually produce any output.

Cement often includes multiple handler implementations of an interface that may or may not have additional features or functionality than the interface requires. The documentation below only references usage based on the interface and default handler (not the full capabilities of an implementation).

Cement Extensions That Provide Output Handlers:

API References:

Configuration

Application Meta Options

The following options under modify configuration handling:

Option

Description

output_handler

The handler that implements the output interface.

Rending Output

Cement applications do not need to use an output handler by any means. Most small applications can get away with simple print() statements. However, anyone who has ever built a bigger application that produces a lot of output will know that this can get ugly very quickly in your code.

Using an output handler allows the developer to keep their logic clean, and offload the display of relevant data to an output handler, possibly by templates or other means (GUI?).

An output handler has a render() function that takes a data dictionary to produce output. Some output handlers may also accept a template or other parameters that define how output is rendered. This is easily accessible by the application object.

from cement import App

with App('myapp' as app:
    app.run()

    # create a data dictionary
    data = {
        'foo': 'bar',
    }

    # render data dictionary
    app.render(data)

The above example uses the default dummy output handler, therefore nothing is displayed on screen. That said, for an example we can use the JSonOutputHandler to see something happen:

from cement import App

class MyApp(App):
    class Meta:
        label = 'myapp'
        extensions = ['json']
        output_handler = 'json'

with MyApp() as app:
    app.run()

    # create a data dictionary
    data = {
        'foo': 'bar',
    }

    # render data dictionary
    app.render(data)
$ python myapp.py
{"foo": "bar"}

Rendering Output via Templates

While some output handlers only require the data dictionary, others can utilize text templates to render formatted output to console.

myapp.py
from cement import App

class MyApp(App):
    class Meta:
        label = 'myapp'
        extensions = ['jinja2']
        output_handler = 'jinja2'
        template_dir = './templates'

with MyApp() as app:
    app.run()

    # create a data dictionary
    data = {
        'foo': 'bar',
    }

    # render data dictionary
    app.render(data, 'example.jinja2')
templates/example.jinja2
Example Jinja2 Template

{% if foo %}
    Foo => {{ foo }}
{% endif %}
$ python myapp.py
Example Jinja2 Template

    Foo => bar

Template Directory Loading

  • ~/.myapp/templates

  • ~/.config/myapp/templates

  • /usr/lib/myapp/templates

End-users can prepend their own paths to this list by setting the template_dir setting under the application configuration settings.

Once a template is found, loading stops and the template is rendered.

Creating an Output Handler

myapp.py
from cement import App
from cement.core.output import OutputHandler

class MyOutputHandler(OutputHandler):
    class Meta:
        label = 'my_output_handler'

    # do something to implement the interface

class MyApp(App):
    class Meta:
        label = 'myapp'
        output_handler = 'my_output_handler'
        handlers = [
            MyOutputHandler,
        ]

Template directories are looked for in the most common places by default as defined by :

All interfaces in Cement can be overridden with your own implementation. This can be done either by sub-classing itself, or by sub-classing an existing extension's handlers in order to alter their functionality.

Output Interface
DummyOutputHandler
Dummy
Json
Yaml
Jinja2
Mustache
Tabulate
Cement Core Output Module
App.Meta
App.Meta.template_dirs
OutputHandler