README

该扩展为消费 Nordkirche API 的扩展（nkc_address、nkc_event）提供了一些基本功能。包括

一个 NDK 的 ApiService
一个 NAPI 扩展的基础控制器
一个 TYPO3 后端 TCA 或 Flexform 字段，用于访问 NAPI 元素
一个用于与 NAPI 同步类别的调度器作业
一个用于预热地图标记缓存的调度器作业
用于输出和处理 NAPI 内容的各种 ViewHelper

要求

该扩展需要

nordkirche/NDK ^2.0
TYPO3 11.5

安装

由于在安装过程中需要安装所有依赖项，因此该扩展通过 composer 进行安装。

composer req nordkirche/nkc-base

然后，在扩展配置区域配置 NAPI 访问。您可以从 Nordkirche 的 AfÖ 获得您的 NAPI 访问。

作为替代，您可以在 AdditionalConfiguration.php 中保存配置。

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nkc_base'] = [
    'NDK_NAPI_PROTOCOL' => 'https',
    'NDK_NAPI_HOST' => 'www.nordkirche.de',
    'NDK_NAPI_PATH' => 'api/',
    'NDK_NAPI_PORT' => '443',
    'NDK_NAPI_VERSION' => '1',
    'NDK_NAPI_USER_ID' => '*******',
    'NDK_NAPI_ACCESS_TOKEN' => '*******',
    'NDK_NAPI_TIMEOUT' => 30
];

ApiService

APIService 仅提供静态方法，以简化 NDK 的初始化和使用

方法

ApiService::get()

调用时无需参数。该方法返回一个 NDK 实例。如果服务中尚未注册实例，则将创建一个新实例。服务将使用来自扩展配置（ext_conf_template.txt）的访问数据和配置。

ApiService::getRepository($object)

调用时需要一个 NAPI 对象名称（event、person、institution 等）。该方法返回对象的存储库，通过该存储库可以执行对 NAPI 的请求。

ApiService::getQuery($object)

调用时需要一个 NAPI 对象名称（event、person、institution 等）。该方法返回对象的查询，通过该查询可以构建查询。

ApiService::getAllItems($repository, $query, $includes = [], $pageSize = 50)

由于性能原因，NAPI 每个请求最多返回 99 个对象。可以通过分页获取更多对象。此方法是一个辅助程序，用于真正获取查询的所有对象。

$repository - Repository Instanz
$query - Query Instanz
$includes - ein Array mit den Includes (siehe NDK Dokumentation)
$pageSize - die Anzahl Objekte pro Abruf

代码示例

通过 API 工厂获取存储库实例

$api = \Nordkirche\NkcBase\ApiService::get();
$eventRepository = $api->factory(\Nordkirche\Ndk\Domain\Repository\EventRepository::class);

通过 ApiService 获取存储库实例

$eventRepository = \Nordkirche\NkcBase\ApiService::getRepository('event');

构建一个活动查询并对 NAPI 进行请求

$eventRepository = $api->factory(\Nordkirche\Ndk\Domain\Repository\EventRepository::class);
$eventQuery = \Nordkirche\NkcBase\ApiService::getQuery('event');

# Alle Veranstaltungen ab heute
$eventQuery->setTimeFromStart(new \DateTime(date('Y-m-d')));

$events = $eventRepository->get($eventQuery);
$allEvents = \Nordkirche\NkcBase\ApiService\ApiService::getAllItems($eventRepository, $eventQuery);

结果是 NAPI 对象的数组

错误处理

建议使用异常处理来处理对 NAPI 的请求，以防止前端出现 Ooops 消息，如果 NAPI 响应不够快或返回错误。对 NAPI 的请求的默认限制为 20 秒，并且可以通过扩展配置进行修改。

try {
    # Veranstaltungen holen
    $events = $eventRepository->get($eventQuery);
} catch (\Exception $e) {
    # Fehlerbahandlung
    ...
}

如果您想检查您的系统执行的哪些 NAPI 访问，可以定义一个日志文件，将所有请求记录到该文件中

    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nkc_base']['NDK_LOG_FILE'] = '/shared/ndk.log';

日志功能仅支持开发环境。

Extbase 扩展的基础控制器

基础控制器应该从基于 NAPI 的 Extbase 扩展继承

    class myFancyNapiController extends \Nordkirche\NkcBase\BaseController

该控制器包含一个 initializeAction 方法，在实现自己的 initializeAction 方法时应该调用它。

class myFancyNapiController extends \Nordkirche\NkcBase\BaseController {

    public function initializeAction()
    {
        parent::initializeAction();
    }
}

该方法初始化

$this->api
$this->napiService

此外，它将 Flexform 设置与 TypoScript 配置合并。

在

plugin.tx_myfancynapi_pi1.settings.flexformDefault {
    foo = bar
}

中的设置与 Flexform 字段合并，这些字段的命名模式如下

<settings.flexform.foo></settings.flexform.foo>

结果位于 Settings 数组中

$this->settings['flexform']

TCA Feld zur Auswahl von NAPI Objekten

对于后端，该扩展增加了一个新的 FormEngine 字段，可以用于选择 NAPI 元素。此字段可以用于 TCA 或 PlugIn Flexforms。

示例

<settings.flexform.eventCollection>
    <TCEforms>
        <label>Diese Veranstaltungen darstellen</label>
        <config>
            <type>user</type>
            <renderType>napiItemSelector</renderType>
            <allowed>event</allowed>
            <minItems>0</minItems>
            <maxItems>99</maxItems>
            <size>10</size>
        </config>
    </TCEforms>
</settings.flexform.eventCollection>

用于同步类别的调度任务

NAPI 使用类别，这些类别可以作为 Sys-Categories 被纳入自己的 TYPO3 系统中。此扩展提供了一个调度任务，例如每天执行一次。

重要：请注意，使用此任务时，将覆盖自行创建的类别。

用于 Map Cache Warmup 的调度任务

如果您想显示带有许多标记的地图，可以通过调度任务来预热标记的缓存。

在任务配置中指定受影响的页面元素（uid），这些元素将被考虑。

ViewHelper

在 ViewHelper 中，您可以找到相应的代码示例以供使用。

破坏性更改

由于 TYPO3 从版本 11.5 开始不再支持小部件，因此已移除 Paginate Widget。现在，Nkc 扩展将一个名为 "pagination" 的数组传递给模板，在 Partials 目录中提供了一个如何从该数组构建分页的示例。

Fluid 样式化内容布局

此扩展为 Fluid 样式化内容带来了一个默认布局。基于 nkc_base 的其他 Nordkirche 扩展通过 AJAX 加载内容，并使用 TypoScript CONTENT 对象。这种方法确保即使在 Extbase JSON 视图中，也会围绕内容放置一个 <div>。为了避免这种情况，提供了一个稍作调整的布局。

我们将在未来的版本中修改此功能，以使不再需要自定义布局。

发现错误了吗？

请通过 github（https://github.com/Nordkirche/nkc-base）报告错误。

nordkirche / nkc-base

维护者

详细信息