Uygulama yazma (eklentiler)

Uygulamalar, Antimatter'e içeriden özellik ekler: sunucuya kanca (hook) ile bağlanan Go dilinde bir sunucu kısmı ve menüler, paneller, ileti türleri ve sayfalar ekleyen React dilinde bir web uygulaması kısmı. Bu sayfa, uygulamaların nasıl düzenlendiğini, örnek olarak paketlenmiş Anket (Polls) uygulamasını kullanarak ve Antimatter'in Fusion arayüzünde nelerin değiştiğini gösterir.

Bir uygulamanın çalışma şekli

• Sunucu kısmı bir Go programıdır. Sunucu, bunu ayrı bir süreç olarak başlatır ve RPC üzerinden iletişim kurar: uygulamanın kancalarını (bir iletinin gönderilmek üzere olması, bir komutun çalıştırılması…) çağırır ve uygulama, sunucunun eklenti API'sini (bir iletinin oluşturulması, bir kullanıcının okunması, veri depolanması…) çağırır. Ayrıca /plugins/<app id>/ altında HTTP yolları da sunabilir.
• Web uygulaması kısmı, web uygulamasıyla birlikte tarayıcıya yüklenen bir JavaScript paketidir. registrant (kayıt defteri) ile React bileşenleri ve geri çağırma işlevleri (callback) kaydeder: bir menüdeki düğme, bir panel, bir ileti türünü çizme yöntemi.
• Herhangi bir kısım isteğe bağlıdır. Bir uygulama, .tar.gz paketi olarak kurulur ve sistem yöneticileri onu etkinleştirir, devre dışı bırakır ve yapılandırır.

Antimatter, Mattermost için yazılmış uygulamaları ve tersi, bir uygulama yalnızca her ikisinin de sahip olduğu kancaları kullandığı sürece çalıştırır. Yalnızca Antimatter'in sahip olduğu kancalar bölümüne bakın.

Paket düzeni

Ayrı bir başlangıç şablonu yoktur: antimatter-plugin-polls veya antimatter-plugin-todo gibi küçük bir paketlenmiş uygulamadan başlayın ve kimliğini (ID) ve kodunu değiştirin. Polls şu şekilde düzenlenmiştir:

antimatter-plugin-polls/
├── plugin.json            the manifest
├── Makefile               build, test, bundle, deploy
├── build/                 the manifest and pluginctl helper tools (Go), setup.mk
├── assets/icon.svg        files shipped with the bundle
├── go.mod
├── server/
│   ├── main.go            plugin.ClientMain(&Plugin{})
│   ├── plugin.go          the Plugin type, OnActivate, ServeHTTP
│   ├── manifest.go        generated from plugin.json
│   ├── api.go, command.go, hooks.go, store.go …
│   └── dist/              compiled binaries, one per platform
└── webapp/
    ├── package.json, webpack.config.js, tsconfig.json
    ├── i18n/              en.json and one file per language
    ├── src/index.tsx      registers the app with the web app
    ├── src/manifest.ts    generated from plugin.json
    ├── src/translations.ts
    └── dist/main.js       the bundle

İsteğe bağlı: /plugins/<app id>/public/ adresinde olduğu gibi sunulan bir public/ klasörü.

plugin.json

{
  "id": "com.example.weather",
  "name": "Weather",
  "description": "Forecasts in the chat.",
  "homepage_url": "https://github.com/example/weather",
  "support_url": "https://github.com/example/weather/issues",
  "icon_path": "assets/icon.svg",
  "version": "1.0.0",
  "min_server_version": "12.0.0",
  "server": {
    "executables": {
      "linux-amd64": "server/dist/plugin-linux-amd64",
      "linux-arm64": "server/dist/plugin-linux-arm64",
      "darwin-amd64": "server/dist/plugin-darwin-amd64",
      "darwin-arm64": "server/dist/plugin-darwin-arm64",
      "windows-amd64": "server/dist/plugin-windows-amd64.exe"
    }
  },
  "webapp": {"bundle_path": "webapp/dist/main.js"},
  "settings_schema": {"settings": []}
}

• id: benzersiz ve kalıcı; genellikle tersine çevrilmiş bir alan adı kullanılır. Yolları, depolanan ayarları ve WebSocket olaylarını adlandırır.
• version: anlamsal sürüm (semantic version). Paketlenmiş uygulamalar bunu plugin.json dosyasından hariç tutar; sürüm bilgilerini en son v* git etiketinden alır.
• min_server_version: Antimatter 12.0.0 sürümünü bildirir.
• settings_schema: Sistem Konsolu'ndaki uygulamanın ayarlar sayfası (bkz. Ayarlar).

make apply, manifest dosyasını server/manifest.go ve webapp/src/manifest.ts dosyalarına kopyalar; make manifest-check ise doğrular.

Sunucu bölümü

Sunucu bölümü, Mattermost uygulamalarıyla aynı Go modülünü, github.com/mattermost/mattermost/server/public modülünü, Go modül vekili (proxy) üzerinden alır. main fonksiyonu yalnızca uygulamayı başlatır:

package main

import "github.com/mattermost/mattermost/server/public/plugin"

func main() {
	plugin.ClientMain(&Plugin{})
}

Plugin tipi, plugin.MattermostPlugin tipini gömerek p.API erişimi sağlar ve ihtiyaç duyduğu kancaları (hooks) uygular:

type Plugin struct {
	plugin.MattermostPlugin
	router *mux.Router
}

func (p *Plugin) OnActivate() error {
	p.router = p.newRouter()
	return p.API.RegisterCommand(&model.Command{
		Trigger:          "weather",
		AutoComplete:     true,
		AutoCompleteDesc: "Show the forecast",
		AutoCompleteHint: "[city]",
	})
}

func (p *Plugin) ExecuteCommand(c *plugin.Context, args *model.CommandArgs) (*model.CommandResponse, *model.AppError) {
	city := strings.TrimSpace(strings.TrimPrefix(args.Command, "/weather"))
	return &model.CommandResponse{
		ResponseType: model.CommandResponseTypeEphemeral,
		Text:         "Forecast for " + city + ": sunny",
	}, nil
}

func (p *Plugin) ServeHTTP(c *plugin.Context, w http.ResponseWriter, r *http.Request) {
	p.router.ServeHTTP(w, r)
}

Yaygın kancalar

Tam liste, tam imzalarla birlikte, server/public/plugin/hooks.go dosyasında; API ise server/public/plugin/api.go dosyasındadır. pluginapi paketi (server/public/pluginapi), API'yi daha kullanışlı yardımcılarla sarar.

Yararlı API çağrıları

• CreatePost, UpdatePost, SendEphemeralPost: uygulamanın botu veya bir kullanıcı adına ileti gönderin.
• EnsureBotUser(&model.Bot{Username, DisplayName}): uygulamanın botunu bir kez oluşturun ve kimliğini (ID) alın.
• PublishWebSocketEvent("poll_updated", payload, &model.WebsocketBroadcast{ChannelId: id}): web uygulamasına bir olay gönderin. Olay, custom_<app id>_poll_updated olarak ulaşır.
• OpenInteractiveDialog: bir dialog açın.
• LogInfo, LogError ve benzerleri: sunucu günlüğüne, uygulamanın kimliğiyle (ID) etiketlenmiş olarak yazın.
• GetUser, GetChannel, HasPermissionToChannel: bir kullanıcı adına işlem yapmadan önce, kimin ne yapabileceğini kontrol edin.

Bir uygulama, kümenin her sunucusunda çalışır. Durumu yalnızca bellekte değil, anahtar-değer deposunda veya veritabanında saklayın.

Yapay zeka servisi

Antimatter sunucusu, uygulamalar adına yapay zeka modellerine, bir yöneticinin kurduğu model bağlantıları aracılığıyla (yönetici kılavuzundaki Yapay Zeka bölümüne bakın) istek gönderir. Bir uygulama asla bir sağlayıcının anahtarını tutmaz: hangi kişi adına ve nerede hareket ettiğini belirtir; sunucu, bu kişinin orada bu bağlantıyı kullanıp kullanamayacağını kontrol eder, sınırlarını ve bütçelerini uygular, tokenleri kişi ve uygulama adına sayar ve içeriği denetlemeden çağrıyı denetler.

Her isteğin ConnectionID değeri bağlantıyı, Model değeri ise bu bağlantının modellerinden birini seçer (boş bırakılırsa bağlantının varsayılanı kullanılır). Operation, kullanım ve denetim kayıtları için kısa bir etikettir; asla içerik değildir. Bunların minimum sunucu sürümü 11.11'dir.

Bu yöntemler ve ai paketi (server/public/ai), yalnızca Antimatter'in modül kopyasında mevcuttur; Mattermost tarafından yayınlanan sürümde bulunmaz. Bunları kullanmak için, go.mod dosyanızda bir replace satırıyla Antimatter'in server/public dizinine karşı derleme yapın; örneğin replace github.com/mattermost/mattermost/server/public => ../antimatter/server/public. Bu tür bir uygulama yalnızca Antimatter üzerinde çalışır.

Veri saklama

Her uygulamanın, sunucunun veritabanında kendi anahtar-değer deposu vardır:

• KVSet(key, value), KVGet(key), KVDelete(key): değerler bayt olarak, genellikle JSON biçimindedir. Anahtarlar en fazla 150 karakter olabilir.
• KVSetWithExpiry(key, value, seconds): değer bu süre dolunca silinir.
• KVCompareAndSet(key, old, new) ve Atomic ile KVSetWithOptions: birden fazla istek veya sunucu aynı anahtarı yazarken güvenli güncellemeler sağlar. Anket, her oyu bu şekilde kaydeder ve çakışma durumunda yeniden dener.
• KVList(page, perPage): anahtarlar, sayfa sayfa listelenir.

Web uygulaması bölümü

Yığın (bundle), window.registerPlugin ile bir sınıf kaydeder. initialize metodu kayıt defterini (registry) ve Redux deposunu alır:

import manifest from './manifest';

class Plugin {
    initialize(registry, store) {
        registry.registerTranslations((locale) => translationsFor(locale));
        registry.registerPostTypeComponent('custom_poll', PollPost);
        registry.registerWebSocketEventHandler(`custom_${manifest.id}_poll_updated`, (msg) => {
            store.dispatch(pollUpdated(JSON.parse(msg.data.poll)));
        });
        registry.registerReconnectHandler(() => store.dispatch(reloadPolls()));
    }
}

window.registerPlugin(manifest.id, new Plugin());

• Paylaşılan kütüphaneler. Web uygulaması React, ReactDOM, Redux, React Redux ve React Intl sağlar: bunları kendi kopyalarınızı yığmak (bundle) yerine webpack externals olarak listeleyin (React, ReactDOM, Redux, ReactRedux, ReactIntl). Anket'in webpack.config.js dosyasına bakın.
• Sunucu bölümünüzü çağırma. ${window.basename}/plugins/<app id>/… adresini, Client4.getOptions() (kaynağı mattermost-redux/client) ile gelen seçenekleri kullanarak getirin (fetch): bu seçenekler, sunucunun tarayıcıdan gelen isteği kabul etmesi için gereken başlıkları taşır.
• Kendi durumunuz. registerReducer bir reducer ekler; bu, state['plugins-<app id>'] altında saklanır.
• Tipler. Antimatter'in ek kayıt defteri (registry) yöntemleri, Mattermost'un yayımladığı tiplerde yer almaz: Anket, kullandığı kayıt defterini webapp/src/types/host.ts dosyasında tanımlar.

Kayıt defterinin (registry) yöntemleri ve parametreleri, webapp/fusion/src/plugins/registry.ts (Fusion) ve webapp/channels/src/plugins/registry.ts (klasik) dosyalarındaki kodda belgelenmiştir.

Fusion arayüzünü destekleme

Antimatter'in iki web arayüzü vardır: varsayılan olan Fusion ve klasik arayüz. İkisi de aynı uygulama yığınlarını (bundle) yükler ve aynı kayıt defterine (registry) sahiptir, ancak Fusion birçok öğeyi kendisi çizer ve eklenti bileşenlerini kendi yöntemine göre yerleştirir. Uygulamanızı her iki arayüzde de test edin.

Arayüzü algılama

Herhangi bir uygulama yüklenmeden önce, her iki arayüz de window.antimatterWebUI değerini 'fusion' veya 'classic' olarak ayarlar ve aynı değeri sayfanın kök öğesinde data-am-web-ui olarak belirler. Mattermost'ta bu değerlerden hiçbiri ayarlanmaz.

export function isFusionUI(): boolean {
    return window.antimatterWebUI === 'fusion' || document.documentElement.dataset.amWebUi === 'fusion';
}

Yerleşik uygulamalar, arayüzü farklı şekilde çizmek için bunu kullanır. Anketler, anket kartlarını ve oluşturma iletişim kutusunu Fusion stiline göre çizer ve Fusion'daki /poll komutu için kendi iletişim kutusunu açar. Aramalar ve Ses kanalları, Fusion'un kendi arama arayüzüyle değiştirdiği kenar çubuğu ve bildirim bileşenlerini hariç tutar. Ajanlar uygulaması, AI işlemlerini, kaydırma araç çubuğu yerine Diğer işlemler altında bir grup olarak ileti menüsüne yerleştirir. Bu uygulamaların arayüzle uyumlu olması için kullandığı şey, Fusion'un kendi CSS sınıfları (am- önekiyle) ve iletişim kutusu katmanı (am-layer öğesi)dir; bunlar belgelenmiş ve kararlı bir API değildir.

Fusion'un eklenti bileşenlerini gösterdiği yerler

Fusion'un göstermediği veya çalıştırmadığı öğeler

• registerPostDropdownMenuComponent (ilet menüsündeki bir bileşen), registerPostCardTypeComponent (sağdaki paneldeki bir gönderinin kartı) ve registerProductSwitcherMenuItem, Fusion'un ana görünümlerinde gösterilmez. İlki yerine registerPostDropdownMenuAction kullanın.
• registerMessageWillBeUpdatedHook, Fusion'da bir iletinin düzenlendiğinde çalışmaz. Düzenlemeleri sunucuda MessageWillBeUpdated kancasıyla kontrol edin.
• registerActionAfterChannelCreation yalnızca klasik kanal oluşturma iletişim kutusundan çalışır; Fusion bunu Kanal oluştur iletişim kutusundaki Diğer seçenekler… öğesinden açar.
• Uygulama çubuğu bileşenleri, supportedProductIds değerleri ne olursa olsun gösterilir.
• registerNeedsTeamRoute ve registerCustomRoute kaynaklı rotalar, ürünler gibi klasik sayfa çerçevesini korur.

Yalnızca Antimatter'da bulunan kancalar

Bu kayıt yöntemleri Mattermost'ta mevcut değildir. Uygulamanın orada da çalışabilmesi için bir yöntemi çağırmadan önce mevcut olup olmadığını kontrol edin:

if (typeof registry.registerComposerMenuItem === 'function') {
    registry.registerComposerMenuItem({
        text: 'Create a poll',
        icon: <i className='icon icon-chart-bar'/>,
        fusionIcon: 'poll',
        action: ({channelId, rootId}) => openPollCreation(channelId, rootId),
    });
} else {
    registry.registerChannelHeaderButtonAction(icon, (channel) => openPollCreation(channel.id), 'Create a poll', 'Create a poll');
}

Emoji seçicideki görünümleri ekleyin ve yönetin

Fusion'da bir emoji seçici sekmesi pickerKit özelliğine (prop) sahip olur: Emoji sekmesinin kendi ekleme ve yönetme görünümleri için kullandığı bileşenler, böylece bir sekmenin görünümleri aynı görünüme sahip olur ve seçici içinde kalır. GIFs ve Memes uygulamaları GIF'leri, çıkartmaları ve meme şablonlarını eklemek ve yönetmek için bunu kullanır. version (1), usePickerView ve useOnEscape hook'larını, PickerViewButtons (arama kutusunun yanındaki + ve yönetme düğmeleri), PickerViewFrame (geri oku olan bir görünüm), PickerNotice, PickerField, PickerSearch, PickerDropZone ve PickerManageList bileşenlerini içerir. Escape tuşu, bir görünümden sekmenin ızgarasına geri döner. Özelliğin mevcut olduğundan emin olun: diğer konaklar (hosts) bunu hariç tutar ve bu durumda sekme kendi diyaloglarını korur. Tipler webapp/fusion/src/types/store/plugins.ts (EmojiPickerTabProps) ve bileşenler webapp/fusion/src/fusion/popovers/picker_views.tsx dosyasında bulunur.

Paneli yeni bir pencerede

Fusion, registerRightHandSidebarComponent bileşenine iki ek prop verir; böylece Yeni pencerede aç paneli uygulama ana sayfasında değil, bulunduğu yerde açar:

• setPanelState(state): panel yer değiştirdiğinde çağırın. Kısa bir dize, örneğin 'note/<id>' veya 'board/<id>/card/<id>', veya ana sayfasında null kullanın. Bu değer pencerenin adresine yazılır, bu yüzden gizli bilgiler asla içermemelidir. 512 karakterden uzun veya denetim karakterleri içeren durumlar düşürülür.
• initialPanelState: yeni pencerede panelin sahip olduğu durum veya undefined. Bunu güvensiz bir girdi olarak ele alın: öğeyi oturum açan kişi olarak yeniden getirin ve kişi öğeyi açamıyorsa uygulamanın ana sayfasını veya bulunamadı görünümünü gösterin.

Panel kapatıldığında veya başka bir uygulamanın paneli onun yerini aldığında durum unutulur. Bir panelin penceresini kendiniz açmak için popoutRhsPlugin (aynı zamanda window.WebappUtils.popouts içinde) durumu isteğe bağlı beşinci argüman olarak alır. Not, Beyaz tahta, Yapılacaklar, Kanban ve Playbook'lar bunu kullanır.

fusionIcon, Fusion'un simge setindeki bir simgeyi belirtir (örneğin poll, sticker, calendar veya image; bkz. webapp/fusion/src/fusion/components/icon). Fusion, icon yerine bunu gösterir, böylece öğe diğerleriyle uyumlu olur.

Ayarlar

plugin.json içindeki settings_schema, uygulamanın Sistem Konsolu › Uygulama ekleri sayfasını açıklar:

"settings_schema": {
  "header": "Forecasts come from the weather service below.",
  "settings": [
    {"key": "ServiceURL", "display_name": "Service URL", "type": "text", "default": "https://api.example.com"},
    {"key": "Units", "display_name": "Units", "type": "dropdown", "default": "metric",
     "options": [{"display_name": "Celsius", "value": "metric"}, {"display_name": "Fahrenheit", "value": "imperial"}]},
    {"key": "EnableAlerts", "display_name": "Severe weather alerts", "type": "bool", "default": false,
     "help_text": "Post alerts in the channels that follow a city."}
  ]
}

Ayar türleri: bool, text, longtext, number, dropdown, radio, generated (rastgele bir gizli anahtar), username ve custom (web uygulaması bölümünün registerAdminConsoleCustomSetting ile kaydettiği bir bileşen tarafından çizilir). Ayarlar sections içinde gruplandırılabilir.

Sunucu bölümü, alanları anahtarlarla eşleşen bir yapıya (struct) okur:

type configuration struct {
	ServiceURL   string
	Units        string
	EnableAlerts bool
}

func (p *Plugin) OnConfigurationChange() error {
	var cfg configuration
	if err := p.API.LoadPluginConfiguration(&cfg); err != nil {
		return err
	}
	p.setConfiguration(&cfg)
	return nil
}

Yöneticiler, bunları yapılandırmada, PluginSettings.Plugins.<app id> altında, küçük harfli anahtarlarla da ayarlayabilir (bkz. yönetici kılavuzu).

Çeviriler

Antimatter 37 dile çevrilmiştir ve paketlenen uygulamalar da öyle. Web uygulaması bölümü bunu şu şekilde yapar:

1. Tüm dizeleri React Intl ile, bir kimlik (ID) ve İngilizce metniyle yazın: <FormattedMessage id='polls.create' defaultMessage='Create a poll'/> veya defineMessages. Kimliklerin başına uygulamanızın adını ekleyin.
2. İngilizce dizeleri webapp/i18n/en.json dosyasına çıkarın (paketlenen uygulamalar formatjs extract kullanır).
3. Yanına, aynı kimliklere sahip her dil için bir dosya ekleyin: fr.json, de.json, pt-BR.json, zh-CN.json…
4. Bunları web uygulamasına verin; kullanıcıdan dilini ister:

   import fr from '../i18n/fr.json';
   import ptBR from '../i18n/pt-BR.json';
   
   const catalogs = {fr, 'pt-BR': ptBR};
   
   export function translationsFor(locale) {
       return catalogs[locale] || catalogs[locale.split('-')[0]] || {};
   }
   
   registry.registerTranslations(translationsFor);

Eksik bir dize, İngilizce defaultMessage değerine geri düşer. Sunucu tarafının gönderdiği dizeler için (komut yanıtları, bot iletileri) pluginapi/i18n paketi, paketle birlikte gelen çeviri dosyalarını (örneğin assets/i18n) yükler ve her kullanıcı için kendi dilinde bir yerelleştirici sağlar.

Derleme, kurulum ve hata ayıklama

Go ve Node.js (uygulamanın .nvmrc dosyasındaki sürüm) gerekir. Uygulamanın klasöründe:

make deploy ve diğer sunucu komutları, bir yerel mod soketi bulduklarında onu kullanır (/var/tmp/antimatter_local.socket veya AM_LOCALSOCKETPATH): bunları yerel mod açıkken sunucunun makinesinde çalıştırın. Aksi halde MM_SERVICESETTINGS_SITEURL ile belirtilen sunucuya AM_ADMIN_TOKEN veya AM_ADMIN_USERNAME ve AM_ADMIN_PASSWORD ile giriş yaparlar. Derleme araçları henüz site URL'si için bir AM_ adını okumaz.

Bir paketi elle kurun

• Bir sistem yöneticisi, AM_PLUGINSETTINGS_ENABLEUPLOADS=true ayarıyla yüklemelere izin verir (varsayılan olarak kapalıdır; Sistem Konsolu'nda bir anahtarı yoktur).
• Ardından Sistem Konsolu › Uygulama ekleri › Uygulama eki yönetimi › Uygulama eki yükle veya amctl plugin add weather.tar.gz ardından amctl plugin enable com.example.weather.
• Sunucuda Uygulama eki imzası istensin seçeneği açıksa, yalnızca güvendiği bir anahtarla imzalanmış paketleri kabul eder; bkz. Diğer uygulamaların yüklenmesi.