README

在页面列表中使用不同模板时很有用，它有助于避免冗余代码。

安装

将库包含在 composer.json 中

composer require xanweb/c5-page-info

简单使用示例

$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()]);
}

配置管理

您可以注册自己的配置以获取页面信息

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

预定义配置

1. 默认
   
   • 页面名称： [页面名称属性]
   • 页面描述： [页面描述属性]
   • 缩略图： ['thumbnail' 属性]
2. 基础
   
   • 页面名称： [页面名称属性]
   • 页面描述： [页面描述属性]
   • 缩略图： ['thumbnail' 属性, 图片块]
3. 高级
   
   • 页面名称： [页面标题块，页面名称属性]
   • 页面描述： [页面描述属性]
   • 缩略图： ['thumbnail' 属性, 图片块]
     如果安装了 'page_heading' 块（Xanweb 定制的块），则它将是
   • 页面名称： [页面标题块，页面名称属性]
   • 页面描述： [页面标题块，页面描述属性]
   • 缩略图： ['thumbnail' 属性, 图片块]

预定义配置使用示例

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

或者

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

如何覆盖 PageInfo 类

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