Templates are a quick way of reusing the same layouts between different components and even projects. To accommodate this process imola introduces a simple template engine.
Creating templates
Templates can be created via gridTemplate().
They are collections of arguments that can be passed to a grid or flex function.
In practice this means they share all the properties of those arguments, including:
- Support for breakpoints
- Allowing both css notation (a string with values separated by a space) or vector notation (a vector where each element is a value).
It is important to note that templates require a name and a type.
The name is simply an identifier for the template (useful later for registering templates) and the type defines what type of functions it can be used for (grid or flex).
Trying to apply a template of the wrong type to a panel or page function is not possible.
mytemplate <- gridTemplate("myareas", "grid",
areas = list(
default = c(
"area1 area1 area1",
"area2 area3 area3",
"area2 area3 area3"
),
xs = c(
"area1",
"area2",
"area3"
)
),
gap = "20px"
)We can then use this template object as a value for the template argument in grid panels or pages:
#in ui.R
gridPanel(
id = "somePanel"
template = mytemplate
area1 = div("area 1 content"),
area2 = div("area 2 content"),
area3 = div("area 3 content")
)Registering templates
Registered templates are templates that are either bundled with imola, or added to the global template list by using registerTemplate() on a template object.
You can view all registered templates by using listTemplates().
By registering a template you are making it available outside of the scope where it is created, meaning it will be available to use even if the object itself was created somewhere else.
This approach allows us to create and register templates before they are needed, making them easier to bundle and manage when a lot of templates are needed.
#in global.R
mytemplate <- gridTemplate("myareas", "grid",
areas = list(
default = c(
"area1 area1 area1",
"area2 area3 area3",
"area2 area3 area3"
),
xs = c(
"area1",
"area2",
"area3"
)
),
gap = "20px"
)
# register it globally
registerTemplate(mytemplate)Calling registerTemplate() on a gridTemplate() object adds that template available to use in any page or panel page directly by its name:
#in ui.R
gridPanel(
id = "somePanel"
template = "myareas"
area1 = div("area 1 content"),
area2 = div("area 2 content"),
area3 = div("area 3 content")
)If needed you can also remove a template from the global list using unregisterTemplate("name", "type"):
# unregister a template
unregisterTemplate("myareas", "grid")Registered templates can also be turned back into a template object using getTemplate(). This object can then be used and if created with gridTemplate().
Bundled templates
By default imola also includes some ready to use templates. Similar to manually registered templates these are also listed under listTemplates().
These can be used just like registered templates, with the difference that they do not require manually registering them:
#in ui.R
gridPanel(
template = "header-sidebar-right"
header = div("header"),
content = div("content"),
sidebar = div("sidebar")
)For a demo on all templates bundled with imola, click here
Importing and Exporting
It is also possible to import and export template objects for future usage in different projects. In this case you can make use of exportTemplate() and importTemplate().
exportTemplate() allows you to export a template object into a specific file.
This file will contain all the necessary information to rebuild the template, even in a different project, and can be turned back into a template object using importTemplate().