NAME
Rapi::Blog::Manual::Scaffolds - Public-facing content for Rapi::Blog
DESCRIPTION
Rapi::Blog serves public facing content from a local "scaffold" which is a simple directory of HTML and associated content, mounted at the root (/) of the app. The other, backend namespaces for the various controllers/modules are merged into the common root-based namespace. This design allows for the scaffolds to be structured as an ordinary HTML site following the same conventions as a static site living in a folder on your PC. The only difference between a Rapi::Blog scaffold and a static HTML directory is that files within the scaffold are able to *optionally* call template directives for dynamic content via simple variable substitution.
Scaffolds may also define an additional config which declares details about how it can be used by the backend. See below.
SCAFFOLD CONFIG
The scaffold config is defined in a YAML text file named scaffold.yml in the root of the scaffold directory.
The scaffold.yml supports the following options:
static_paths
List of path prefixes which are considered 'static' meaning no template processing will happen on those paths. You want to list asset/image dirs like 'css/', 'fonts/' etc in this param, which helps performance for paths which the system doesn't need to parse for template directives.
private_paths
List of path prefixes which will not be served publicly, but will still be available internally to include, use as a wrapper, etc. Note that this option isn't really about security but about cleaning the public namespace of paths which are known not to be able to render as stand-alone pages in that context (like snippets, block directives, etc etc)
landing_page
Path/template to render when a user lands on the home page at '/' (or the URL the app is mounted on)
not_found
Path/template to render when a requested path is not found (404). This provides a mechanism to have branded 404 pages. If not specified, a default/plain 404 page is used.
favicon
Path to the favicon to use for the site.
view_wrappers
The view_wrappers are what expose Posts in the database to public URLs. The view_wrappers are supplied as a list of HashRefs defining the config of an individual view_wrapper. For example:
view_wrappers:
- { path: post/, type: include, wrapper: private/post.html }For typical setups, only one view_wrapper is needed, but you can setup as many as you choose.
Each 'view_wrapper' config requires the following three params:
path
The path prefix to be exposed. The Post name is appended to this path to produce a valid URL for the given Post. Using the above example, a Post named 'my-cool-post' would be accessible at the public URL '/post/my-cool-post'.
wrapper
The scaffold template to use when rendering the Post. This should be a TT template which has been setup as a WRAPPER with a the Post body content loaded in [% content %]. The given Post row object will also be available as [% Post %].
type
Must be either 'insert' or 'include' to control which TT directive is used internally to load the Post into the [% content %] in the wrapper. With 'include' (default) the content of the template, along with its template directives, is processed in advance and then populated into the [% content %] variable, while with 'insert' the content is inserted as-is, leaving any directives to be processed in the scope of the wrapper. You shouldn't need to use 'insert' unless you have a specific reason and know what you are doing.
default_view_path
The default 'view_wrapper', identified by its configured path, to use for accessing posts. This is used in locations where the system generates URLs when it needs to publicly link to a post. Defaults to the first 'include' type view_wrapper.
preview_path
Optional alternative path to use instead of default_view_path for the purpose of rendering a "preview" of the post as it will display on the site. This preview is presented in an iframe on the "Publish Preview" tab on the internal Post row page. This is useful in case you want to use a different wrapper that excludes items like top navigation, sidebars, etc, and display just the post itself with the active styles on the site. It is totally optional, and for some cases you may prefer using the same exact view as the public site to be able to really see exactly how the post will look. This would be one of the common a cases for a second 'view_wrapper' to be defined.
internal_post_path
The one, "real" URL path used to access Posts *internally*. This is used by the view_wrappers internally to resolve the Post from the supplied URL. Defaults to 'private/post/' which shouldn't normally need to be changed. It is suggested that it be within a private (i.e. covered by 'private_paths') namespace.
default_ext
Default file extension for scaffold templates, defaults to html. This makes it so that the template '/path/to/doc.html' can alternatively be accessed at '/path/to/doc' for cleaner/nicer looking URLs
You may also define any additional datapoints you like in the scaffold config which can be used by the scaffold templates internally.
TEMPLATE DIRECTIVES
Files within the scaffold (which are not defined as static_paths) are processed as Template::Toolkit templates with the following methods/parameters exposed in the template variables (i.e. the Template::Stash):
scaffold
The active scaffold config/data structure.
list_posts
Interface to retrieve and filter Posts from the database. This is exposed with the ListAPI interface which accepts several named params and returns a common ListAPI result packet.
Accepted params (all optional):
search
String to search/filter results. The search will match substrings in the body, name, title, summary, body and exact match on a tag. Only Posts with at least one match will be returned.
tag
Limit posts to those containing the named tag.
limit
The maximum number of results to return (i.e. page size)
page
The page number to return, in conjunction with limit.
sort
Sort keyword for the order posts are returned in. Currently supports 3 possible values (defaults to newest)
newest
Newest (by Post Date/Time) Posts first
popularity
Posts with the most "Hits" first. Note that in order for a hit to be recorded, the scaffold must call the template directive [% Post.record_hit %].
most_comments
Posts with the most comments (includes sub-comments/replies) first
list_tags
Interface to retrieve and filter Tags from the database. This is exposed with the ListAPI interface which accepts several named params and returns a common ListAPI result packet.
Accepted params (all optional):
search
String to search/filter results. The search will match substrings of the tag name.
post_id
Limit results to Tags linked to the supplied post_id
sort
Sort keyword for the order tags are returned in. Currently supports 3 possible values (defaults to popularity)
popularity
Most popular tags by number of posts which use them.
alphabetical
Tags in alphabetical order.
recent
Most recently used (according to Post Date/Time) tags first.
list_users
Interface to retrieve and filter Users from the database. This is exposed with the ListAPI interface which accepts several named params and returns a common ListAPI result packet.
Accepted params (all optional):
search
String to search/filter results. The search will match substrings of the username or the full_name.
only
Limit users to those with the matching named permission, which are currently 'authors' or 'commenters'
User
The currently logged in user, or undef if not logged in. Returns a Rapi::Blog::DB::Result::User object.
request_path
The path of the current request
remote_action_path
URL path that a client can use to access the Remote controller which provides additional API end-points that can be used to post comments, etc.
add_post_path
URL path to directly load the "New Post" form. Useful if the scaffold wants to provide its own "New Post" links(s).
Post
When the target template of the request is a Post, including requests dispatched via a view_wrapper, 'Post' template variable will also be available. This will be a reference to the associated Post Row object (see Rapi::Blog::DB::Result::Post). For non-post requests (i.e. requests to ordinary templates within the scaffold) this value will be undef.
PRIVILEGED TEMPLATE DIRECTIVES
Both scaffold templates as well as post templates are able to access the above template directives/attributes, however, additional privileged directives are available to scaffold templates only (excludes view_wrappers which are processed in the role of a post)
c
A reference to the Catalyst context object for the current request. This provides an entrypoint to the entire application which can be used to perform actions based on the query string params (e.g. [% c.req.params.foo %], direct access to the database (e.g. [% c.model('DB::Post').search_rs(...) %]) or anything else which can be reached via the context.
SEE ALSO
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 112:
=back without =over