Skip to content

Xanweb/c5-page-info

Repository files navigation

Concrete5 Page Info Fetcher

Latest Version on Packagist Software License

Useful in page lists when using different templates, it helps to avoid redundant code.

Installation

Include library to your composer.json

composer require xanweb/c5-page-info

Simple usage example

$pageInfoFactory = new Xanweb\PageInfo\Factory(); // We can pass our own config (Check `Config Management` section), otherwise default config will be used.
foreach ($pages as $page) {
    $pageInfo = $pageInfoFactory->build($page);
    $pageName = $pageInfo->fetchPageName($truncateChars, $tail); // Page name with htmlentites applied
                                                                //  $truncateChars: an optional argument can be passed to truncate description
    $pageDescription = $pageInfo->fetchPageDescription($truncateChars, $tail); // $truncateChars: an optional argument can be passed to truncate description
    $thumbnail = $pageInfo->fetchThumbnail($defaultThumbnail); // By default uses 'thumbnail' attribute.
    $formattedPublishDate = $pageInfo->getPublishDate($format); // Optionally you can pass format argument ('full', 'long', 'medium' or 'short') or a php custom format
    $formattedPublishDateTime = $pageInfo->getPublishDateTime(); 
    $authorUserInfo = $pageInfo->getAuthor(); 
    $lastEditedByUserInfo = $pageInfo->getLastEditor(); 
    $lastEditedByUserName = $pageInfo->getLastEditorUserName(); 
    $tags = $pageInfo->getTags(); 
    
    $linkTag = \HtmlObject\Link::create($pageInfo->getURL(), $pageName, ['target' => $pageInfo->getTarget()]);
}

Config Management

You can register your own config to fetch page information

use Xanweb\PageInfo\Fetcher\AttributePropertyFetcher;
use Xanweb\PageInfo\Fetcher\BlockPropertyFetcher;
use Xanweb\PageInfo\Fetcher\PagePropertyFetcher;

// Order of registering fetchers is important.
// The first registered will be firstly fetched. 
$config = $app->make(Xanweb\PageInfo\Config::class);

// if display_name attribute is filled for the page then it will be used otherwise the page name will be used
$config->registerPageNameFetcher(new AttributePropertyFetcher('display_name'));  
$config->registerPageNameFetcher(new PagePropertyFetcher(PagePropertyFetcher::PAGE_NAME));
$config->registerPageDescriptionFetcher(new PagePropertyFetcher(PagePropertyFetcher::PAGE_DESCRIPTION));

// Fetch thumbnail from a custom attribute
$config->registerThumbnailFetcher(new AttributePropertyFetcher('my_thumbnail_ak'));
// Fetch thumbnail from a block within the page. (requires installing "xanweb/c5-helpers" library)
$config->registerThumbnailFetcher(new BlockPropertyFetcher(
    'image', // Block Type handle 
    function ($bController) { // Method will be called to return thumbnail file if the block is found.
        return $bController->getFileObject();
    },
    // In case we have more than a block in the page, we may need to refine the fetching by making some checks
    // for the found block 
    function ($bController) { 
        return $bController->getFileObject() !== null;
    },
    // More refining also can be done by excluding some areas from fetching, example:
    ['Right Sidebar', 'Left Sidebar', 'Footer']
    )
);

$cfgManager = Xanweb\PageInfo\ConfigManager::get();

$cfgManager->register('my_cfg_key', $config);
// You can also register a callable, the config then will be created only it's called
$cfgManager->register('my_cfg_key', function () {
    $config = $app->make(Xanweb\PageInfo\Config::class);
    $config->register...
    
    return $config;
});

$myConfig = $cfgManager->getConfig('my_cfg_key');

Predefined Configs

  1. DEFAULT:
    • Page Name: [Page Name Property]
    • Page Description: [Page Description Property]
    • Thumbnail: ['thumbnail' attribute]
  2. BASIC:
    • Page Name: [Page Name Property]
    • Page Description: [Page Description Property]
    • Thumbnail: ['thumbnail' attribute, Image Block]
  3. ADVANCED:
    • Page Name: [Page Title Block, Page Name Property]
    • Page Description: [Page Description Property]
    • Thumbnail: ['thumbnail' attribute, Image Block]
      If 'page_heading' block (Custom block by Xanweb) is installed, then it will be:
    • Page Name: [Page Heading Block, Page Name Property]
    • Page Description: [Page Heading Block, Page Description Property]
    • Thumbnail: ['thumbnail' attribute, Image Block]

Example of using predefined config:

$myConfig = Xanweb\PageInfo\ConfigManager::getBasic();
$pageInfoFactory = new Xanweb\PageInfo\Factory($myConfig);

OR

$pageInfoFactoryWithDefaultConfig = new Xanweb\PageInfo\Factory();
$pageInfoFactoryWithBasicConfig = $pageInfoFactoryWithDefaultConfig->withConfig('basic');

How to override PageInfo class

class MyPageInfo extends \Xanweb\PageInfo\PageInfo {
    
}
$pageInfoFactory = new Xanweb\PageInfo\Factory($myConfig, MyPageInfo::class);