vai al contenuto principale

Invocare Plugin

Le API GraphQL della Cloudlet consentono di invocare Plugin dichiarati su FormActionHandler di classi e classi Form.

A partire dalla versione di Livebase 5.6.2, lo schema GraphQL offre dei servizi per invocare FormActionHandler e gestirne il messaggio di ritorno. È possibile invocare un FormActionHandler passando al servizio una form in un contesto di tipo Create, Update o Save (scrittura generica), tra gli scenari descritti nei servizi di scrittura.

I servizi descritti in questa pagina sono tutti di tipo mutation e rispettano il formato <ClassName>___<scenario>___formAction___<HandlerName>; questi vengono generati per ogni FormActionHandler modellato sulla classe.

Modello di riferimento #

Tutti gli esempi in questa pagina fanno riferimento ala classe Employee in figura, e in particolare all’Handler calculateSalary cerchiato in rosso:

Employee

La classe Employee, come modellata nel Tutorial, a cui è stato aggiunto l’Handler calculateSalary.

Questo consente di calcolare il salario dell’impiegato secondo diversi criteri, e di aggiornare automaticamente il valore dell’attributo hourly_cost.

Dettaglio: implementazione

Servizio create___formAction #

Il servizio Mutation.<ClassName>___create___formAction___<HandlerName> consente di invocare un FormActionHandler passando il contesto della form di creazione di un nuovo oggetto di una certa classe.

type Mutation {
  ClassName___create___formAction___HandlerName(
    data: ClassNameDraftCreate
    jsonParam: String
    forceWarnings: ForceWarnings
  ): ClassNameFormActionHandlerResult
}

Il servizio accetta in input la struttura <ClassName>DraftCreate e restituisce in output la struttura <ClassName>FormActionResult. È possibile passare informazioni aggiuntive all’Handler (serializzate in JSON) mediante il campo jsonParam: String. Nota che il campo data, a partire dalla versione 5.11.2 di Livebase, è anch’esso opzionale e può non essere valorizzato nella mutation.

È possibile aggirare eventuali warning restituiti dal server causati da Class Warning non bloccanti includendo l’argomento forceWarnings, di tipo ForceWarnings.

Ad esempio, il servizio per invocare l’Handler calculateSalary di Employee in un contesto di Create è il seguente:

type Mutation {
  Employee___create___formAction___calculateSalary(
    data: EmployeeDraftCreate
    jsonParam: String
    forceWarnings: ForceWarnings
  ): EmployeeFormActionHandlerResult
}

Servizio update___formAction #

Il servizio Mutation.<ClassName>___update___formAction___<HandlerName> consente di invocare un FormActionHandler passando il contesto della form di modifica di un oggetto esistente di una certa classe.

type Mutation {
  ClassName___update___formAction___HandlerName(
    data: ClassNameDraftUpdate
    jsonParam: String
    forceWarnings: ForceWarnings
  ): ClassNameFormActionHandlerResult
}

Il servizio accetta in input la struttura <ClassName>DraftUpdate e restituisce in output la struttura <ClassName>FormActionResult. È possibile passare informazioni aggiuntive all’Handler (serializzate in JSON) mediante il campo jsonParam: String. Nota che il campo data, a partire dalla versione 5.11.2 di Livebase, è anch’esso opzionale e può non essere valorizzato nella mutation.

È possibile aggirare eventuali warning restituiti dal server causati da Class Warning non bloccanti includendo l’argomento forceWarnings, di tipo ForceWarnings.

Ad esempio, il servizio per invocare l’Handler calculateSalary di Employee in un contesto di Update è il seguente:

type Mutation {
  Employee___update___formAction___calculateSalary(
    data: EmployeeDraftUpdate
    jsonParam: String
    forceWarnings: ForceWarnings
  ): EmployeeFormActionHandlerResult
}

Servizio formAction #

Il servizio Mutation.<ClassName>___formAction___<HandlerName> consente di invocare un FormActionHandler passando il contesto di una form di scrittura generica su una certa classe.

type Mutation {
  ClassName___formAction___HandlerName(
    data: ClassNameDraft
    jsonParam: String
    forceWarnings: ForceWarnings
  ): ClassNameFormActionHandlerResult
}

Il servizio accetta in input la struttura <ClassName>Draft e restituisce in output la struttura <ClassName>FormActionResult. È possibile passare informazioni aggiuntive all’Handler (serializzate in JSON) mediante il campo jsonParam: String. Nota che il campo data, a partire dalla versione 5.11.2 di Livebase, è anch’esso opzionale e può non essere valorizzato nella mutation.

È possibile aggirare eventuali warning restituiti dal server causati da Class Warning non bloccanti includendo l’argomento forceWarnings, di tipo ForceWarnings.

Ad esempio, il servizio per invocare l’Handler calculateSalary di Employee in un contesto di Create o Update è il seguente:

type Mutation {
  Employee___formAction___calculateSalary(
    data: EmployeeDraft
    jsonParam: String
    forceWarnings: ForceWarnings
  ): EmployeeFormActionHandlerResult
}

FormActionHandler con classi Form in input #

Per i FormActionHandler a cui è assegnata una classe Form (Set form... su menu contestuale del FormActionHandler, come descritto nella reference sulle classi Form e nella guida sviluppo Plugin), viene generato un argomento ulteriore nei servizi GraphQL: formParam, il cui tipo è la struttura di input relativa alla classe Form puntata dall’Handler. Questo argomento, quando presente, è required.

A seconda del contesto del servizio (rispettivamente Create o scrittura generica), il tipo di formParam può essere:

Ad esempio, la signature del servizio formAction generico diventa la seguente:

type Mutation {
  ClassName___formAction___HandlerName(
    data: ClassNameDraft
    formParam: FormClassNameDraft!
    jsonParam: String
    forceWarnings: ForceWarnings
  ): ClassNameFormActionHandlerResult
}

type <ClassName>FormActionHandlerResult #

Tutti i servizi menzionati finora ritornano la seguente struttura <ClassName>FormActionHandlerResult:

type ClassNameFormActionHandlerResult {
  data: ClassName # oggetto corrente su cui è stato invocato l'handler, eventualmente alterato dal codice del plugin
  result: FormActionHandlerResult!
}

Il campo data contiene la struttura <ClassName>; questa rappresenta l’oggetto corrente sui cui è stato invocato il FormActionHandler, eventualmente alterato dal codice del Plugin.

Il campo result contiene una struttura comune, indipendente dal modello, di tipo FormActionHandlerResult. Espandendo questo campo è possibile ottenere informazioni circa il risultato dell’invocazione dell’Handler, che, come descritto qui, può restituire un messaggio informativo, un messaggio di avvertimento o un messaggio d’errore.

type FormActionHandlerResult {
  # analogo alla struttura ritornata dal FormActionHandler dello SPI generato
  type: FormActionHandlerResultType!
  message: FormActionHandlerMessageResult
}

enum FormActionHandlerResultType {
  MESSAGE
  NONE
}

type FormActionHandlerMessageResult {
  type: MessageType!
  message: String!
  title: String
}

enum MessageType {
  ERROR
  INFO
  WARNING
}