mat|r docs Importing libraries |

Mat|r allows the user to integrate his applications with other applications (also created in Mat|r), called libraries. This integration is quick and easy, and you can use code written by other users or by yourself. Thus, the developer can share and reuse the libraries saving time and adding value to the Mat|r community.

Content

Creating an Mat|r application as library
Import libraries in Modeller/IDE
Import statement of a library
Importing Elements
Access to the elements imported from a library
Example of an import library application

Creating a Mat|r application as library

To create a library app, we answer affirmatively to the question “Can this app be imported?” and enter the package name that will be used at the moment of importing the library.

After that, we continue developing the app as usual. In the example, we will create a library called OAuthFacebookLib, to authenticate the user in Facebook. The code of the library is the following:

Model FacebookUser {
    String name
}

Application {

    String tokenOAuth
    FacebookUser user
    OnInit{       
        tokenOAuth = ""
    }
}

RuleContext LibraryContext {

    Rule login {

      OAuth fbOAuth = OAuth()
      //clientID and secret are fields generated by facebook
      fbOAuth.clientID = "110429725963xxxx"
      fbOAuth.secret = "8fc0392d9624db955147d36e26xxxxxx"

      //accountName: field used internally by mat|r to persist session info
      fbOAuth.accountName = "MyAccountFacebook"

      //authorizationURL y tokenURL: are provided in the facebook API documentation
      //the api version to connect with must be the same to the version is informed on the facebook app configuration screen
      fbOAuth.authorizationURL = "https://www.facebook.com/v2.9/dialog/oauth?scope=email"
      fbOAuth.tokenURL = "https://graph.facebook.com/v2.9/oauth/access_token"

      //redirect URL: here you must enter a custom URL as it is established by the oauth2 protocol
      fbOAuth.redirectURL = "http://mywebpage/auth/callback"

      //oauth2 authorize call is made, and in case of success a valid token is fetched
      tokenOAuth = broker.oauth.authenticate(fbOAuth)

      //once the authorization is granted, the variable 'tokenOAuth' can be used in all the endpoints which need a valid token
      usuario = FacebookUser()
      usuario.nombre = "John Doe"
      ...
      ...
    }
}

In the previous code, we defined a rule called login, that will be in charge of the authentication and it will save the token resulting from the global variable tokenOAuth. If you want the library to be visible for other Mat|r users, it needs to be opened through the Deploy tab. And by clicking on the Publish button, a QR code appears with the new version.

Import libraries in Modeller/IDE

You can find the “Libraries” section on the right panel of the Modeller/IDE of an app at the Mat|r platform.

Within this section you can see “Current libraries”. It shows a list of libraries that we have imported into the application.

You can check the documentation and functionality offered for every imported library (Variables, Models, Modules, Services and Rule Contexts).

In the lower section, you will find “Import library”, where all available libraries (being public and / or published) will be displayed on the Mat|r. To facilitate the search you can filter by name in the “Search” field, or also by “Property”, “Category” or by “Tags”.

In this way you can see the “Libraries” listed below the “search engine,” where you can import the one you need to use your application by pressing the “+” button (you will find it to the right of the library name and next to the button to see his description).

When you click on the “+” button and you accept the dialog box, the sentence “Import ThisLib as ThisLib” will be inserted into the first mat | r script file, “ThisLib” being the Package Name of the library to be imported. And you can integrate the imported library into your application.

You must Fork other libraries. You can make the Fork of the Library within the documentation.

When you enter a library documentation, you will see the content, information and description left by its creator. The current version is visible in “Current Version” and the sentence to import the library (you can click on the clipboard to copy the sentence “Import ThisLib as ThisLib” as explained before) At the end of the window you can rate the library and leave a comment of your experience with it, you can also see the reviews of other users of Mat|r.

Import statement of a Library

Once the library is finished and opened, we import it from our application. This process can be done in two different ways:

Specifying the version of the library we want to import:

  Import packageNameOfLib, version as aliasLib

in our example:

  Import OAuthFacebookLib, 0.7 as facebookOAuth

Without specifying the version of the library we want to import, understanding that the last version that has been displayed will be imported.
```
  Import packageNameOfLib as aliasLib
```
in our example:
```
  Import OAuthFacebookLib as facebookOAuth
```

When a new available version is detected, the Refresh icon will be shown on the library display, on the right panel. By clicking on the button, the code of the last available version is updated. It is important to highlight that the updating process does not include the layouts, that must be updated individually.

As we can see in the import statement, we must determine an alias for the library (what comes after the word as), in order to have access to the elements of the library. Once the library is imported in our application, we can see on the right panel of the screen that the library has been imported properly. By clicking on it, we will be able to see each of the imported elements.

Models
Global variables
Layouts
Rule contexts
Endpoints
Modules and Functions

Importing Elements

Just importing a part of your library, and not all of it, is also possible in mat|r script. This is called element import. All the elements that can be imported are the ones listed previously.

In order to import an element, one of the following sentences should be used:

Specifying the version of the library we want to import:

  Import packageNameOfLib.nameElement, version as aliasLib

We import the model of our example:

  Import OAuthFacebookLib.FacebookUser, 0.7 as facebookOAuth

Without specifying the version of the library we want to import, understanding that the last version that has been displayed will be imported.
```
  Import packageNameOfLib.nameElement as aliasLib
```
We import the model of our example:
```
  Import OAuthFacebookLib.FacebookUser as facebookOAuth
```

Access to the elements imported from a library

To use the elements of the library, we use the alias defined in the import statement, followed by 2 colons (::), as shown below:

aliasLibrary::nameModel

aliasLibrary::globalVariable

aliasLibrary::nameLayout

aliasLibrary::nameRuleContext.nombreRule

aliasLibrary::nameEndPoint

aliasLibrary::nameModule.nameFunction()

There is a possibility to initiate the library (i.e. calling on its OnInit method), in the case the library needs to set certain values before its initialization. For this action, we use the core function called initialize, as shown below:

    broker.core.initialize("aliasLibrary")

or in our example:

    broker.core.initialize("facebookOAuth")

Example of an import library application

Continuing with the same example, we create an application that will import the library facebookOAuth, and we use the following statements:

Configuring Decision with an imported rule:
```
Decision btn2 action("facebookOAuth::LibraryContext.login") label("LOGIN")
```
With this statement, we are defining a button called ‘LOGIN’, and, by clicking on it, the login rule will be called. Said rule is specified in the facebookOAuth library, in the context of the library: LibraryContext.
Access to the global variable
```
broker.ui.showAlert("token", facebookOAuth::tokenOAuth)
```
This statement will display -in a dialogue box-, the token that was configured in the global variable of the tokenOAuth library, when clicking on the button previously mentioned.
Instatiation of an imported model
```
facebookOAuth::User localUser = facebookOAuth::User()
```
This line indicates how a new instance is created from a model defined in the library by allocating the instance to the local variable
localUser.

Here is the complete code:

Import OAuthFacebookLib, 0.7 as facebookOAuth

Experience Main{
    Decision btnLogin action("facebookOAuth::LibraryContext.login") label("LOGIN")
    Decision btnShow action("ApplicationContext.showToken") label("SHOW TOKEN")
}

Application {
    Main m
    OnInit {
        m = Main()
        broker.ui.push("Main", m)

        try {
            broker.core.initialize("facebookOAuth")
        } catch (e){
            broker.ui.showAlert("error","can't initialize lib" + e.reason())
        }
    }
}

RuleContext ApplicationContext {

    Rule showToken {
        broker.ui.showAlert("token", facebookOAuth::tokenOAuth)
    }

    Rule usingImportedModelInARule {

        //we define a local variable of an imported model type
        facebookOAuth::User localUser

        //Asign the global variable pointing to our logged user, to the local variable localUser
        localUser = facebookOAuth::usuario

        //or if we want to use a new instance, we can do
        localUser = facebookOAuth::User()
        ...
        ...
    }
}