Custom Post Templates

Feature overview

Some blogs have various “post types” that should be rendered differently to standard blog posts.

It’s currently possible to do this in a round-a-bout way by using (internal) tags, partials, and conditionals in post.hbs but it’s not ideal for certain site structures and can become unwieldy with many post types. When using such a setup the availability of different post types is hidden from authors by overloading the tags feature with theme/site-specific functionality.

With the Custom Post Templates feature theme authors will be able to create individual templates that are recognised as custom templates and exposed in the admin interface for selection by post authors.

Design

UI:

• display a “Template” section with a select dropdown (only when custom templates are available) after the page/feature checkboxes in the PSM

Technical:

• custom templates will be identified by the format custom-{{dasherized-name}}.hbs
  • they will be applicable to both posts and pages for now
  • the dasherized-name will be titleized to Dasherized Name for display in the UI
  • later iterations could incorporate front-matter in the templates themselves to provide theme authors a way to define a different name for the UI or to limit the template to posts or pages
• list of available custom templates for each theme provided as an attribute on the /themes/ and /themes/:name/ endpoints
  • client should ensure this info is cached to avoid unnecessary requests each time a post is opened
  • a differentiation needs to be made between post/page-{{slug}}.hbs templates and “shared” custom templates so that the client dropdown can display only the shared templates
  • available templates should also be returned when uploading/activating a theme
• if a post-{{slug}}.hbs or page-{{slug}}.hbs template exists and matches the post slug then that template has precedence and will override any custom template selection
  • if the client detects that the post slug matches a template then it should disable the custom template select with a message indicating which template will be used
• if a post has a custom template selected but that template is not available in the theme then rendering should fall back to the default post.hbs or page.hbs template

/themes/ & /themes/:name/ endpoint format

When fetching multiple or single themes the available templates will be included as an attribute on each member in the collection. Example fetching themes where one theme is installed and it contains a single custom, post, and page template:

GET /themes/

{
    "themes": [
        {
            "active": true,
            "name": "example-theme",
            "package": {
                "name": "Example Theme",
                "version": "0.1"
            },
            "templates": [
                {
                    "filename": "custom-news-bulletin.hbs",
                    "name": "News Bulletin",
                    "for": ["post", "page"],
                    "slug": null
                },
                {
                    "filename": "post-one.hbs",
                    "name": "One",
                    "for": ["post"],
                    "slug": "one"
                }
                {
                    "filename": "page-about.hbs",
                    "name": "About",
                    "for": ["page"],
                    "slug": "about"
                }
            ]
        }
    ]
}

custom-*.hbs templates are automatically assigned to both posts and pages post-*.hbs templates are automatically assigned to posts, with the slug calculated from the filename page-*.hbs templates are automatically assigned to pages, with the slug calculated from the filename

The filename attribute acts as a unique identifier.

The name attribute will be auto-generated from the filename by titleizing after removing the custom/post/page- prefix and file extension.

The for attribute will be used by the client to determine when custom templates aren’t available due to a slug-based template (post-*.hbs, page-*.hbs) taking precedence.

TODOs

• server
  • update GScan to recognise and expose custom templates
  • return templates attribute containing list of custom templates and any post/page-* templates as part of the /themes/ and /themes/:name/ responses
  • add custom-template field to the post model
  • allow custom-template to be set during saving
  • render custom template on front-end if specified and template exists
  • finish TODO’s from #9073
  • cache clear happens?
• client
  • fetch active theme with templates when editor is loaded - do not block rendering
  • display list of available templates in PSM when templates are available
  • disable template select if post slug matches known post/page template
  • test against server implementation + check styles
• documentation
  • publish new version on themes.ghost.org
    • update templates list on Structure page
    • update templates list and add custom templates description on Templates page
    • update changelog
  • notify Sarah (help.ghost.org)
  • dev blog post

[pascalandy]

This is really awesome!!

[oit63]

I find the reason, seems docker has cache the site, I restart docker container, it works!!!