includePartial()

Signature

includePartial() — returns string

Available in: controller Category: Miscellaneous Functions

Description

Includes the specified partial file in the view. Similar to using cfinclude but with the ability to cache the result and use Wheels-specific file look-up. By default, Wheels will look for the file in the current controller’s view folder. To include a file relative from the base views folder, you can start the path supplied to partial with a forward slash.

Parameters

Name	Type	Required	Default	Description
partial	any	yes	—	The name of the partial file to be used. Prefix with a leading slash (/) if you need to build a path from the root views folder. Do not include the partial filename’s underscore and file extension. If you want to have Wheels display the partial for a single model object, array of model objects, or a query, pass a variable containing that data into this argument.
group	string	no	—	If passing a query result set for the partial argument, use this to specify the field to group the query by. A new query will be passed into the partial template for you to iterate over.
cache	any	no	—	Number of minutes to cache the content for. The cache key is a hash of every argument passed to the partial, including the full contents (all rows) of a query argument, so editing a row produces a new cache key automatically. Pass any viewer state the output depends on (for example editable=true) as an argument so it becomes part of the key. Partial caching runs only when the cachePartials setting is on — on in production, off in development and testing.
layout	string	no	—	The layout to wrap the content in. Prefix with a leading slash (/) if you need to build a path from the root views folder. Pass false to not load a layout at all.
spacer	string	no	—	HTML or string to place between partials when called using a query.
dataFunction	any	no	true	Name of controller function to load data from.
$prependWithUnderscore	boolean	no	true

Examples

// 1. Include a partial from the current controller's view folder.
//    When in the "sessions" controller, Wheels looks for "app/views/sessions/_login.cfm".
#includePartial("login")#

// 2. Include a partial relative to the root views folder using a leading slash.
//    Wheels looks for "app/views/shared/_button.cfm".
#includePartial(partial="/shared/button")#

// 3. Pass a query to loop through records automatically.
//    Wheels loops through the result set and renders "app/views/posts/_post.cfm" for each row.
posts = model("Post").findAll();
#includePartial(posts)#

// 4. Override the template when rendering a query.
//    Provide the template path via partial and pass the query separately.
posts = model("Post").findAll();
#includePartial(partial="/shared/post", query=posts)#

// 5. Pass a single model object — Wheels renders the matching partial for its model type.
post = model("Post").findByKey(params.key);
#includePartial(post)#

// 6. Override the template when rendering a single model object.
post = model("Post").findByKey(params.key);
#includePartial(partial="/shared/post", object=post)#

// 7. Pass an array of model objects — Wheels iterates and renders the partial for each.
posts = model("Post").findAll(returnAs="objects");
#includePartial(posts)#

// 8. Override the template when rendering an array of model objects.
posts = model("Post").findAll(returnAs="objects");
#includePartial(partial="/shared/post", objects=posts)#

// 9. Cache the partial output for 30 minutes to reduce processing overhead.
//     The cache key is a hash of every argument, including the full contents (all rows)
//     of a "query" argument, so editing a row produces a new cache key automatically —
//     there is no need to clear the cache by hand. Partial caching only runs when the
//     "cachePartials" setting is on (on in production, off in development and testing).
#includePartial(partial="sidebar", cache=30)#

// 9b. Caching a partial that renders a query, plus viewer-specific output.
//     The query's rows are part of the key, so the cache refreshes when the data changes.
//     Pass any state the output depends on (here whether the viewer may edit) as an
//     argument so it becomes part of the key and each variant is cached separately.
posts = model("Post").findAll();
#includePartial(partial="post", query=posts, editable=canEditPosts, cache=30)#

// 10. Group a query result set by a column before rendering.
//     Wheels splits the query into sub-queries grouped by "categoryId"
//     and passes each sub-query into "app/views/products/_product.cfm".
products = model("Product").findAll(order="categoryId");
#includePartial(partial="product", query=products, group="categoryId")#

// 11. Insert a separator string between each rendered partial in a loop.
posts = model("Post").findAll();
#includePartial(partial="post", query=posts, spacer="<hr>")#