menu

Calling Web Services

Singlepage provides a rpc object that can be used to invoke methods on Singlepage Web services. The Echo component code below illustrates how to call a remote Web service. The echoMessage method on the component uses the rpc object to call echo method on EchoService service.

<template>
  <div class="p-4 d-flex justify-content-center flex-column">
    <form>
      <p><input name="input" class="form-control" v-model="msg"
      placeholder="Type words to echo back from EchoService"></p>
      <input type="submit" value="Echo" class="btn btn-primary" @click.prevent.stop="echoMessage">
    </form>
    <div v-html="echo" class="p-3 mt-3 border bg-light d-flex align-items-center justify-content-center"></div>
  </div>
</template>
<script>
export default {
  data: function() { return {echo: '', msg: ''}},
  
  methods: {
    echoMessage: function() {
      this.$app.rpc.invoke("EchoService", "echo", {words: this.msg}, this.echoSuccess, this.echoFail)
    },

    echoSuccess: function(resp) {
      this.echo = '<div class="lead text-success">' + resp + '</div>';
    },

    echoFail: function(errorCode, error) {
      this.echo = '<div class="lead text-danger">' + errorCode + ' : ' + error + '</div>';
    }
  }

}
</script>

The invoke method on rpc object takes 5 arguments:

  • service - Name of the service as registered with Singlepage
  • method - Method name
  • params - JSON object that is passed to the service
  • successHandler (optional) - Callback in case of successful invocation
  • appErrorHandler (optional) - Callback when the method invocation returns application level error

If the method call returns successfully Singlepage will call the successHandler (if provided) with one argument representing the return value of the method. The argument value will be the JSON object returned by the service.

Method Return Status Codes

Singlepage defines several return status codes defined on $app.constants object:

  • RETURN_SUCCESS - Method invocation succeeded
  • RETURN_LOGIN_REQUIRED - The user needs to log in to invoke this method
  • RETURN_APP_ERROR - There was an application level error
  • RETURN_ACCESS_DENIED - The user does not have permission to invoke this method
  • RETURN_INTERNAL_ERROR - Internal error
  • RETURN_NO_CONNECTION - Method invocation failed due to network connection issues
  • RETURN_INVALID_REQUEST - Programming error

Error Handling

If the user does not provide an error callback, Singlepage will display an error dialog. The message displayed in the dialog will depend on the status code returned. The message displayed can be internationalized via the messages file as described in the Internationalization section. Additionally, for RETURN_NO_CONNECTION, the dialog box will offer the option to retry the method.

Error Status Error Message
RETURN_LOGIN_REQUIRED error_login_required
RETURN_APP_ERROR Localized error message if returned by the service; error_generic otherwise
RETURN_ACCESS_DENIED error_access_denied
RETURN_INTERNAL_ERROR error_generic
RETURN_NO_CONNECTION error_no_connection
RETURN_INVALID_REQUEST error_generic

User provided error callback is called with the following arguments:

  • Error status code,
  • Error message string
  • Error details - a JSON object that can provide more details such as invalid form fields