Home

AsiCAT - Documentație API

Funcția Extensii este încă în dezvoltare! Vă rugăm să ne oferiți feedback dacă aveți neplăceri sau sugestii.

Aceasta este documentația pentru API-ul AsiCAT, ce permite interacțiunea dintre Extensii și restul programului. În această documentație, vă va fi prezentat procesul creeri unei extensii, cât și instrucțiuni pentru răsfoirea acestor metode API. Important de știut: Extensiile sunt scrise în JavaScript.

Extensiile AsiCAT sunt doar niște fișiere ZIP. Structura acestora este următoarea:

  • manifest.json - Fișierul cu informațiile extensiei.
  • Fișierele script

Fișierul manifest.json conține un obiect cu următoarele proprietăți:

  • manifestVersion - Numărul reprezentând versiunea formatului manifest. AsiCAT 1.15 ignoră această valoare, iar 1.16 și versiunile ulterioare necesită valoarea 2.
  • minVersionCode - Codul numeric al versiunii minime de AsiCAT pe care va funcționa această extensie.
  • name - Numele extensiei.
  • uuid - Un identificator unic (UUID) al acestei extensii. Nu folosiți UUID-ul altei extensii, și nu îl schimbați după publicarea acesteia. Puteți obține un UUID cu un site precum acesta.
  • description - Descrierea extensiei. Afișată în Manager extensii.
  • version - Numele versiunii extensiei. De exemplu: 1.1 sau 2.7.3-rc1. Poate fi orice string, și nu are semnificație la actualizarea extensiei.
  • versionCode - Un cod numeric al versiunii. Ideea ar fi ca prima versiune să aibă 1, iar cu fiecare versiune să incrementați codul. Este folosit la actualizarea extensiilor, astfel suprascrierea unei extensii deja instalate este permisă doar dacă versionCodeNou >= versionCodeVechi.
  • author - Numele autorului extensiei.
  • files - O listă a numelor fișierelor script. Doar fișierele specificate aici vor fi executate.
  • permissions - O listă a permisiunilor cerute de extensie. Se discută mai jos despre permisiuni.

Extensia poate fi instalată doar dacă aceste câmpuri au valori valide. Odată ce o extensie este instalată, la fiecare pornire a programului, se va crea un sandbox pentru aceasta unde vor fi executate, pe rând, fișierele specificate în lista files.

Sandbox-ul este complet izolat de restul programului, singurul acces fiind prin acest API. API-ul se poate accesa din sandbox prin globala AsiCAT.

Permisiunile

Unele funcții API sunt restricționate, iar extensia dvs. trebuie să ceară anumite permisiuni pentru a le putea folosi. Lista de permisiuni este prezentată utilizatorului la instalare, iar, prin continuare, își exprimă acordul cu acestea. După instalare, extensia are toate permisiunile cerute.

O declarație de permisiune, pentru a fi considerată validă, trebuie să aibă forma: namespace.permission.name.

Aici, namespace este spațiul din care face parte această permisiune. Permisiunile de program se găsesc în asicat. În viitor, extensiile vor putea să expună funcții și să își creeze propriile permisiuni pentru a le proteja.

name este numele permisiunii, partea cea mai importantă.

În documentația fiecărei funcții, este menționată permisiunea necesară, dacă este cazul. Următoarele permisiuni sunt valide și vă vor acorda drepturi suplimentare:

  • asicat.permission.READ_PRODUCTS
  • asicat.permission.WRITE_PRODUCTS
  • asicat.permission.SHOW_NOTIFICATIONS
  • asicat.permission.ADD_MENU_BUTTONS
  • asicat.permission.REQUEST_RESTART
  • asicat.permission.CREATE_HTML_ELEMENTS
  • asicat.permission.READ_COMPANY_INFO
  • asicat.permission.WRITE_COMPANY_INFO
  • asicat.permission.READ_CATEGORIES
  • asicat.permission.WRITE_CATEGORIES
  • asicat.permission.READ_SETTINGS
  • asicat.permission.ADD_TEMPLATES

Hai să facem o extensie exemplu

Vom crea un dosar, iar în interior fișierele manifest.json și main.js.

manifest.json va conține:

{
	"manifestVersion": 2,
	"minVersionCode": 23,
	"name": "Extensie exemplu",
	"uuid": "690de7c7-2b19-4f0d-8629-21ade86cca0c",
	"description": "Această extensie îți spune salut",
	"version": "1.0",
	"versionCode": 1,
	"author": "Boss",
	"files": ["main.js"],
	"assets": ["imagini/pisica.png", "imagini/caine.png"]
	"permissions": [
		"asicat.permission.ADD_MENU_BUTTONS"
	]
}

La UUID, am completat un ID generat random. La files, o listă conținând fișierul nostru main.js.

La assets, am specificat path-urile unor fișiere statice din arhiva ZIP, ce le vom putea folosi cu AsiCAT.GetAsset și AsiCAT.DisposeAsset. La permisiuni, am cerut asicat.permission.ADD_MENU_BUTTONS, pentru a putea adăuga butoane în bara de meniu.

Observăm cum extensia targetează AsiCAT 1.19. Este mereu recomandat să suportați doar cele mai noi versiuni.

În main.js, vom completa următorul cod:

AsiCAT.AddPluginButton("Spune salut", async () => {
    AsiCAT.Dialog("Ce mai faci?", "Salut!");
}, "Extensii", "fa-hand");

Vei afla în curând cum funcționează aceste funcții din documentație. Pe scurt, adăugăm un buton în fila Extensii și afișăm o casetă de dialog când este apăsat. Ne amintim că API-ul se accesează prin globala AsiCAT.

Instalarea extensiei

Se face astfel:

  • Se împachetează fișierele extensiei într-un ZIP. Aveți grijă - nu arhivați dosarul, ci conținutul acestuia!
  • Din AsiCAT, se deschide Manager extensii din meniul Extensii.
  • Din partea de jos a ferestrei, se face clic pe Instalează o extensie...
  • Se selectează fișierul ZIP.
  • Dacă fișierul este procesat cu succes, veți fi întrebat să confirmați instalarea.
  • După instalare, va trebui să reporniți programul.

În viitor, vom pune la dispoziție un magazin de extensii. Între timp, pregătiți-vă!

Extensia exemplu ar trebui să adauge un buton în fila Extensii, care afișează „Salut! Ce mai faci?”.

Debugging

Puteți vedea erorile ce apar în executarea funcțiilor API în Jurnalul de evenimente, din meniul Instrumente. Puteți să vă testați codul în Editorul de cod, disponibil tot acolo.

Dacă ceva o ia razna, puteți dezactiva temporar extensiile instalate executând AsiCAT cu opțiunea asicat-safe-mode.

Exemplu Windows: %USERPROFILE%\AppData\Local\Programs\asicat\AsiCAT.exe asicat-safe-mode

Exemplu Linux: ~/.local/bin/asicat/asicat.AppImage asicat-safe-mode

Răsfoirea documentației

Toate funcțiile API se găsesc în sidebar. Ele apar în global, dar se află toate în AsiCAT.

De exemplu, în cod, veți folosi CreateProduct ca AsiCAT.CreateProduct.