====== AeroPad App Development ======


AeroPad is written in HTML and Javascript and communicates with LRM through the LRM Data Connector (technically known as "LRM REST Services").

LRM has a built-in, super light-weight web server that can host static content as well as providing a handful of REST API (JSON) endpoints that enable app developers to retrieve various types of data from LRM as well as cloud services provided by FsHub.

These endpoints are documented in the [[lrm:developers:rest_api_v1|LRM REST Services]] document.

Although LRM provides a number of useful API endpoints for you to use, you can also, build your own API's on your own server(s) and access data using AJAX within your AeroPad app - this is, however, beyond the scope of this project but if you would like to know further information about this you can visit our [[https://forums.fshub.io/c/support/developer-integration/11|Developer Discussion]] forum and we will get back to you as quickly as possible.



===== Minimum app requirements =====

The absolute minimum requirements for building an AeroPad app consists of the following files:

  * An ''lrm-plugin.json'' manifest file
  * A 256x256 (pixel) image file (we recommend using PNG with a transparent background) - you can name this file whatever you like and should be declared in the ''lrm-plugin.json'' file - see the **Resources** section below to download an Adobe Photoshop compatible template (PSD) file.

The above files are adequate for, what we will refer to as a "redirect app" - A "redirect app" is essentially just a redirect to an external website or application that may be run on your own server or an externally hosted service that provides useful content to a virtual pilot such as FuelPlanner.com.

There are two apps that are provided by AeroPad that, by default utilise this type of app configuration, these being "**My FsHub**" and "**FsHub Rader**" app - both of these "apps" technically just redirect to specific pages on FsHub.

In order to build a true app (an app that loads its content locally), the addition of an HTML file (this should be named ''index.html'' and placed in the root of your plugin folder to ensure that it is loaded when you click on the app icon in the AeroPad EFB) and for the majority of apps (unless you just want a static page ), one or more JavaScript files too - these can be named however you like as you are responsible for referenced them from your plugins' ''index.html'' file.

===== How to create a new plugin =====

All plugins are located in their own dedicated plugin folder and are located (installed to) the following directory:

''C:\Program Files (x86)\Landing Rate Monitor\ws\plugins''

During development or, once your application is ready to ship, you can manually copy your plugin folder into this directory and then refresh your AeroPad screen, the app icon should then appear (a//ssuming you have setup the ''lrm-plugin.json''  in the root of the plugin folder too and correctly referenced the icon file//).

You should create a new folder in this directory and name it something that relates to your plugin, it is, however, recommended to avoid using spaces in the filename and, by convention, use lowercase characters only.

Once the folder is created, you should set up your ''lrm-plugin.json'' file, you can use the following content as a base for your new plugin:

<file json>
{
  "name": "My App",
  "description": "This will appear in the app manager when browsing available apps to install, update or uninstall.",
  "icon": "your-icon-file.png",
  "developer": "Your Name",
  "url": "https://your-website.com",
  "version": "1.0.0",
  "open_mode": "same",
  "remote_app_url": null
}
</file>

Once you have created the ''lrm-plugin.json'' file using the above template, you should replace each of the property values with your own values (see below for details of what each property is and how to use them).

Next, assuming you do not intend on just making a "redirect" app, you should now create an HTML file in the root of your plugin folder, this file MUST be named ''index.html'' - you can add other HTML files to the root of your plugin folder too but the ''index.html'' file is the file that will get loaded when a user clicks on the icon in the AeroPad home screen and therefore should be considered as the "bootstrap" file.

===== The lrm-plugin.json file =====

The ''lrm-plugin.json'' file is used by both LRM and AeroPad to correctly display your app in the AeroPad home screen; it is also used by the "App Manager" (app store) app to display information about your app and enables a user to install it (if you publish your app to the store), update it and/or remove it from their AeroPad.

The JSON schema details and properties are as follows:-

  * ''name'' - This is the name of your app, this will be displayed below the App Icon on the AeroPad home screen, it will also be used   in the App Manager listing of apps that can be installed, removed or updated.
  * ''description'' - The description field should be used as a brief summary of what your app is or does, this information will be displayed in the App Manager app.
  * ''icon'' - This is the filename to the icon that will be displayed on the AeroPad home screen, it is recommended that the icon file is stored in the root of your plugin directory.
  * ''developer'' - This should be your name, your company name or the development group name, this information will be displayed in the App Manager app.
  * ''url'' - This should be a URL to your website and will allow users to visit your website from the App Manager; if you don't have a website you can leave this empty, eg. ''"url": "",''.
  * ''version'' - This should be the version number of your app, each time you release a new version you should increment this value. This will also be displayed and used by App Manager when it checks for app updates on the user's behalf.
  * ''open_mode'' - This defines how the app will open, valid options are either "self" or "external" - this setting has no effect when the "remote_app_url" is set and should only be used for standard apps.
  * ''remote_app_url'' - If this is set, the app will launch the URL specified (in a new tab), by setting this value to anything other than ''null'', this will essentially turn the app into a "redirect" app

===== Example lrm-plugin.json manifests =====

Here is the actual ''lrm-plugin.json'' file that the "FsHub Radar" app uses, as you can see, it specifies a remote app URL and therefore, will, when the user clicks on the icon, will open a new tab (the ''open_mode'' option is ignored for the remotely hosted app) and load the remote webpage:

<file json>
{
  "name": "FsHub Radar",
  "description": "View all active flights on FsHub's world radar'",
  "icon": "fshub-radar.png",
  "developer": "LRM Client",
  "url": "https://lrmclient.com",
  "version": "1.0.0",
  "open_mode": "same",
  "remote_app_url": "https://fshub.io/radar"
}
</file>

The Aircraft Monitor app on the other hand has its own ''index.html'' file and as you will notice from the ''lrm-plugin.json'' file below, it does not specify a ''remote_app_url'' - this is the defining factor as to if AeroPad will load the apps' ''index.html'' file from the root of the plugin folder or if it will load the remote URL as specified in the ''remote_app_url'' property.

<file json>
{
  "name": "Aircraft Monitor",
  "description": "An aircraft monitor app for the AeroPad.",
  "icon": "monitor-icon.png",
  "developer": "Bobby Allen",
  "url": "https://lrmclient.org",
  "version": "1.0.0",
  "open_mode": "same",
  "remote_app_url": null
}
</file>

===== Design language - the "back" button =====

We do not enforce how your app should look or work on AeroPad but we do recommend, especially for apps that use the ''''self'''' option in the ''lrm-plugin.js'''s ''open_mode'' setting that the app developer uses the following HTML snippet to add a standardised back button that users will become familiar with across all apps enabling them to quickly and easily navigate back to the AeroPad home screen.

We recommend that this HTML snippet is placed directly below your HTML files' ''<body>'' tag (this specifically uses "absolute placement" to ensure that it is easier for developers to integrate into their pages without breaking their content.

You may wish to update the ''margin'' parameters of the code template below (to make it fit better in your app's interface):


<file HTML>
<!-- Standard AeroPad "Back Button"-->
<span style="position: absolute; top: 0; margin-top: 5px; margin-left: 5px; z-index: 1000;">
        <a href="/plugins/" class="text-light">
            <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" fill="#FFFFFF"
                 class="bi bi-arrow-90deg-left" viewBox="0 0 32 32">
                <path fill-rule="evenodd"
                      d="M1.146 4.854a.5.5 0 0 1 0-.708l4-4a.5.5 0 1 1 .708.708L2.707 4H12.5A2.5 2.5 0 0 1 15 6.5v8a.5.5 0 0 1-1 0v-8A1.5 1.5 0 0 0 12.5 5H2.707l3.147 3.146a.5.5 0 1 1-.708.708l-4-4z"/>
            </svg>
            <i class="bi bi-arrow-90deg-left"></i>
        </a>
    </span>
<!-- End Standard AeroPad "Back Button"-->
</file>
 
===== Downloadable resources =====

These are some example files and templates that can be used by developers to test or use as a starting point.

  * App Icon templates (PSD and PNG format): {{ :lrm:developers:aeropad_app_icon_template.zip |}}

===== Deploying your app to the AeroPad app store (App Manager) =====

Whilst you can personally distribute your app by sending the plugin folder to whoever you would like and providing them the instructions as to how to install it (essentially telling them to copy the LRM installation directory and to paste it into the'' ws\plugins'' folder) we are currently in the process of building an "app store" style system (this is yet to be released).

In future, however, developers will be able to upload their plugin folder to a dedicated packages website that we will be releasing shortly, when developers release updates to their AeroPad apps they can simply re-upload the plugin to the new packages website and LRM will automatically alert users that new updates are available for your app. 

The packages site will also provide download stats and metrics to app developers (you can see how many installs, uninstalls and updates users have performed against one or more of your published apps!

The benefits of publishing your apps through the "App Manager" system as opposed to manually distributing them are as follows:-

  * You get easy access to install, uninstall and upgrade metrics (as a "count" - absolutely no personal data is provided)
  * Your users can easily install updates as these will be identified automatically.
  * Users can browse and find your apps without you having to personally market your app.
  * User can feel safe in the knowledge that the apps they install from the "App Manager" have been vetted for potential security flaws or data breaches.

The App Manager will ONLY provide the services for "free apps" - if you wish to make and sell as a premium app then you will be responsible for distributing your app(s).