README

内容

• 1. 安装
• 2. 数据设置
  • 2.1. 类型
  • 2.2. 模板
  • 2.3. 字段
  • 2.4. 实体
  • 2.5. 修订
• 3. 使用
  • 3.1. 通用路由
  • 3.2. EntityRepository
  • 3.3. 列表及其他数据
  • 3.4. 标准路径
  • 3.5. 值检索
• 4. 搜索索引

1. 安装

1. 在Composer中要求此包，运行composer require bozboz/jam
2. 将Larasoft\Jam\Providers\JamServiceProvider::class添加到config/app.php中的providers数组
3. 运行php artisan vendor:publish && php artisan migrate

2. 数据设置

2.1. 类型

实体类型是jam模式的最顶层。它们本质上可以被认为是模型，或者模型的一个逻辑分组，因为模板实际上包含字段。类型在服务提供者中定义。Jam自带“Pages”类型，因为大多数应用程序都需要一个。

当你注册一个类型时，你可以给它一个报表、链接构建器、菜单构建器和实体。如果留空，则将使用默认值。

如果你需要嵌套排序，应使用NestedType。

• report 用于列表示例的后台报表类。通常，除非你需要完全自定义的解决方案，否则不需要更改此设置。NestedType会自动将默认值切换为NestedReport。

  默认Larasoft\Admin\Reports\Report

• link_builder 这是负责知道其负责的类型应该生成哪些路径/URL的类。默认情况下，类型不会生成路径，因为假设不是每个实体都是一个独立的页面。如果你需要你的类型生成路径，你可以使用Larasoft\Jam\Entities\LinkBuilder，它将根据当前实体的嵌套生成单个路径，并更新任何子实体的路径。对于需要存在于多个URL下的复杂实体，可以扩展LinkBuilder类并添加自己的路径生成逻辑。从实体嵌套中生成的路径将被用作任何附加路径的规范路径。

  默认Larasoft\Jam\Entities\LinksDisabled

• menu_builder
  处理类型在后台菜单中的位置。类型将不会显示在菜单中，直到它们有基于其实体的模板。

  • Larasoft\Jam\Types\Menu\Hidden不在菜单中显示
  • Larasoft\Jam\Types\Menu\Content在内容下拉菜单中显示
  • Larasoft\Jam\Types\Menu\Standalone作为顶级菜单项显示

  默认Larasoft\Jam\Types\Menu\Content

• search_handler Jam内置了对Elastic Search的基本支持，但默认情况下是禁用的。参见4. 搜索索引。

• entity Jam中有几种不同的实体类，用于指定排序选项。正常的Larasoft\Jam\Entities\Entity不可排序，将按名称排序。Larasoft\Jam\Entities\SortableEntity可以手动排序，但单独使用时仅允许兄弟排序。如果需要嵌套排序，则必须与Larasoft\Jam\Types\NestedType类型一起使用。最后还有Larasoft\Jam\Entities\Post实体，将按发布日期排序实体。

  默认Larasoft\Jam\Entities\Entity

2.2. 模板

一旦您有了需要的类型，就需要为它们提供一些模板。模板决定了实体具有哪些数据。类型可以有任意数量的模板。要添加模板，请登录到管理员界面，点击“Jam”，然后选择一个类型进行编辑。

在添加模板时，您必须提供它的名称和视图，但列表视图和最大使用次数是可选的。视图字段将在默认渲染方法中使用，以选择实际渲染的视图。列表视图的实现主要取决于需求，其目的是您可以在同一类型的多个模板中使用不同的视图。一旦创建了模板，管理员菜单将识别该类型，并在配置的菜单构建器指定的菜单中显示它。最大使用次数允许您限制模板的使用次数，例如，将其设置为1将在创建一个实体后隐藏使用该模板创建新实体的选项。

2.3. 字段

模板由一系列字段组成。Jam附带以下字段类型

• 文本
  标准单行文本输入。

• 文本区域
  标准多行文本输入，具有复选框选项，使其成为WYSIWYG HTML编辑器。

• 图片
  单个媒体库字段。

• 画廊
  多选媒体库字段。

• 日期

• 日期和时间

• 切换
  复选框用于切换布尔值。

• 实体列表
  允许创建多个子实体。用于重复内容结构，如滑块幻灯片、呼出框等。
  为了使用此字段类型，您必须首先设置另一个实体类型，该字段可以链接到它，使用Larasoft\Jam\Types\EntityList类型。
  例如：

  `php <?php $mapper = $this->app['EntityMapper'];

  $mapper->register([

    'callout-boxes' => new \Larasoft\Jam\Types\EntityList('Callout Boxes'),
  

  ]); `

• 属于
  允许您将一个实体链接到另一个实体。

  在创建/编辑表单中，所有创建的实体都将有选定的父实体。仅选择类型或模板将允许用户从所选类型/模板的实体中选择父实体。

  您还可以选择是否使具有此字段的实体成为相关实体的嵌套子页面。

  注意：不应与在同一列表中显示的不可排序实体一起使用，因为这可能导致意外的树形结构操作。

• 属于多个
  为实体表单提供从多个实体中选择以关联的选项。与属于一样，下拉菜单中的选项将限制为在添加字段到模板时所选的类型和模板。

• 反向属于多个（只读）
  是属于多个字段中定义的关系的反向，提供对相关实体的只读视图。

• 隐藏
  允许您在实体的创建/编辑表单中添加隐藏字段，当创建字段时将保存输入的值。

如果您需要上述未列出的任何功能（例如，定义实体模板与应用程序的未存储在Jam中的自定义模型之间的关系），您可以通过扩展Larasoft\Jam\Fields\Field类并使用在服务容器中注册的FieldMapper在服务提供程序中注册字段类型来创建任意数量的自定义字段类型。

2.4. 实体

通常，您不需要比包中默认的功能更多，您不应直接与实体类本身交互。有关如何使用不同的实体类的信息，请参阅2.4. 实体，有关如何获取实体信息，请参阅3.2. 实体仓库。

2.5. 修订

每次保存实体时，它都会在entity_revisions表中创建一个修订版，并生成一组新值。这允许您跟踪实体之间的更改或回滚到之前的状态。

3. 使用

3.1. 通用路由

默认情况下，Jam 没有设置任何前端路由，但确实有一个控制器，您的应用可以将一些路由指向它。

通常，您需要在路由文件的末尾添加一个通配符路由，以处理大多数甚至所有实体的路由。这将使用路径表根据请求路径查找实体，并在其配置的视图中提供。

<?php
Route::get('{entityPath}', [
    'as' => 'entity',
    'uses' => '\Larasoft\Jam\Http\Controllers\EntityController@forPath'
])->where('entityPath', '(.+)?');

3.2. EntityRepository

应使用 Larasoft\Jam\Repositories\EntityRepository 类的 forType 方法手动检索实体。这将返回一个针对已注册到类型的正确实体类的查询构建器，并限制为该类型的实体。

3.3. 列表及其他数据

某些页面可能需要比实体更多的数据，因此您需要为当前视图创建一个视图生成器。这些应添加到 app/Http/ViewComposers 中，并在 ComposerServiceProvider 服务提供器的 boot 方法中注册。

3.4. 标准路径

每个具有链接构建器的实体都将有一个规范路径，通常在从其他页面/菜单链接到它时将使用该路径。在查询实体时，应使用 withCanonicalPath 范围来预加载它，或者在处理集合时使用 loadCanonicalPath 方法来延迟加载它。使用 $entity->canonical_path 来输出它。

3.5. 值检索

仅查询实体将只会给出实体表中的数据，为了加载值，必须在单个或实体集合上调用 loadValues 方法。该方法接受一个要加载的字段列表，如果没有提供参数，则将加载所有字段。

例如：

<?php
$pages = $entityRepository->forType('page')->get()->loadFields('content', 'image');

4. 搜索索引

Jam 支持通过 Elasticsearch 索引实体，但每种类型都需要设置一个搜索处理器，请参阅 2.1. 类型。如果您只需要索引实体的名称，则可以使用基类 Larasoft\Jam\Entities\Indexer。在很可能需要更多的情况下，每种类型都需要为其编写一个处理器。在为实体类型设置搜索处理器类时，它应扩展基本 Indexer 类并重写 getPreviewData 和 getSearchableData 方法。

getPreviewData 的目的是将实体转换为适合您的搜索结果视图的格式，而 getSearchableData 是返回您想要作为单个长字符串可搜索的所有值。

例如：

<?php
protected function getPreviewData($page)
{
    return [
        'preview' => str_limit(strip_tags(
            $page->intro_text ?: $page->content
        ), 200),
        'image' => Media::getFilenameOrFallback($page->image, null, 'search-result'),
    ];
}

protected function getSearchableData($page)
{
    return strip_tags(implode(' ', [
        $page->intro_text,
        $page->content,
    ]));
}