¶ Technical Overview
Creating a smartCARS 3 plugin enables you to add custom features or change built-in behavior inside the desktop application. Below, we will explain how the plugin system works and how to get started creating your own plugin.
¶ Technology
smartCARS 3 is an Electron-based application that hosts sub-web applications internally. The system is divided into three basic layers or systems. All of the default plugins and the main web UI are written in React JS.
¶ The Core
The smartCARS core is the main process and is responsible for primary data storage, responding to and hosting various local APIs, and loading other systems. Plugin developers will only use APIs provided by the core; none of its code is accessible to plugins.
The core also loads and hosts the web code sponsible for the main smartCARS UI. The web code provides the application frame, profile, radio player, settings menu, plugin UI, and the main menu.
All other content and functionality is provided via plugins.
¶ Plugins
A plugin may consist of one, or both, of the plugin components: the UI and the background. At its simplest, a plugin is essentially a small website that is loaded into the smartCARS interface when clicked. This allows a developer to provide any interface or functionality they'd like directly within smartCARS using only HTML, CSS, and JavaScript.
A plugin UI, however, is volatile, meaning that it is cleaned up and removed from memory the moment a user navigates to another plugin or system (profile, settings, etc.) within smartCARS.
To account for this, plugins can also provide "background" code. Background code is JavaScript code loaded by the core of smartCARS and retained throughout the duration of the application's lifecycle. The background is where flight tracking, the connection to the chat server, and other critical, system-wide functions exist in the default plugins.
By sending data from the UI to the background, data can be retained and accessed by your plugin, or by other plugins (if desired), at any time.
React JS is not required for plugins, but is recommended.
¶ Application Lifecycle
The standard smartCARS application and plugin lifecycle are as follows:
- A user opens smartCARS
- The core checks for updates and other critical runtime variables
- The core loads the web code and primary UI
- The user is presented with the login and VA selector interfaces
- The user logs in
- The core generates a list of plugins that should load based on user preference and VA settings
- The core determines what plugins must be installed or updated and does so
- The core sequentially loads the background code of each active plugin that provides any
- The main UI is presented and the user may begin to use the application
Starting smartCARS in development mode replaces step 6 by instead loading all plugins that exist on the computer at that time. It also disables plugin installation, uninstallation, and updating. To start in development mode, the application must be started with the '--local' argument (implying that the 'local' plugin list is the authority, instead of secure TFDi Design plugin storage).
Development mode, although an important feature for developers, allows any code in the plugins folder to be run without confirmation and should never be used on a production device.
¶ Folder Structure
The smartCARS folder structure is as follows. By default, smartCARS is installed to "%localappdata%\TFDi Design\smartCARS".
From that main folder, plugins exist in the "dist\plugins" folder, each in their own subfolder named after their package ID (in the format of "com.example.pluginname").
Within each plugin folder there can be a "ui" and "background" folder, as required. The "ui" folder must contain an index.html and associated web interface code. The "background" folder must contain an index.js that contains the entry point for the background code.
In the root level of a plugin folder, a plugin.json file must exist with the required fields.
¶ Local API Reference
There are several (local) core APIs provided by the core to help plugin developers. These are outlined by category below. They are accessible via http://localhost:7172. For example, a call to get the user identity would be http://localhost:7172/api/identity.
¶ plugins
| API Call | Method | Description | Notes |
|---|---|---|---|
| api/plugins | GET | Retrieve a list of all currently available custom plugin API endpoints | Refer to plugin documentation for specifics on each endpoint - these APIs are hosted on the same URL and port as the core API |
Response - 200
[
{
"method": "GET",
"path": "/api/com.tfdidesign.flight-center/flights",
"description": "Endpoint to list flights"
},
{
"method": "GET",
"path": "/api/com.tfdidesign.flight-center/bookings",
"description": "Endpoint to list bookings"
},
{
"method": "GET",
"path": "/api/com.tfdidesign.flight-center/airports",
"description": "Endpoint to list airports"
},
{
"method": "GET",
"path": "/api/com.tfdidesign.flight-center/aircrafts",
"description": "Endpoint to list aircrafts"
},
{
"method": "POST",
"path": "/api/com.tfdidesign.flight-center/create-flight",
"description": "Endpoint to create a flight"
},
{
"method": "POST",
"path": "/api/com.tfdidesign.flight-center/unbook-flight",
"description": "Endpoint to unbook a flight"
},
{
"method": "POST",
"path": "/api/com.tfdidesign.flight-center/book-flight",
"description": "Endpoint to book a flight"
}
]
¶ plugins/installed
| API Call | Method | Description | Notes |
|---|---|---|---|
| api/plugins/installed | GET | Retrieve a list of all active plugins | Other plugins may be installed but not active based on community settings |
Response - 200
[
{
"id": "com.tfdidesign.chat",
"name": "Chat",
"version": "0.9.0",
"type": "airline",
"description": "The chat system for smartCARS"
},
{
"id": "com.tfdidesign.flight-center",
"name": "Flight Center",
"version": "0.9.0",
"type": "airline",
"description": "The flight booking system for smartCARS"
},
{
"id": "com.tfdidesign.flight-tracking",
"name": "Flight Tracking",
"version": "0.9.0",
"type": "airline",
"description": "The flight tracking system for smartCARS"
},
{
"id": "com.tfdidesign.logbook",
"name": "Logbook",
"version": "0.9.0",
"type": "airline",
"description": "The PIREP viewer and flight breakdown system for smartCARS"
},
{
"id": "com.tfdidesign.map",
"name": "Map",
"version": "0.9.0",
"type": "airline",
"description": "The map for smartCARS 3"
},
{
"id": "com.tfdidesign.simbrief",
"name": "SimBrief",
"version": "0.9.0",
"type": "user",
"description": "SimBrief integration for smartCARS 3"
}
]
¶ navigate
| API Call | Method | Description |
|---|---|---|
| api/navigate | POST | Navigate the primary content view to a specific plugin |
Request Body
{
"pluginID": "com.example.plugin"
}
Response - 200
No output - application navigated to the plugin
Response - 404
No output - specified plugin not found
¶ store
| API Call | Method | Description |
|---|---|---|
| api/store/:key | GET/POST | Stores a key value pair in the local store |
The key parameter must be sent as GET.
Request Body
Request body is the value to be stored
Response - 200
Output matches request body
¶ retrieve
| API Call | Method | Description |
|---|---|---|
| api/retrieve/:key | GET/POST | Retrieves a stored key value pair from the local store |
The key parameter must be sent as GET.
Response - 200
Output is value or empty
¶ log
| API Call | Method | Description | Notes |
|---|---|---|---|
| api/log | POST | Log an item to the smartCARS system log | The log function in the smartCARS SDK wraps this call |
Request Body
{
"message": "Something happened",
"level": "info",
"data": "some optional custom object, number, or text to be logged"
}
Response - 200
No output - item was logged
Response - 400
No output - invalid request, item not logged
¶ open-link
| API Call | Method | Description |
|---|---|---|
| api/open-link | POST | Open a link in the default system browser |
Request Body
{
"link": "https://website.com"
}
Response - 200
No output
¶ blockclose
| API Call | Method | Description | Notes |
|---|---|---|---|
| api/blockclose | POST | Indicate that the application should ask the user for confirmation before closing based on a specified reason identifier | The blockName value is not displayed and should simply be a unique, memorable string - subsequent calls with the same blockName are safely ignored and do not stack |
Request Body
{
"blockName": "flight-tracking"
}
Response - 200
No output
¶ unblockclose
| API Call | Method | Description | Notes |
|---|---|---|---|
| api/unblockclose | POST | Indicate that the application should no longer ask the user for confirmation before closing based on a specified reason identifier | The blockName value is used to remove that reason from the stack and must match the one used to block initially |
Request Body
{
"blockName": "flight-tracking"
}
Response - 200
No output
¶ identity
| API Call | Method | Description | Notes |
|---|---|---|---|
| api/identity | GET | Retrieve the current user and community information | The tfdi_design_user field may not be set if the TFDi Design login was skipped |
Response - 200
{
"tfdi_design_user": {
"id": 1,
"hasPremium": false,
"token": "abc123",
"firstName": "John",
"lastNameInitial": "D",
"authority": 0,
"developer": false,
"tester": false,
"showHost": false
},
"va_user": {
"dbID": 1,
"pilotID": "ABC1",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"rank": "User",
"rankImage": "http://site.com/image.png",
"rankLevel": 0,
"avatar": null,
"session": "abc123"
},
"airline": {
"id": 1,
"isPartner": true,
"settings": {
"airlineName": "smartCARS Community",
"airlineICAO": "SCC",
"accentBackgroundColor": "#45ade2",
"accentForegroundColor": "#FFFFFF",
"welcomeMessage": null,
"maintenanceMode": false,
"maintenanceModeMessage": null,
"logo": "default/logo.png",
"logoDark": "default/logo_dark.png",
"icon": "default/icon.png",
"scriptURL": "https://site.com/smartCARS/api/phpvms5/",
"vaURL": "https://site.com",
"ico": "default/icon.ico"
},
"plugins": [
{
"id": "com.tfdidesign.flight-center",
"name": "Flight Center",
"verified": true,
"downloads": 617,
"rating": 1,
"totalReviews": 6,
"author": "TFDi Design",
"description": "The flight booking system for smartCARS",
"lastUpdated": "2023-05-16 21:37:21",
"version": "0.9.0",
"type": "airline",
"availableSettings": {
"enable_booking": {
"name": "Enable Flight Booking",
"type": "boolean",
"default": true,
"description": "Allow pilots to search for and bid on flights"
},
"charter_flights": {
"name": "Allow Flight Chartering",
"type": "boolean",
"default": false,
"description": "Allow pilots to create new single-use flights"
}
},
"appliedSettings": {
"enable_booking": true,
"charter_flights": true
}
}
]
}
}
¶ settings
| API Call | Method | Description |
|---|---|---|
| api/settings | GET | Retrieve the current user settings |
Response - 200
{
"com.tfdidesign.simbrief": {
"simbriefUsername": "myusername",
"simbriefAdvancedFlightTracking": true
}
}
¶ notification
| API Call | Method | Description | Notes |
|---|---|---|---|
| api/settings | POST | Send a notification to the client and receive the notification ID | This API can be used for toast-only notifications or persistent and alerted notifications |
Request Body - Toast Only
{
"source": "com.example.plugin",
"type": "info",
"toast": {
"type": "info",
"message": "Something happened"
}
}
Request Body - Full, Persistent Notification with Toast, Flash, and Sound
{
"source": "com.example.plugin",
"type": "info",
"message": "Something happened"
"toast": true,
"data": "some optional object or data"
}
Request Body - Quiet, Persistent Notification with No Toast
{
"source": "com.example.plugin",
"type": "info",
"message": "Something happened"
"toast": false,
"quiet": true,
"data": "some optional object or data"
}
The type field may be one of info, warning, success, or danger. The toast field may be unset, an object, or a boolean. An object allows granular control of the toast separate
Response - 200
{
"id": "5f6d5571-1960-4021-9ef1-739ecc507096"
}
¶ Making a Plugin
Armed with an understanding of how smartCARS and its plugins work, a plugin can now be created.
¶ Setting Up
First, create the folder for your plugin in the %localappdata%\TFDi Design\smartCARS\resources\app\dist\plugins folder. In there, create a plugin.json file and fill it out as described below.
For a full source example of a working plugin, refer to the TFDi Design Flight Center plugin on GitHub.
¶ The plugin.json
{
"id": "com.example.pluginname",
"name": "Plugin Name",
"organization": "",
"allowedCommunities": [],
"version": "0.0.1",
"type": "user",
"description": "An example plugin",
"availableSettings": {
"some_setting": {
"name": "Enable some feature?",
"description": "Do you want to have this feature do its tasks?",
"type": "boolean",
"default": false
}
}
}
In the above example, the fields are as follows.
- id: The package name of the plugin. This should typically be the TLD of the organization, the common name, and the name of the plugin separated by dots (i.e. com.tfdidesign.chat)
- name: This is the name of the plugin to be displayed to the user
- organization: An organization name to be displayed as the author - this is an optional field
- allowedCommunities: This an optional field consisting of an array of numeric community IDs this plugin is available to - this can be used to limit access during testing or create community-specific features.
- version: The version string of the plugin
- type: Specifies whether this plugin is installed by a user or a community - options are
userorairline - description: The textual description of the plugin to display to a user
- availableSettings: An array of plugin settings (see below)
The
allowedCommunitiesfield serves primarily as a filter and should not be considered a security measure or protection system.
¶ Settings
The availableSettings field of the plugin.json is an array of settings, as described below.
The settings are stored as a key-value-pair, where the key is the setting key (to be used to find the value later) and the value is the object describing the setting.
A barebones setting is as follows:
"some_setting": {
"name": "Enable some feature?",
"description": "Do you want to have this feature do its tasks?",
"type": "boolean"
}
The possible settings and all of their possible configuration options are listed below. All settings can have an optional required field specifying that it must be checked and/or filled.
¶ Boolean (Toggle)
"my_setting": {
"type": "boolean"
}
¶ Range (Slider)
"my_setting": {
"type": "range",
"min": 0,
"max": 10,
"step": 1
}
¶ List (Combobox)
"my_setting": {
"type": "list",
"options": {
"option_1": "Option 1",
"option_2": "Some other option"
}
}
¶ Number
"my_setting": {
"type": "number",
"min": 0,
"max": 10,
"step": 1
}
¶ Number
"my_setting": {
"type": "number",
"min": 0,
"max": 10,
"step": 1
}
¶ Date
"my_setting": {
"type": "date"
}
¶ JSON
"my_setting": {
"type": "json",
"minLength": 0,
"maxLength": 4096
}
¶ Long Text
"my_setting": {
"type": "longtext",
"minLength": 0,
"maxLength": 4096
}
¶ Radio Button
"my_setting": {
"type": "radio",
"options": {
"option_1": "Option 1",
"option_2": "Some other option"
}
}
¶ Text
"my_setting": {
"type": "text",
"minLength": 0,
"maxLength": 4096,
"pattern": "[A-Aa-z]*",
}
¶ Creating the UI
This is not a complete guide on creating a web interface and assumes you have at least basic experience coding in HTML, CSS, and JavaScript.
¶ Getting Started
To start creating a plugin UI, we must first create a web application. As mentioned, we recommend using React. To get started with a React web application, see https://create-react-app.dev/docs/getting-started.
The UI SDK contains helper functions and the UI styling. To install it, run
npm install @tfdidesign/smartcars3-ui-sdk
Once your project is initialized, you may add your UI code as needed.
Once your UI is built, the output must be placed in the ui folder within your plugin.
Some web application systems require that a homepage be specified. The homepage URL of the web app will be
/plugins/{your plugin ID}.
¶ Styling
smartCARS uses Tailwind CSS as the foundation of its UI styling. Tailwind, although technically not absolutely required, is strongly recommended as the default styling is based on its presence.
All plugins should include the smartcars.css file as it will apply the default smartCARS styling to all controls and classes. We encourage developers to review the classes within this CSS file to better understand it.
¶ Responding to Theme Customization
As each community can change its theme colors and the user can toggle light or dark mode, it is important for a UI plugin to respond to these changes. The community foreground color, background color, and current UI mode are sent as URL parameters to the plugin.
Additionally, the smartCARS UI SDK provides "applyVAColor" and "applyAppColor" functions that accept the parameters directly as given by the URL and update the CSS variables for you. This means that to support color customization and themes, you simply must use the provided classes and call the color application function. The rest is handled by smartCARS for you.
An example of how this is done in React is given below.
/*Toward the top of the file*/
import { request, applyAppColor, applyVAColor } from "@tfdidesign/smartcars3-background-sdk";
const MyComponent = () => {
const urlParams = new URLSearchParams(window.location.search);
const darkMode = urlParams.get("darkmode") === "true";
const foreColor = urlParams.get("forecolor");
const backColor = urlParams.get("backcolor");
applyAppColor(document, darkMode);
applyVAColor(document, foreColor, backColor);
/* ...Other ui work */
return (...);
};
¶ Menu Icons
A plugin must include two icon files in its root directory. The first must be named menu_icon_dark.png for use in dark mode, and menu_icon_light.png. If using React, this can be achieved in react by placing the two icons in the public folder within your project.
¶ Creating a Background
To create a background plugin, a JavaScript index.js file containing the plugin entry point must be created.
A background SDK with helper functions is also available on NPM. To install it, run
npm install @tfdidesign/smartcars3-background-sdk
A plugin may export onStart, acceptNotification, and onEnd function and a routes array to be used by smartCARS.
This is helpful if you want a notification to be conditionally silenced but cannot restrict the notification when it is generated. The data field of the notification is also forwarded to this function, meaning custom information added to your notification can be used to make this decision.
A full example of a barebones index.js is as follows:
module.exports = {
onStart: (identity) => {
//do setup
},
acceptNotification: (notification) => {
return "ACCEPT";
},
routes: {
get: {
somedata: {
description: "Endpoint to retrieve certain data. Returns object with data, takes no parameters.",
handler: async (request, response) => {
return response.status(200).json({});
},
},
},
},
onEnd: () => {
//do cleanup
},
};
¶ Startup and Shutdown
The onStart function is given an identity object. It is the same as the response from the api/identity call; it is simply provided here for ease and efficiency. The onStart and onEnd calls are performed sequentially and are blocking, meaning the UI cannot continue until they have returned.
¶ Routes
The routes object may have a get and post sub-object, both a collection of key-value-pairs that create plugin API routes. Plugins exporting routes this way is what populates the routes returned by the api/plugins call.
¶ Accepting Notifications
Finally, the acceptNotification function will be called by smartCARS when a notification sent by (or on behalf of) that plugin is about to be displayed. This function can then return ACCEPT, QUIET, or REJECT, indicating that smartCARS should display the notification normally, quietly, or not at all, respectively.
¶ Deployment
Once a plugin is developed, it must be deployed. To deploy a plugin, visit the Developer Center in smartCARS Central.
¶ Preparing to Upload
A packaged plugin is simply a zip file of the contents of the plugin. The plugin.json file must be at the root of the zip file (as pictured below).
Once ready, upload the plugin via the "Upload New Plugin" button in the Developer Center. This will create a new plugin based on the information in the plugin.json.
smartCARS Central will give relatively verbose error messages should a plugin not be accepted, making resolving issues easier.
To update a plugin, click the "Update" button and select the zip file containing the new plugin data.
¶ Plugin Verification
For obvious reasons, plugins are considered "third-party code" by the smartCARS core and as such, require user consent to install or update. Plugins that are verified by TFDi Design are considered "first-party" and can be installed or updated without an additional dialog. Verified plugins will also display that status in a green bubble to the users.
The requirements to have a plugin verified are outlined below.
- The developer must be known by the community and have a credible reputation
- The plugin source code must be provided to, built, and deployed by TFDi Design (credit will go to the submitting developer)
- The plugin must have had formal testing lasting at least 7 days with a sample size of 5 or more different users
Plugin verification is currently on a per-plugin, per-version basis. This means that if an update is uploaded to a verified plugin, it will become unverified and require re-verification by TFDi Design.
To inquire about having your plugin verified, please contact our support team.