Applications

Introduction

Applications are collections of templates and their dependencies that have been added to a single package, so it can be installed together in one go.

Applications allow the templates to be shared with other accounts.

Application types

Applications have 4 types

Full (default)

Standalone application, selected by default when creating a new application

Bundle

A listing of several applications that do not need to be connected with each-other. Serves as a bundle to install or update several applications in one go.

Module

Note

As of version 1.319.0 the new module v2 features are released. Read about its functionality here: Read more about module v2

Extension to a specific full application. Files in the module can be set as replacements for files in the target full application.

Modules will be installed when the full app is installed automatically but the replacements will not be enabled until the user uses the configure modules functionality to enable it.

There is no limit to how many modules can be enabled at the same time, but only a single module can be active if multiple of them target the same file in the full application. Goerp will generate the module configuration groups based on this - modules that target unique files will be in a separate group and modules that target the same files will be in the same group.

Asset

Applications that can be shared between multiple applications.

Used to share styles, js functions or general purpose partials/pages.

Note that the version of the asset in the application indicates the minimum required version of the asset, installation will make sure that at-least this version is installed. It will not downgrade the version on the account if it has a higher version installed.

Asset package creator needs to make sure that updates to the app does not break used elements in previous versions, if this cannot be done then a new application should be created instead.

Modules

Modules V2

Module v2 features released as of version 1.319.0

Modules can be used to easily enable or disable certain features on existing applications with a toggle.

Connections to applications

Modules can be created for any application. V2 modules do not need to be added to the parent application, instead it is connected to the applications from the module application itself.

Create of open a module type application in the development mode editor view
Move to the ‘Modules’ tab
Use the ‘Select application for module’ button to connect the module to needed application

The enable and disable checkbox here can be used to immediately enable the module.

By default, goerp does not limit the modules to groups like v1 modules did, but the following grouping can be used to create a custom behaviour similar to it. The custom group name field can be used to group modules to a custom radio group on the store and on the parent applications configure modules area.

Automatically merged data

Note that if the module contains translations or variables then these are automatically merged to the applications data when the module is enabled.

Modification type templates

With modules v2 the main file type for adjustments is the new type ‘modification’. By itself it does nothing. We need to configure it to alter something on a source page.

Multiple modifications can alter the same source (no defined limit).

Create or edit a ‘modification’ type template in the module application.
Open ‘Modules’ tab in the editor for the template.

You will see several options:

For template - Select the target template we want to alter

Module type - Select the module behaviour

Replace all content - replaces all contents of the target
Prepend all content - adds the module template contents before the target content
Append all content - adds the module template contents after the target content
Anchor - looks for the value in the ‘Module tag’ field and adds the content instead of it
Replace by name - looks for the ‘Module tag’ html node and replaces its contents
Prepend by name - looks for the ‘Module tag’ html node and adds content before its content
Append by name - looks for the ‘Module tag’ html node and adds content after its content
Prepend by ID - looks for the specific html node by its id and adds content before its content

Configure modules

Use the configure v2 modules button on the parent application ‘Modules’ tab or in the editor application structure view to enable and disable the modules.

In store

Note that v2 modules are not installed automatically from the store with the parent. Instead, the store will list all available modules from the store to the user, and the user can decide what to install.

However, the application type ‘bundle’ can be used to package the parent and modules into a single installation.

Examples

Adding new file dependencies to the source

Here we add an extra static css dependency to the original, adding a new line to the head of the document.

Parent index-page

<!DOCTYPE html>
<html>
    <head>
        <title>Demo modidied app</title>
        <link rel="stylesheet" {{ .Tools.CSP }} href="{{ .Tools.StaticLink "dma-styles-css" }}">
    </head>
    <body>
        <h1>Demo modified application</h1>

        {{ $products := .Tools.Func "dma-fetch-products-func" }}

        <div>
        {{ range $products.Array }}
            <div class="block">
                <p>{{ .Get "productID" }}</p>
                {{/* anchor */}}
            </div>
        {{ end }}
        </div>
    </body>
</html>

Modification template in module

For-template: index-page Module type: Append by name Module tag: head

<link rel="stylesheet" {{ .Tools.CSP }} href="{{ .Tools.StaticLink "dam3-styles-css" }}">

Replacing a custom anchor in the source

Here we use the anchor to just replace it in the source. Note that the anchor can be any value in the source.

Parent index-page

<!DOCTYPE html>
<html>
    <head>
        <title>Demo modidied app</title>
        <link rel="stylesheet" {{ .Tools.CSP }} href="{{ .Tools.StaticLink "dma-styles-css" }}">
    </head>
    <body>
        <h1>Demo modified application</h1>

        {{ $products := .Tools.Func "dma-fetch-products-func" }}

        <div>
        {{ range $products.Array }}
            <div class="block">
                <p>{{ .Get "productID" }}</p>
                {{/* anchor */}}
            </div>
        {{ end }}
        </div>
    </body>
</html>

Modification template in module

For-template: index-page Module type: Anchor Module tag: {{/* anchor */}}

<p>{{ .Get "code" }}</p>

Create

Basic info

To use applications for files, first we need to create an application entity.

Use the CREATE NEW -> Create new application from the menu to create one. Give the application a good clean name, it should follow the following rules:

Not contain any special characters
Start with a capital letter

You can link templates to the application from the application view screen, or you can link the template to the application in the template view under the ‘Publish settings’ right panel.

Note that templates in the application should have a unique name. Recommendation is to use some kind of prefix related to the application to describe the templates.

Example: My Test App -> mta-my-page

Templates and links

The linked templates list can be used to make the application create links to the application. There are 2 kinds of links

Open menu link - this is the link that is created on the store application card, under the ‘Open’ button.
Menu link - this is an actual link that is added to the Erply menu

Green icon on the link button means a link has been defined.

Types

Currently, the application can be either a full, asset or module.

Adding assets or modules to applications

Only full application can have assets and modules. In the application edit screen navigate to the asset or module connection area (under templates).

Note

Note that the asset or module needs to be published to the store first.

Add assets/modules using the add button.
Update connected versions by just re-adding them.

Create version and publish

In order to share the application to other accounts we need to publish to the store. Before the application can be published it needs to meet the following conditions:

Have publishing permissions on the account for the application uuid
Version needs to pass the application validation rules
1. Have a rate higher than 0
  1. Valid application name, description and short description
  2. Not include partials or static files that are not used by the application
2. Not include any critical validation errors
  1. Unlinked partials or static files
  2. Links to untrusted sources
3. Not use file names that are already used by another application
4. Has at-least one ‘Open’ menu link
5. has at-least one Erply menu link

To publish the application the workflow would be the following: Validate version -> Create version -> Publish to the selected cluster

Logs

Application logs

The system collects application based errors into a short-lived memory that we can access for approximate 1 hour.

This can be used for debugging purposes or to check if the application is causing errors.

These logs are only captured for items that are connected to an application.

What is being recorded

Failures in the editor for application connected templates
Failures in page view’s for any possible api’s or the view generation logic itself
Optionally the ‘debugDynApi=1’ can be added to the page parameters to record even successful requests. Note! If the template was recently linked to an application and the template was not save/updated then it might need a new re-save to properly start reading the debug logs.

This will make the application records all requests it makes even successful ones.

Where can the logs be seen

Template edit view under the ‘Application logs’ right section.
Under local application edit view. Content here is minimal as the api request data is not displayed.
Under store application installation view. Content here is minimal as the api request data is not displayed.

Store errors indicator

The store will also indicate with a bug icon for the application if it has recently encountered errors.

Note that this will also capture template editing errors and can be used to reference encountered errors.

Moving applications

Moving application between accounts without using the store

Applications can be moved from one account to another without using the store interface. For this we can export the application and then import it to the other account using the export and import functionality.

Navigate to the application you want to move

Edit the application under ‘Developer mode’

Move to the ‘Export’ tab

Open the ‘Export’ tab and click on the ‘Export’ button to download the application package

Import the application

Open the account you wish to move the application to and open the ‘Developer mode’ view. Hover to the ‘Applications’ row to make the import button visible. On the new modal select the previously exported zip file and click ‘Import’.

Wait for the process to complete. After this all the application should be available on the account.

Variables

Application static variables

Applications can use application accessible static variables that can then be used on all application connected templates.

Useful when a similar value is being used in multiple templates and for optimization where a static value is faster than trying to fetch one from an api.

These values can also be assigned into dynamic api requests parameters.

Create variables

In order to use the feature, first we need to create a ‘variables’ type file that is connected to the application.

Note

Application should only have a single variables file, if multiple are connected only the first one of them will be used.

Contents of the variables file is in json format. The structure can have any kind of nesting or value types.

{
    "someKey": "someValue",
    "stuff": {
        "other": [
            {
                "id": 10
            },
            {
                "id": 12
            }
        ]
    },
    "defaultProductID": 21
}

Usage

The values can just be printed to the template or be used in dynamic api chaining features. The reading syntax is the same as reading dynamic api responses so all the same features and rules apply. More about dynamic response reading

Simple read

Reading values from the sample above

{{ .Variables.Get "someKey" }}
{{ .Variables.Get "stuff.other.#.id" }}

In dynamic api chaining

Reading value from the sample above

<input type="hidden" name="ErplyApi.Api.Post.myRequest1"
	data-preset-val="getProducts">
<input type="hidden" name="ErplyApi.Api.PostParam.myRequest1.<-productID"
    data-preset-val="Variables.defaultProductID">

Security

Application security

Security settings that can be changed per application

Note

Note that the setting here only apply to the selected application, they are not global.

Where to change:

Open “Developer mode”
Edit the desired application
Navigate to the “Security tab”

Custom CSP rules

The server will apply a default CSP ruleset (shown below), but you can disable this in the application security settings and provide a custom one instead. The changes here will only take effect for the edited application.

The default ruleset:

default-src *; script-src 'self' 'nonce-{nonce}'; object-src *; style-src 'self' 'nonce-{nonce}' 'unsafe-inline'; img-src * data: blob: 'unsafe-inline'; font-src * data: blob: 'unsafe-inline'

IP blocking / whitelist

It’s possible to also start blocking access to the application routes (or app user login) by IP. The settings here work as a whitelist, this means when enabled without any ip inputs then all accesses are blocked.

Enter the allowed IP’s and an optional note who the IP belongs to. When done then don’t forget to click on the “Confirm changes” button.

There are 2 modes for the blocking functionality:

This mode does not prevent access to view the pages but does block the app users from logging in.

View block

This mode blocks views of the pages entirely.

Applications

Introduction

Subsections of Applications

Application types

Full (default)

Bundle

Module

Asset

Subsections of Application types

Modules

Modules V2

Connections to applications

Automatically merged data

Modification type templates

Configure modules

In store

Examples

Adding new file dependencies to the source

Parent index-page

Modification template in module

Replacing a custom anchor in the source

Parent index-page

Modification template in module

Create

Basic info

Templates and links

Types

Adding assets or modules to applications

Create version and publish

Logs

Application logs

What is being recorded

Where can the logs be seen

Store errors indicator

Moving applications

Moving application between accounts without using the store

Navigate to the application you want to move

Move to the ‘Export’ tab

Import the application

Variables

Application static variables

Create variables

Contents

Usage

Simple read

In dynamic api chaining

Security

Application security

Custom CSP rules

IP blocking / whitelist

Login block

View block