README

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);