アドストロフ管理のUIのカスタマイズ

This guide focuses on how to customize Apostrophe's administrative user interface, or "admin UI." The built-in functionality covers most situations, but sometimes you'll want to add or change functionality.

警告

UIを変更することはまれに慎重に行われるべきです.可能な場合は、カスタムスキーマフィールド型とカスタムマネージャーのビュー列のような新しい機能を追加します.必要に応じて完全にコンポーネントをオーバーライドしないように.

UIコンポーネントをオーバーライドすると、プロジェクトはそのコンポーネントに関連する将来のUI改善とバグ修正から恩恵を受けることができません.

目標を達成するためのより良い方法がないことを確認します.これにはasking for help in Discord and requesting or contributing コアの新機能.

アポストロフィ3の寿命中のある時点で.X私たちはVueに移行するつもりです.js 3X .私たちは、できるだけ多くの後方互換性を持つようにします、そして、コミュニティをタイムラインに意識させるようにします、しかし、カスタムAdmin UIコンポーネントをコーディングするとき、マイナーな変更が将来必要であるかもしれないと理解されなければなりません.

ファイルの構造
アポストロフィの管理者のUIはVueで実装されます.js多くから造られている.vue 様々なアポストロフィモジュールのファイル.これらは典型的にアポストロフィコアで見つけられますが、プロジェクトのどこにでもいます.これは、私たちがAdmin UIに我々自身のVueコンポーネントを加えることができるだけであることを意味します.vue ファイルをui/apos/components 任意のアポストロフィモジュールのサブディレクトリ.以下で説明するように、同じ名前のコンポーネントを供給することで既存のコンポーネントをオーバーライドすることも可能です.

変更を行うときにUIを再構築する
パフォーマンス上の理由から、アポストロフィプロジェクトは、コード変更時に自動的に管理者UIを再構築するように構成されていません.ほとんどのプロジェクトではカスタム管理のUIコードがないので、これは意味があり、ビルドする時間がかかります.
しかし、以下のようにすべてのコード変更でUIを再構築することができます.

APOS_DEV=1 npm run dev

便宜上、環境変数を端末セッションの間に設定したい場合があります.

export APOS_DEV=1

もちろん、管理UIは常に展開するときに再構築されます.特別な変更や環境設定は、生産用には必要ありません.

カスタムフィールド型の登録
アポストロフィschema field types カバー多くの状況が、我々は新しいものを追加したい場合があります.
以来、それ以上のトピックに触れるだけではなく、私たちはseparate article on how to add a custom field type . しかし、あなたが最初にその記事を読むならば、あなたはこの記事の残りに従うのがより簡単であるとわかります.

ピース型マネージャーへのカスタム列の追加
もう1つの一般的な拡張は、ピース型マネージャーのカスタム列です.既定では、Managerモーダルにはタイトル、特定のフラグ、および更新された最後の時間が表示されます.我々は、カスタムスターの評価を表示するには、この拡張することができます.

サーバーサイド部分の実装
簡単なピース型モジュールを見てみましょうreview それはstarRating field type we define in a separate article . 私たちはrating Page型のスキーマにフィールドを指定し、Managerモーダルで表示する列を追加します.

module.exports = {
  extend: '@apostrophecms/piece-type',
  fields: {
    add: {
      rating: {
        type: 'starRating',
        label: 'Star Rating',
        required: true
      }
    }
  },
  columns: {
    // 👇 Columns are a "cascade" just like fields,
    // we have an "add" property with a subproperty
    // for each column
    add: {
      rating: {
        // 👇 Each column has a label property and a
        // component property. The component name must
        // exist as a Vue component
        label: 'Rating',
        component: 'ColumnStarRating'
      }
    }
  }
};

ブラウザ側部分の実装
このコードはvueコンポーネントを参照します.ColumnStarRating , それはまだ存在しない.次に、そのコンポーネントを紹介します.

<template>
  <p
    class="apos-table__cell-field"
    :class="`apos-table__cell-field--${header.name}`"
  >
    <span v-if="hasValue">
      <span v-for="index in 5" :key="index" class="rating">{{ isActive(index) ? '☆' : '★' }}</span>
    </span>
    <span v-else>
      None
    </span>
  </p>
</template>

<script>
import AposCellMixin from 'Modules/@apostrophecms/ui/mixins/AposCellMixin';

export default {
  name: 'AposCellBasic',
  mixins: [ AposCellMixin ],
  computed: {
    hasValue() {
      return this.get(this.header.name) != null;
    }
  },
  methods: {
    isActive(index) {
      return index <= (this.get(this.header.name) || 0);
    }
  }
};
</script>

Vueコンポーネントを任意のモジュールに配置することができますが、それは最も意味をグループ化するためにstar-range-field モジュールではなく、review .
このコンポーネントはAposCellMixin 二つの重要なことを行う

コンポーネントは、アクセスすることによって、カラムの構成へのアクセスを得るheader prop.自動的にmixinで宣言されます.

コンポーネントは、呼び出しによってピースからプロパティを取得できますthis.get プロパティ名を指定します.アポストロフィの慣例に従って、このメソッドは、それが存在しない場合は、作品の公開バージョンから自動的に取得します.

標準Vueのオーバーライドコンポーネント名
ほとんどの場合、我々はアポストロフィと共に出荷するADIコンポーネントをオーバーライドする必要はありません.しかし、もし私たちに必要があれば、私たちは、標準のコンポーネントと同じ名前のファイルをui/apos/components プロジェクトレベルモジュールのサブディレクトリ.また、カスタムのNPMモジュールでは、プロジェクト間で再利用を達成するためにこれを行うことができます.
アポストロフィは、起動時に見つかったコンポーネントの最後のバージョンのみを使用します.一般的な起動順序は以下の通りです.

コアアポストロフィーモジュール

アプリケーションで設定されている順序で、プロジェクトレベルのモジュールをインストールします.js
たとえば、我々のプロジェクトのアプリの最後のモジュールの場合.JSモジュールリストには、UI/APOS/コンポーネント/aposlogpadlessが含まれます.Vueファイルは、そのロゴは、通常はアポストロフィコアまたは以前に設定した任意のモジュールから読み込まれるバージョンの代わりに管理バーで使用されます.

NOTE: For more information about the patterns used, props provided and APIs needed to override an existing core component, it's necessary to study the source code of the original.

標準Vueのオーバーライド構成によるJSコンポーネント
一つしかないAposDocsManager プロジェクト内のコンポーネント定義ですが、特定の型に対して異なる振る舞いをする必要があります.コアコンポーネントをオーバーライドし、条件付きロジックを追加することによってこれを回避することができますが、これは維持するのが困難なコードになります.また、複雑なコンポーネントのコピーを維持し、バグ修正や改良に失敗したことを意味します.特定のピースタイプを管理するために使用する、異なるカスタムコンポーネント名を指定する方が良いでしょう.
以下に例を示します.

module.exports = {
  extend: '@apostrophecms/piece-type',
  options: {
    components: {
      managerModal: 'AnnouncementManager'
    }
  }
}

この構成で、アポストロフィはVueを探すでしょう.jsコンポーネントAnnouncementManager ユーザーが管理バーから「発表」を選択すると、バイパスAposDocManager .
実際のVueは.JSコード、我々はそれを置くmodules/announcement/ui/apos/components/AnnouncementManager.vue .
もちろん、このようにオーバーライドすることができる他のコンポーネントがあり、リストは時間とともに成長しています.以下は、現在設定中のコンポーネントです.

読みやすさのために.オプションのサブプロパティを分離するために上記の表で使用されます(上記の例を参照してください.、@apostrophecms/piece-type これは、拡張モジュールを使用することができます.

クロージングノート
既存のページの種類を変更することができますので、1つのマネージャモーダルと1つだけのエディタのすべてのページのモードであり、これらのコンポーネント名は@apostrophecms/page モジュールです.ピースとウィジェットの型には、独自の型をオーバーライドできます.
オプションがModal , コンポーネントを埋め込むにはAposModal コンポーネント.たとえば、上記の既定のコンポーネントのソースコードを見てください.
The AposWidgetEditor コンポーネントは既に任意のウィジェットのスキーマを編集するためのモーダルダイアログボックスを提供していますので、ページ上で直接編集をサポートしない限り、置換を設定する必要はありません.AposRichTextWidgetEditor これを行う方法の例です.
The AposWidget コンポーネントは、典型的なサイトの訪問者の経験と何の関係もありません.ページが編集モードの間、我々のウィジェットを表示するときだけ、それは使われます.このコンポーネントをオーバーライドしている間は@apostrophecms/rich-text-widget モジュールは、リッチテキストウィジェットの「経験を編集する」を提供するようにします.もしあなたのウィジェットをフロントエンドJavaScriptで強化しようとしているなら、あなたはwidget player 代わりに.
エディタモードをオーバーライドする前にadding a custom schema field type 代わりに.