ColdBox HMVC Documentation
DocsSourceSupportTraining
7.x
7.x
  • Introduction
    • Contributing Guide
    • Release History
      • What's New With 7.4.0
      • What's New With 7.3.x
      • What's New With 7.2.0
      • What's New With 7.1.0
      • What's New With 7.0.0
        • Release Notes
    • Upgrading to ColdBox 7
    • What is ColdBox
    • What is MVC
    • About This Book
      • Author
  • For Newbies
    • 60 Minute Quick Start
      • Installing ColdBox
      • My First ColdBox Application
      • My First Handler & View
      • Linking Events Together
      • Working with Events
      • Adding A Layout
      • Adding A Model
      • RESTFul Data
      • Next Steps
    • Getting Started Guide
  • Getting Started
    • Installation
    • Application Templates
    • Conventions
    • Configuration
      • ColdBox.cfc
        • Configuration Directives
          • CacheBox
          • ColdBox
          • Conventions
          • Environments
          • Flash
          • InterceptorSettings
          • Interceptors
          • Layouts
          • LayoutSettings
          • LogBox
          • Modules
          • ModuleSettings
          • Settings
          • WireBox
        • System Settings (Java Properties and Environment Variables)
      • Using Settings
      • Bootstrapper - Application.cfc
  • The Basics
    • Request Context
    • Routing
      • Requirements
        • Rewrite Rules
      • Application Router
      • Routing DSL
        • Routing By Convention
        • Pattern Placeholders
        • Routing Methods
        • Resourceful Routes
        • Named Routes
        • Routing Groups
        • Routing Namespaces
      • Building Routable Links
      • RESTFul Extension Detection
      • HTTP Method Spoofing
      • HTML Base Tag
      • Pathinfo Providers
    • Event Handlers
      • How are events called?
      • Getting & Setting Values
      • Setting Views
      • Relocating
      • Rendering Data
      • Sending Files
      • Interception Methods
        • Pre Advices
        • Post Advices
        • Around Advices
      • Model Integration
        • Model Data Binding
      • HTTP Method Security
      • Implicit Methods
      • Executing Events
      • Executing Routes
      • Viewlets - Reusable Events
      • Event Caching
      • Validation
    • Layouts & Views
      • Views
        • Rendering Views
        • Rendering External Views
        • Rendering With Local Variables
        • Rendering Collections
        • View Caching
        • View Helpers
        • View Events
      • Layouts
        • Basic Layouts
        • Default Layout
        • Nested Layouts
        • Overriding Layouts
        • Layouts From A Module
        • Layout Helpers
        • Layout Events
      • Implicit Layout-View Declarations
      • Helpers UDF's
      • ColdBox Elixir
    • Models
      • Domain Modeling
        • Service Layer
        • Data Layers
        • Book
      • Conventions Location
      • WireBox Binder
      • Super Type Usage Methods
      • Injection DSL
        • ColdBox Namespace
        • CacheBox Namespace
        • EntityService Namespace
        • Executor Namespace
        • Java Namespace
        • LogBox Namespace
        • Models Namespace
        • Provider Namespace
        • WireBox Namespace
      • Object Scopes
      • Coding: Solo Style
        • Datasource
        • Contact.cfc
        • ContactDAO.cfc
        • ContactService.cfc
        • Contacts Handler
      • Coding: ActiveEntity Style
        • ORM
        • Contact.cfc
        • Contacts Handler
        • Views
      • Coding: Virtual Service Layer
        • ORM
        • Contacts.cfc
        • Contacts Handler
        • Views
      • Coding: ORM Scaffolding
        • ORM
        • Contacts.cfc
        • Scaffold
    • Interceptors
      • How do they work?
        • Conventions
      • Interceptor Declaration
      • Interceptor Registration
      • Dynamic Registration
      • Core Interception Points
        • Application Life Cycle Events
        • Object Creating Events
        • Layout-View Events
        • Module Events
        • CacheBox Events
      • Restricting Execution
      • Interceptor Output Buffer
      • Custom Events
        • Configuration Registration
        • Programmatic Registration
        • Listening
        • Announcing Interceptions
      • Unregistering Interceptors
      • Reporting Methods
      • Interceptor Asynchronicity
        • Async Announcements
        • Async Listeners With Join
        • Async Listeners No Join
        • Asynchronous Annotations
  • HMVC
    • Modules
      • Core Modules
      • Locations
      • Parent Configuration
      • Module Layout
        • Changing The Module Layout
      • Module Service
        • Module Lifecycle
        • Module Registration
        • Module Activation
        • Module Unloading
        • Common Methods
        • Loading New Modules
        • Loading A-la-carte Modules
        • Module Events
      • ModuleConfig
        • Public Module Properties
        • The Decorated Variables
        • The configure() Method
        • Module Settings
        • Environment Control
        • Interceptor Events
      • Module Event Executions
      • URL Routing
        • Default Route Execution
        • Module Routes Files
      • Module Async Scheduling
      • Request Context Module Methods
      • Layout and View Renderings
        • Layout/View Discovery
        • Overriding Views
        • Overriding Layouts
        • Default Module Layout
        • Explicit Module Renderings
      • Models
      • Module CF Mappings
      • Module Dependencies
      • Module Helpers
      • Module Bundles
      • Module Inception
  • Testing
    • Testing Quick Start
    • Testing ColdBox Applications
      • Test Harness
      • ColdBox Testing Classes
      • Testing Methods
      • Integration Testing
        • Test Annotations
        • Life-Cycle Events
        • Request Setup()
        • The execute() Method
        • HTTP Testing Methods
        • Testing Without Virtual Application
      • Interceptor Testing
      • Model Object Testing
      • Tips & Tricks
  • Digging Deeper
    • Async Programming
      • Async Pipelines & Futures
      • Parallel Computations
      • Executors
      • Scheduled Tasks
    • ColdBox Proxy
      • Getting Started
      • The Base Proxy Object
      • The Event Handlers
        • Distinguishing Request Types
        • RenderData()
      • Proxy Events
      • Standard Return Types
      • Caveats & Gotchas
    • Controller Decorator
    • ColdBox Scheduled Tasks
    • Flash RAM
      • Flash Storage
      • Using Flash RAM
      • Creating Your Own Flash Scope
    • HTML Helper
    • REST Handler
    • Request Context Decorator
    • Recipes
      • Building REST APIs
      • ColdBox Exception Handling
      • Debugging ColdBox Apps
      • Clearing the View Cache
      • Basic HTTP Authentication Interceptor
  • Architecture Concepts
    • How ColdBox Works
Powered by GitBook
On this page
  • Rendering Methods
  • view()
  • externalView()
  • layout()
  • Examples
  • Model Rendering

Was this helpful?

Edit on GitHub
Export as PDF
  1. The Basics
  2. Layouts & Views
  3. Views

Rendering Views

Last updated 10 months ago

Was this helpful?

Rendering Methods

We have now seen how to set views to be rendered from our handlers. However, we can use some cool methods to render views and layouts on demand. These methods exist in the Renderer, and several facade methods exist in the supertype, so you can call it from any handler, interceptor, view, or layout.

  1. view()

  2. externalView()

  3. layout()

Check out the latest for the latest arguments.

view()

/**
 * Render out a view
 *
 * @view                   The the view to render, if not passed, then we look in the request context for the current set view.
 * @args                   A struct of arguments to pass into the view for rendering, will be available as 'args' in the view.
 * @module                 The module to render the view from explicitly
 * @cache                  Cached the view output or not, defaults to false
 * @cacheTimeout           The time in minutes to cache the view
 * @cacheLastAccessTimeout The time in minutes the view will be removed from cache if idle or requested
 * @cacheSuffix            The suffix to add into the cache entry for this view rendering
 * @cacheProvider          The provider to cache this view in, defaults to 'template'
 * @collection             A collection to use by this Renderer to render the view as many times as the items in the collection (Array or Query)
 * @collectionAs           The name of the collection variable in the partial rendering.  If not passed, we will use the name of the view by convention
 * @collectionStartRow     The start row to limit the collection rendering with
 * @collectionMaxRows      The max rows to iterate over the collection rendering with
 * @collectionDelim        A string to delimit the collection renderings by
 * @prePostExempt          If true, pre/post view interceptors will not be fired. By default they do fire
 * @name                   The name of the rendering region to render out, Usually all arguments are coming from the stored region but you override them using this function's arguments.
 * @viewVariables          A struct of variables to incorporate into the view's variables scope.
 */
function view(
	view                   = "",
	struct args            = getRequestContext().getCurrentViewArgs(),
	module                 = "",
	boolean cache          = false,
	cacheTimeout           = "",
	cacheLastAccessTimeout = "",
	cacheSuffix            = "",
	cacheProvider          = "template",
	collection,
	collectionAs               = "",
	numeric collectionStartRow = "1",
	numeric collectionMaxRows  = 0,
	collectionDelim            = "",
	boolean prePostExempt      = false,
	name,
	viewVariables = {}
)

externalView()

/**
 * Renders an external view anywhere that cfinclude works.
 *
 * @view                   The the view to render
 * @args                   A struct of arguments to pass into the view for rendering, will be available as 'args' iview.
 * @cache                  Cached the view output or not, defaults to false
 * @cacheTimeout           The time in minutes to cache the view
 * @cacheLastAccessTimeout The time in minutes the view will be removed from cache if idle or requested
 * @cacheSuffix            The suffix to add into the cache entry for this view rendering
 * @cacheProvider          The provider to cache this view in, defaults to 'template'
 * @viewVariables          A struct of variables to incorporate into the view's variables scope.
 */
function externalView(
	required view,
	struct args            = getRequestContext().getCurrentViewArgs(),
	boolean cache          = false,
	cacheTimeout           = "",
	cacheLastAccessTimeout = "",
	cacheSuffix            = "",
	cacheProvider          = "template",
	viewVariables          = {}
)

layout()

/**
 * Render a layout or a layout + view combo
 *
 * @layout        The layout to render out
 * @module        The module to explicitly render this layout from
 * @view          The view to render within this layout
 * @args          An optional set of arguments that will be available to this layouts/view rendering ONLY
 * @viewModule    The module to explicitly render the view from
 * @prePostExempt If true, pre/post layout interceptors will not be fired. By default they do fire
 * @viewVariables A struct of variables to incorporate into the view's variables scope.
 */
function layout(
	layout,
	module                = "",
	view                  = "",
	struct args           = getRequestContext().getCurrentViewArgs(),
	viewModule            = "",
	boolean prePostExempt = false,
	viewVariables         = {}
)

Examples

<cfoutput>
// render inline
#view( 'tags/metadata' )#

// render from a module
#view( view="security/user", module="security" )#

// render a region
#view( name : "userLogins" )#

// render and cache
#view(
    view="tags/longRendering", 
    cache=true, 
    cacheTimeout=5, 
    cacheProvider="couchbase"
)#

// render a view from the handler action
function showData(event,rc,prc){
    // data here
    return view( "general/showData" );    
}

// render an email body content in an email template layout
body = layout( layout='email',view='templates/email_generic' );
</cfoutput>

Inline renderings are a great asset for reusing views and doing layout compositions

Model Rendering

If you need rendering capabilities in your model layer, we suggest using the following injection DSL:

property name="renderer" inject="provider:coldbox:renderer";
function sendEmail(){
    
    // code here.
    var body = renderer.view( "templates/email" );

}

This will inject a of a Renderer into your model objects. Remember that renderers are transient objects so you cannot treat them as singletons. The provider is a proxy to the transient object, but you can use it just like the normal object:

API Docs
provider