Abstract Blog Theme
Abstract Blog middleware for your Roadiz theme., (*1)
Inheritance
Your own theme entry class must extend AbstractBlogThemeApp instead of FrontendController to provide essential methods:, (*2)
use Themes\AbstractBlogTheme\AbstractBlogThemeApp;
class MyThemeApp extends AbstractBlogThemeApp
{
//ā¦
}
Dependency injection
Edit your own app/AppKernel.php to register Blog services:, (*3)
use Themes\AbstractBlogTheme\Services\BlogServiceProvider;
/**
* {@inheritdoc}
*/
public function register(\Pimple\Container $container)
{
parent::register($container);
$container->register(new BlogServiceProvider());
}
You must override these services in your custom theme:, (*4)
- blog_theme.post_container_entity
- blog_theme.post_entity
with your own node-type class names., (*5)
/**
* @param Container $container
*/
public static function setupDependencyInjection(Container $container)
{
parent::setupDependencyInjection($container);
$container->extend('blog_theme.post_container_entity', function ($entityClass) {
return NSBlogPostContainer::class;
});
$container->extend('blog_theme.post_entity', function ($entityClass) {
return NSBlogPost::class;
});
}
Add node-types
Abstract Blog theme declare 3 node-types to create your blog website:, (*6)
-
BlogFeedBlock: to create an automatic feed preview on any page
-
BlogPost: the main blog post entity
-
BlogPostContainer: the blog container to host every blog post
bin/roadiz themes:install --data Themes/AbstractBlogTheme/AbstractBlogThemeApp
bin/roadiz generate:nsentities
bin/roadiz orm:schema-tool:update --dump-sql --force
PostContainerControllerTrait
PostContainerControllerTrait will implement your indexAction by handling all request data
to provide your posts, filters and available tags to build your template., (*7)
IndexAction will assign:, (*8)
-
posts: found NodesSources array according to your criteria
-
filters: pagination information array
-
tags: available filtering Tag array
-
currentTag: Tag, array<Tag> or null
-
currentTagNames: array<string> containing current filtering tag(s) name for your filter menu template.
-
currentRelationSource: NodesSources or null containing the filtering related entity
-
currentRelationsSources: array<NodesSources> containing current filtering related entities(s) for your filter menu template.
-
currentRelationsNames: array<string> containing current filtering related entities(s) name for your filter menu template.
-
archives: available years and months of post archives
-
currentArchive: string or not defined
-
currentArchiveDateTime: \DateTime or not defined
Filtering
You can filter your post-container entities using Request attributes or query paramsĀ :, (*9)
-
tag: Filter by a tagā name using Roadiz nodesās tags field. You can pass an array of tag name to combine them.
-
archive: Filter by month and year, or just year on publishedAt field, or the one defined by getPublicationField method.
-
related: Filter by a related nodeā name using Roadiz nodesās bNodes field. You can pass an array of node name to combine them.
Usage
All you need to do is creating your PostContainer node-source's Controller in your theme and
implements ConfigurableController and use PostContainerControllerTrait.
You will be able to override any methods to configure your blog listing., (*10)
<?php
namespace Themes\MyTheme\Controllers;
use Themes\AbstractBlogTheme\Controllers\ConfigurableController;
use Themes\AbstractBlogTheme\Controllers\PostContainerControllerTrait;
use Themes\MyTheme\MyThemeThemeApp;
class BlogPostContainerController extends MyThemeThemeApp implements ConfigurableController
{
use PostContainerControllerTrait;
}
Multiple container controllers usage
If you have more than one blog-post type (Blogpost and PressReview for example), we advise strongly to create
an Abstract class in your theme using this Trait before using it, it will ease up
method overriding if you have multiple container controllers classes:, (*11)
<?php
namespace Themes\MyTheme\Controllers;
use Themes\AbstractBlogTheme\Controllers\ConfigurableController;
use Themes\AbstractBlogTheme\Controllers\PostContainerControllerTrait;
use Themes\MyTheme\MyThemeThemeApp;
abstract class AbstractContainerController extends MyThemeThemeApp implements ConfigurableController
{
use PostContainerControllerTrait;
// common methods overriding hereā¦
}
Then, simply inherit from your Abstract in your multiple container controller definitions:, (*12)
<?php
namespace Themes\MyTheme\Controllers;
class BlogPostContainerController extends AbstractContainerController
{
// override whatever you want
}
class PressReviewContainerController extends AbstractContainerController
{
// override whatever you want
}
Override PostContainerControllerTrait behaviour
Those methods can be overridden to customize your PostContainerControllerTrait behaviour., (*13)
-
getTemplate: By default it returns pages/post-container.html.twig. It will search in every registered themes for this template and fallback on @AbstractBlogTheme/pages/post-container.html.twig. Make sure your own theme have a higher priority.
-
getRssTemplate: By default it returns pages/post-container.rss.twig. It will search in every registered themes for this template and fallback on @AbstractBlogTheme/pages/post-container.rss.twig. Make sure your own theme have a higher priority.
-
throwExceptionOnEmptyResult: By default it returns true. It throws a 404Ā when no posts found.
-
getPostEntity: By default it returns $this->get('blog_theme.post_entity') as classname string. You can customize it to list other nodes.
-
isScopedToCurrentContainer: By default it returns false, PostContainerControllerTrait will fetch all blog-post no matter where
there are. If your overriden isScopedToCurrentContainer method returns true, all blog post will be fetched only from your
current container allowing you to create many blog containers.
-
isTagExclusive: returns true by default, match posts linked with all tags exclusively (intersection). Override it to false if you want to match posts with any tags (union).
-
getPublicationField: By default this method returns publishedAt field name. You can return whatever name unless field
exists in your BlogPost node-type.
-
getDefaultCriteria: returns default post query criteria. We encourage you to override getCriteria instead to keep default tags, archives and related filtering system.
-
getCriteria: Override default post query criteria, this method must return an array.
-
getDefaultOrder: By default this method returns an array :
[
$this->getPublicationField() => 'DESC'
]
-
getResponseTtl: By default this method returns 5 (minutes).
-
selectPostCounts: By default false: make additional queries to get each tagā post count to display posts count number in your tags menu.
-
prepareListingAssignation: This is the critical method which performs all queries and tag resolutions. We do not recommend overriding this method, override other methods to change your PostContainer behaviour instead.
-
getRelatedNodesSourcesQueryBuilder: if you want to fetch only one type related node-sources. Or filter more precisely.
You can override other methods, just get a look at the PostContainerControllerTrait fileā¦, (*14)
PostControllerTrait
PostControllerTrait will implement your indexAction by handling all request data
to provide a single post with its multiple formats., (*15)
Usage
All you need to do is creating your Post node-source'Controller in your theme and
implements ConfigurableController and use PostControllerTrait., (*16)
<?php
namespace Themes\MyTheme\Controllers;
use Themes\AbstractBlogTheme\Controllers\ConfigurableController;
use Themes\AbstractBlogTheme\Controllers\PostControllerTrait;
use Themes\MyTheme\MyThemeThemeApp;
class BlogPostController extends MyThemeThemeApp implements ConfigurableController
{
use PostControllerTrait;
}
Override PostControllerTrait behaviour
Those methods can be overridden to customize your PostControllerTrait behaviour., (*17)
-
getJsonLdArticle: By default it returns a new JsonLdArticle to be serialized to JSON or AMP friendly format.
-
getTemplate: By default it returns pages/post.html.twig. It will search in every registered themes for this template and fallback on @AbstractBlogTheme/pages/post.html.twig. Make sure your own theme have a higher priority.
-
getAmpTemplate: By default it returns pages/post.amp.twig. It will search in every registered themes for this template and fallback on @AbstractBlogTheme/pages/post.amp.twig. Make sure your own theme have a higher priority.
-
allowAmpFormat: By default it returns true.
-
allowJsonFormat: By default it returns true.
-
getResponseTtl: By default this method returns 5 (minutes).
Search engine with Solr
<?php
namespace Themes\MyTheme\Controllers;
use Themes\AbstractBlogTheme\Controllers\ConfigurableController;
use Themes\AbstractBlogTheme\Controllers\SearchControllerTrait;
use Themes\MyTheme\MyThemeApp;
class SearchController extends MyThemeApp implements ConfigurableController
{
use SearchControllerTrait;
}
searchPageLocale:
path: /{_locale}/search.{_format}/{page}
defaults:
_controller: Themes\MyTheme\Controllers\SearchController::searchAction
_locale: en
page: 1
_format: html
requirements:
# Use every 2 letter codes (quick and dirty)
_locale: "en|fr"
page: "[0-9]+"
_format: html|json
Add your search form in your website templates (use GET method to enable user history):, (*18)
<form method="get" action="{{ path('searchPageLocale', {
'_locale': request.locale
}) }}" data-json-action="{{ path('searchPageLocale', {
'_locale': request.locale,
'_format': 'json',
}) }}" id="search">
<input type="search" name="q">
<button type="submit">{% trans %}search{% endtrans %}</button>
</form>
Then create pages/search.html.twig template., (*19)
Override PostControllerTrait behaviour
-
getTemplate(): string
-
getAmpTemplate(): string
-
getJsonLdArticle(): JsonLdArticle
-
getResponseTtl(): string
-
allowAmpFormat(): boolean
-
allowJsonFormat(): boolean
Search result model
For JSON search responses, SearchControllerTrait uses JMS Serializer with a custom model to decorate your
node-sources and its highlighted text. By default SearchControllerTrait instantiates a Themes\AbstractBlogTheme\Model\SearchResult
object that will be serialized. You can override this model if you want to add custom fields according to your
node-sources data., (*20)
Create a child class, then override createSearchResultModel method:, (*21)
/**
* @param $searchResult
*
* @return SearchResult
*/
protected function createSearchResultModel($searchResult)
{
return new SearchResult(
$searchResult['nodeSource'],
$searchResult['highlighting'],
$this->get('document.url_generator'),
$this->get('router'),
$this->get('translator')
);
}
Youāll be able to add new virtual properties in your child SearchResult model., (*22)
AMP mobile page support
AMP format is supported for blog-post detail pages., (*23)
- Disable
display_debug_panel setting
- Add
?amp=1 after your blog-post detail page Url. Or add ?amp=1#development=1 for dev mode.
- Add amp
link to your HTML template:
{% block share_metas %}
{{ parent() }}
<link rel="amphtml" href="{{ url(nodeSource, {'amp': 1}) }}">
{% endblock %}
RSS format is supported for blog-post containers listing pages., (*24)
- Add RSS
link into your HTML template:
{% block share_metas %}
{{ parent() }}
<link rel="alternate" href="{{ url(nodeSource, {
'_format': 'xml',
'page': filters.currentPage,
'tag': currentTag.tagName,
'archive': currentArchive
}) }}" title="{{ pageMeta.title }}" type="application/rss+xml">
{% endblock %}
Templates
Resources/views/ folder contains useful templates for creating your own blog. Feel free to include
them directly in your theme or duplicated them., (*25)
By default, your Roadiz website will directly use AbstractBlogTheme templates.
You can override them in your inheriting Theme using the exact same path and name., (*26)
Twig extension
Functions
get_latest_posts($translation, $count = 4)get_latest_posts_for_tag($tag, $translation, $count = 4)-
get_previous_post($nodeSource, $count = 1, $scopedToParent = false): Get previous post(s) sorted by publishedAt.
Returns a single NodesSource by default, returns an array if count > 1.
-
get_previous_post_for_tag($nodeSource, $tag, $count = 1, $scopedToParent = false): Get previous post(s) sorted by publishedAt and filtered by one Tag.
Returns a single NodesSource by default, returns an array if count > 1.
-
get_next_post($nodeSource, $count = 1, $scopedToParent = false): Get next post(s) sorted by publishedAt.Ā
Returns a single NodesSource by default, returns an array if count > 1.
-
get_next_post_for_tag($nodeSource, $tag, $count = 1, $scopedToParent = false): Get next post(s) sorted by publishedAt and filtered by one Tag.
Returns a single NodesSource by default, returns an array if count > 1.
Filters
-
ampifize: Strips unsupported tags in AMP format and convert img and iframe tags to their AMP equivalent.
Wallogit.com
