A CMS a site is moved from: one module that is a mishka_installer plugin on the "migration:sources" event and implements the callbacks below. WordPress is the first (MishkaCmsMigration.Sources.WordPress); Joomla and others come the same way and reuse the mapping, the dry run, the import job and the report.

defmodule MyExtension.Sources.Ghost do
  use MishkaCmsMigration.Source, id: "ghost", label: "Ghost"
  use Gettext, backend: MishkaCmsCore.Gettext

  @impl true
  def kinds, do: ["user", "tag", "post"]

  @impl true
  def form_fields,
    do: [
      [
        name: :url,
        label: dgettext_noop("mishka_gervaz", "Address"),
        placeholder: "https://example.com",
        required: true
      ],
      [
        name: :secret,
        type: :password,
        label: dgettext_noop("mishka_gervaz", "Admin API key"),
        required: true
      ]
    ]

  @impl true
  def connect(%{"url" => url}, key), do: {:ok, Req.new(base_url: url, params: [key: key])}

  @impl true
  def list(req, kind, cursor) do
    ...
    {:ok, rows, next_cursor_or_nil}
  end

  @impl true
  def normalize(row, "post", _context),
    do: {:ok, %{source_id: row["id"], title: row["title"], content: [%{html: row["html"]}]}}
end

use makes the module a plugin on "migration:sources" — registering is the declaration; the event is never fired, and the plugin's call/1 hands its state back — and adds id/0, label/0, an extra/1 that answers %{}, which a source overrides to keep facts about itself, a host/1 that reads the connection's "url", a form_fields/0 that asks for an address and a secret, which a source overrides to ask for what it connects with, and a file?/0 that answers false, which a source that reads a file overrides. A source registers once it is supervised: an extension that ships one lists the module among the children of its own application's supervisor, as MishkaCmsMigration.Application.plugins/0 lists this extension's. Which sources are installed is read from mishka_installer's own registry (installed/2), so a source an operator stops in the installer is no longer offered and a run of it is refused.

A run

A run names its source by id/0 (MishkaCmsMigration.MigrationRun's source); a run of a source that is not installed is refused when it is created. A job (MishkaCmsMigration.Workers.Helpers.Pipeline) asks connect/2 once, with the run's connection map and its secret opened (MishkaCmsMigration.MigrationRun.open_secret/1), then walks kinds/0 in the order the source gives them, and pages through each with list/3 until it answers no cursor. The walk does not sort the kinds: a source lists them in the order they must be imported, a kind before any kind that points at it, so authors come before the posts that name them. Each listed row goes through normalize/3, which is handed the connection connect/2 answered to read more of the source when a row needs it (context/0), and then MishkaCmsMigration.Source.Item.build/1. An error from connect/2 or list/3 fails the run; an error from normalize/3 fails only that item, and the report says why.

A job of picked items, Dry run this item or Import this item on the Items page, walks only the kinds of those items and reads only their rows: rows/3 with their source ids, where the source has it, and otherwise every page of their kind from list/3, keeping the picked ones once they are normalized. rows/3 is optional; a source that reads a site over the network should have it, so one item never costs a walk of its whole kind.

Its connection form

The Migration page's New import opens one form for every source, and the form asks for what form_fields/0 names: the keys of the run's connection, as data, each the shape a Gervaz :key_map key takes (MishkaGervaz.Form.Types.Field.KeyMap):

• :name — the key the typed value is kept under in connection, as a string;
• :type — :text (the default), :password, :number, :select or another type a :key_map key takes;
• :label and :placeholder — msgids of the mishka_gervaz gettext domain, marked with dgettext_noop("mishka_gervaz", "..."), which the form translates as it draws them;
• :required — true marks the key's label as a required field's label is marked.

The key named :secret is the secret the source signs in with. Give it type: :password: it is drawn masked and never shown again, and creating the run takes it out of connection and keeps it only sealed (MishkaCmsMigration.MigrationRun.take_secret/2), so connect/2 gets it as its secret. Every other key, a :password one too, is kept in connection as typed, so a source has one secret, under :secret. A key left blank is not saved.

use asks for an Address (:url, required, https://example.com as its placeholder) and a Password or key (:secret, a required :password key). form_fields/1 reads the keys of the source a form was opened for.

A source that reads a file

A source that reads a file a site exported, rather than the site itself, answers true to file?/0 (MishkaCmsMigration.Sources.WordPressFile does) and names no keys in form_fields/0. The New import form then asks for the file instead of a Connection, and the run keeps it in a private folder until it ends (see "The source's file" in MishkaCmsMigration.MigrationRun): host/1 and connect/2 get its path as the connection's "file", and a refusal is shown on the form's file. file?/1 tells whether the source a form was opened for is one. use answers false.