Öğretici 1: JavaScript ile merhaba dünya

Bu öğreticide en küçük işe yarar JavaScript eklentisini yazıyorsunuz: bir sayaç değişkeni, bir ayar sayfası, sayacı artıran bir aksiyon ve bir durum çubuğu öğesi. Tek ihtiyacınız bir metin düzenleyici ve çalışan bir Macro Grid sunucusu; derlenecek bir şey yok.

Bitmiş eklenti depoda examples/hello-js altında duruyor (HelloJs/ klasörünün bir kopyası, CI ikisini birebir aynı tutar). Aşağıdaki her kod bloğu bu klasörden alınmıştır.

Adım 1: klasör ve manifest

hello-js adında bir klasör oluşturun ve içine plugin.json dosyasını koyun:

{
  "id": "hellojs",
  "name": "Hello (JavaScript example)",
  "description": "A minimal JavaScript plugin: a counter variable, a settings page, one action and a status item.",
  "author": "Deccoyi",
  "homepage": "https://github.com/Deccoyi/macro-grid-plugin/tree/main/HelloJs",
  "version": "0.1.2",
  "minMacroGrid": "1.0.0",
  "sdkVersion": "^0.4.0",
  "minServerVersion": "0.3.2",
  "entry": "index.js",
  "kind": "js",
  "permissions": ["variables", "actions"]
}

• id benzersiz ve sabit olmalıdır. Değişken adları ve aksiyon türleri <id>. ile başlamalıdır (burada hellojs.).
• kind değeri js, entry ise çalışacak betiktir.
• permissions betiğin neye ihtiyaç duyduğunu listeler. variables değişken yayınlamasını, actions aksiyon kaydetmesini sağlar. Kullanıcı, betik çalışmadan önce tam olarak bu listeyi onaylamak zorundadır.
• minMacroGrid, eklentinin çalıştığı en eski Macro Grid'i söyler (bkz. Uyumluluk).

Adım 2: bir değişken

Yanına index.js dosyasını oluşturun. Betik bir korumalı alanda (sandbox) çalışır ve sunucuya yalnızca genel host nesnesi üzerinden ulaşır. Bir sayaç değişkeniyle başlayın:

let count = 0;

host.variables.describe([
  { name: 'hellojs.count', description: 'How many times the counter was bumped', example: '3', category: 'Hello' },
]);
host.variables.set('hellojs.count', count);

host.variables.describe, değişkeni düzenleyicinin değişken seçicisinde listeler; böylece kullanıcılar adı tahmin etmek zorunda kalmaz. host.variables.set ise ilk değeri yayınlar. Artık her widget bunu metninde Count: {hellojs.count} şeklinde gösterebilir.

Adım 3: bir ayar sayfası

host.settings.page([
  { key: 'step', label: 'Step', kind: 'Number', default: 1, min: 1, max: 100 },
]);

host.settings.page, bir alan listesinden Eklentiler penceresine bir ayar formu ekler. Değerler eklentinin klasöründeki settings.json dosyasında saklanır ve host.settings.get() ile geri okunur.

Adım 4: bir aksiyon

host.registerAction({
  type: 'hellojs.bump',
  name: 'Bump the counter',
  category: 'Hello',
  description: 'Adds the configured step to the hellojs.count variable.',
  icon: 'plus',
  fields: [
    { key: 'times', label: 'Times', kind: 'Number', default: 1, min: 1, max: 10 },
  ],
  run(context, settings) {
    const step = host.settings.get().step || 1;
    count += step * (settings.times || 1);
    host.variables.set('hellojs.count', count);
  },
});

host.registerAction, düzenleyicinin aksiyon seçicisine bir aksiyon ekler. fields aksiyonun kendi formunu tanımlar (burada Times adlı bir sayı alanı); run, aksiyon tetiklendiğinde bu formun değerleriyle (settings) çağrılır. Burada sayaca step * times ekler ve yeni değeri yayınlar.

İpucu: en üst düzeyde kaydedin

Aksiyonlar, ayar sayfası ve değişken açıklamaları betik ilk çalışırken kaydedilmelidir. Daha sonra, bir geri çağrımın (callback) içinden yapılan kayıtlar yok sayılır. Değişkenler ise her zaman ayarlanabilir.

Adım 5: bir durum öğesi

// Timers need no permission. The shortest allowed interval is 100 ms.
host.every(5000, () => {
  host.status('counter', 'Count ' + count, 'Ok');
});

host.every(ms, fn) bir işlevi tekrar tekrar çalıştırır (en kısa aralık 100 ms) ve host.status(id, text, level) düzenleyicinin durum çubuğunda size ait bir öğeyi günceller. Zamanlayıcılar için izin gerekmez.

Betiğin tamamı:

// A small example of a JavaScript plugin. It publishes a counter variable that any widget can show
// ("Count: {hellojs.count}") and adds one action that bumps it. Everything a plugin can do goes through
// the global `host` object; there is no other access to the server.

// #region variable
let count = 0;

host.variables.describe([
  { name: 'hellojs.count', description: 'How many times the counter was bumped', example: '3', category: 'Hello' },
]);
host.variables.set('hellojs.count', count);
// #endregion variable

// #region settings
host.settings.page([
  { key: 'step', label: 'Step', kind: 'Number', default: 1, min: 1, max: 100 },
]);
// #endregion settings

// #region action
host.registerAction({
  type: 'hellojs.bump',
  name: 'Bump the counter',
  category: 'Hello',
  description: 'Adds the configured step to the hellojs.count variable.',
  icon: 'plus',
  fields: [
    { key: 'times', label: 'Times', kind: 'Number', default: 1, min: 1, max: 10 },
  ],
  run(context, settings) {
    const step = host.settings.get().step || 1;
    count += step * (settings.times || 1);
    host.variables.set('hellojs.count', count);
  },
});
// #endregion action

// #region status
// Timers need no permission. The shortest allowed interval is 100 ms.
host.every(5000, () => {
  host.status('counter', 'Count ' + count, 'Ok');
});
// #endregion status

Adım 6: kurun

1. Düzenleyicide Eklentiler, Eklentileri Yönet… yolunu açın ve Klasörden Yükle… seçeneğini seçin.
2. hello-js klasörünü seçin. Klasör %AppData%\MacroGrid\plugins\hellojs\ altına kopyalanır.
3. Eklenti Onay bekliyor olarak görünür. İzin listesini okuyup onaylayın. Eklenti başlar.

Adım 7: kullanın

1. Bir sayfaya düğme ekleyin. Metnini Count: {hellojs.count} yapın (değişken, {...} seçicisinde de Hello kategorisinde bulunur).
2. Düğmenin basınca olayına bir aksiyon bağlayın: Bump the counter aksiyonunu (kategori Hello) seçin ve Times değerini girin.
3. Kaydedin, deck'i açın ve düğmeye basın. Metindeki sayı artar.
4. Eklentiler penceresinde eklentinin dişli düğmesini açın ve Step değerini değiştirin: artık her basış step * times ekler.
5. Durum çubuğunun sağına bakın: Count <n> beş saniyede bir güncellenir.

Adım 8: değiştirin ve yeniden yükleyin

Betiği düzenleyin ve sunucuyu yeniden başlatmadan tekrar deneyin. İki yol var:

• Kaynak klasörünüzü değiştirip yeniden Klasörden Yükle… deyin. Aynı id'ye sahip klasör, kurulu eklentinin yerini alır ve eklentinin kendi settings.json dosyası korunur.
• Ya da %AppData%\MacroGrid\plugins\hellojs\index.js içindeki kurulu kopyayı düzenleyin ve Eklentiler penceresinde Yeniden yükle'ye tıklayın.

Betik ilk çalışırken hata fırlatırsa eklenti, adının altında hata iletisiyle birlikte Hata olarak görünür; düzeltip yeniden yükleyin. Bkz. Hata ayıklama ve günlükler.

Sırada ne deneyebilirsiniz

• JavaScript host API başvurusunu okuyun; örneğin yerel bir hizmeti yoklamak için host.http.get (bir http:<host>:<port> izni gerekir).
• Değişkeninizi widget metninde biçimlendirmek için Öğretici 2 ile devam edin.