• What is AGS ?
• Architecture of an AGS project
  • Directories and files of AGS project
    • Directory assets
    • Directory bin
    • Directory config
    • Directory releases
    • Directory src
    • Directory vendor
  • Overview of AGS
    • The main entry program MyApplication.au3
    • The main manager of graphic user interface GUI.au3
    • Centralize the declaration of global variables
    • The main manager of services SERVICES.au3
    • Easy deployment with Windows installer generation
  • Dependencies manager for AutoIt
    • AGS-component and AGS-wrapper
    • Describe an AGS project and its dependencies
  • Manage application versions
    • Control version with Git
    • Check the updates of the application
  • Configure AGS project
    • Create a configuration file
    • Constants and global variables

What is AGS ?

AutoIt Gui Skeleton (AGS) give an environment for developers, that makes it easy to build AutoIt applications. To do this AGS proposes to use conventions and a standardized architecture. It also gives tools to help developers in recurring tasks specific to software engineering.

Architecture of an AGS project

An AGS project respects this following organization for its files and directories.

Project root folder
.
|   .gitignore                 # Specifies untracked files to ignore in AGS project
|   .yarnrc                    # Yarn configuration used in handling AutoIt dependencies 
|   MyApplication.au3          # The main entry progam. 
|   package.json               # Use npm's convention to describe this project
|   README.md                  # In human readable.
|   RELEASES.json              # Repository for all releases notes of this application.
|      
+---assets                     # Applications assets (images, pdf, static files...) 
|   
+---bin                        # Binary tools
|              
+---config                     # Configuration of application.
|       parameters.ini         # Parameters which can be modified by user in application
|       parameters.ini.dist    # Template of parameters.ini which is save in  control version
|              
+---releases                   # Releases application (zip and windows setup)
|          
+---src                        # AutoIt source
|   |   BUSINESS.au3           # Entry point for business and logic code
|   |   GLOBALS.au3            # Entry point for constants and global variables of application
|   |   GUI.au3                # Entry point for graphic user interface (GUI)
|   |   SERVICES.au3           # Entry point for services applications
|   |      
|   +---business               # Folder for store all business annd logic code
|   |      
|   +---services               # Folder for store all services application 
|   |       Dialogbox.au3      # Handler of dialog box in which the user is prompted
|   |       ParametersIni.au3  # Handler of configuration file parameters.ini     
|   |       
|   \---views                  # Folder for store all views application
|           View_About.au3
|           View_Footer.au3
|           View_Settings.au3
|           View_Welcome.au3
|            
\---vendor                     # Third party code and dependencies handles with npm repository            

Directories and files of AGS project

We organize the files of an AGS project in specific directories.

Directory assets

This directory contains all the elements used in the application like images, text files, pdf, html, css, javascript. Note that it is possible to integrate static html file into an AutoIt application by using a web browser embedded in the GUI with the _IECreateEmbedded () method provided by the IE.au3 library.

Directory bin

This directory is used to store all project executables. The AGS-console, as a command line application (CLI) is stored in this folder. It is built in the Node.js ecosystem with the library Caporal.js. It provides commands to help developpers, for example to clean all AutoIt files of project with Tidy, or to create a Windows setup, or to quickly scaffold out a new project by choosing a template of AGS project.

Directory config

An AGS project must have a configuration file ./config/parameters.ini.

Be careful, this file is not save with control version, so to create a new one you can use ./config/parameters.ini.dist as a “template” of what your parameters.ini file should look like. Set parameters here that may be different on each application. To use this configuration file, we have the constant $APP_PARAMETERS_INI, wich contains the full path of this file. This constant is defined in ./src/GLOBALS.au3, and each time the application is started, AGS checks the existence of the configuration file.

Directory releases

This directory contains the result of a Windows batch that controls the creation of a Windows installer via InnoSetup. To execute this batch, it is necessary that the InnoSetup compiler and 7zip are installed on the pc. If this is not the case, we advise you to use the Windows package manager Chocolatey to install them easily.

choco install 7zip
choco install innosetup

Directory src

All the AutoIt source code of application is store in this directory. You can found specific directories in the latter : services and views, as well as specific files : GLOBALS.au3, GUI.au3 and SERVICES.au3.

Directory vendor

All third party code must be store in this directory.

In order to simplifiy handling dependencies of an AutoIt project, we use yarn and the npmjs.org repository to share AutoIt libraries. All AGS packages hosted in this npmjs repository belong to @autoit-gui-skeleton organization. And you can find two types of packages that are hosted in this organization:

• An AGS-component is an AutoIt library created specifically for AGS. You can use it more easily in your AutoIt project built with the AGS framework. For the example, take a look of AGS-component http-request.
• An AGS-wrapper is a simple wrapper for another AutoIt library, created by another team/developper. Take a look at this example AGS-wrapper-json.

To install all dependencies of a given project ; we assume that you have a valid package.json that describes your project and its dependencies ; you just have to execute this command: λ yarn install. And so all the dependencies of this project are installed into the ./vendor/@autoit-gui-skeleton/ directory.

Overview of AGS

The main entry program MyApplication.au3

This is the single point of entry for the application, and the location where the application starts. In the latter, we begin by including all other dependencies that it needs: AutoIt libraries, third-party libraries, global variable declaration, and code for the GUI and application services.

The application starts with the main GUI of the GUI _main_GUI().

The main manager of graphic user interface GUI.au3

The ./src/GUI.au3 file is the entry point for all view managers, that are saved in the./views directory. We will call it main manager of the GUI. The code for each view is defined each time in a specific file and stored in this ./views directory.

The main manager GUI contains especially the _main_GUI() method, which allows to start the application. This method is only called from the main entry program of the application, and it was designed to create the user interface (GUI) and manage all user interactions and events in the application.

Centralize the declaration of global variables

All constants and global variables are defined in one place in the ./src/GLOBALS.au3 file, in order to centralize the declaration of all global variables. With the exception of all the global variables of the graphic elements, which they are defined in each specific view file. Don’t forget that constants can no longer change value over time, unlike global variables. If a global variable changes its value, it can not be persisted , unless to do it in the configuration file ./config/parameters.ini.

By convention, all global variables must be capitalized and separated by an underscore. For example: Global Const $ APP_EMAIL_CONTACT

The main manager of services SERVICES.au3

The ./src/SERVICES.au3 file is the entry point for all services, that are saved in the./services directory. For example, in AGS, we still have the ParametersIni.au3 service that provides a method to work with the application’s configuration file. It allows to save the changes chosen by a user from the graphical interface.

Easy deployment with Windows installer generation

To facilitate the deployment of a Windows desktop application develop with AutoIt, AGS provides an automated process for generating a Windows installer with the solution InnoSetup.

To generate an AutoIt application installer, here are the main steps to follow:

• Assign a version number to the application;
• Compile the application, i.e. compile the main entry point myProject.au3 with the aut2exe compiler;
• Copy the assets (images, files …) necessary for the proper functioning of the application in the output directory;
• Create a zip archive to package the application;
• And finally build the installer by compiling the associated InnoSetup script.

All these steps are driven by a Windows batch.

Dependencies manager for AutoIt

In order to simplify the management of the dependencies of an AutoIt project built with AGS, we have diverted form its initial use the dependency manager npm, and its evolution Yarn.

This allows us to manage the dependencies of an AGS project with other AutoIt libraries, and to share these AutoIt packages from the npmjs.org repository. We assume that you have already install Node.js and Yarn, for example with Chocolatey.

AGS-component and AGS-wrapper

All AGS packages hosted in npmjs.org repository belong to the @autoit-gui-skeleton organization. And you can find two types of package hosted in this organization:

• An AGS-component is an AutoIt library, that you can easy use in your AutoIt project built with the AGS framework. Take a look of AGS-component http-request.
• An AGS-wrapper is a simple wrapper for an another library created by another team/developper. Take a look of AGS-wrapper-json

To install an AGS component or wrapper in your project, just type in the root folder where the package.json is stored:

yarn add @autoit-gui-skeleton/ags-component-xxx --modules-folder vendor
yarn add @autoit-gui-skeleton/ags-wrapper-xxx --modules-folder vendor

Describe an AGS project and its dependencies

To describe an AGS project and its dependencies we naturally use the package.json file, specific to the Node.js ecosystem. You can find more information about this file, and how to fill it here : https://yarnpkg.com/lang/en/docs/package-json/.

{
  "name": ApplicationWithCheckForUpdates,
  "version": "1.0.0",
  "description": "Example to implementation of AGS-component-check-for-updates",
  "AGS": {
    "framework": {
      "version": "1.0.0"
    },
    "AutoIt": {
      "version": "3.3.14.5"
    }
  },
  "author": "v20100v <v20100v@no-reply.com>",
  "license": "MIT License",
  "year": "2018",
  "private": true,
  "repository": {
    "url": "not-yet-git",
    "type": "git"
  },  
  "dependencies": {
    "@autoit-gui-skeleton/AGS-component-check-for-updates": "^1.0.0"
  }
}

And finaly to install all the dependencies of a given project, you just have to launch this command:

yarn install --modules-folder vendor

All project dependencies, as well as daughter dependencies of parent dependencies, are installed in the ./vendor/@autoit-gui-skeleton/ directory. If you add AutoIt library in the vendor directory, we recommend wrapping them so that they are also managed by the dependency manager, in the same way as AGS-wrapper-json

To install AutoIt dependencies in the ./vendor directory, and not in the default directory of Node.js ./node_modules, you must add the --modules-folder vendor option. We force this choice to avoid any confusion with a Node.js project. Note that with an AGS project, it is not necessary to explicitly write this option on the command line, thanks to the .yarnrc file stored at the root of the project, ie in the same place as the package.json file. Yarn automatically use this file to add an additional configuration of options.

 #./.yarnrc 
 --modules-folder vendor

So with this file you can run yarn install to install the dependencies directly into the appropriate ./vendor directory.

Manage application versions

Control version with Git

In an AGS project, we prefer to use Git for control version. So we natturally add the .gitignore file in the root of the AGS project to exclude files. It uses globbing patterns to match against file names. You can find help to make it here https://www.atlassian.com/git/tutorials/saving-changes/gitignore.

If you use a control version, don’t forget to set the repository property of your ./package.json.

"repository": {
  "url": "https://host.com/my-depot.git",
  "type": "git"
}

Check the updates of the application

The json file RELEASES.json is used as a repository to trace all successive versions of the application. For each version described into it, there is a link to download this version of the application and a link for the release notes associated with this version. This file must be hosted on a remote server, without access constraint.

To check if an update is available, just compare the local version of the application installed on the PC, with the latest version stored in this JSON repository. It is therefore necessary to have an internet connection.

The RELEASES.json file must respect the following schema:

Properties	Description
name	Name of application.
description	Short description of application.
license	License of application.
persistUrl	URL where this file is persist on remote server.
releases	Collection of release schema.
release.version	Version of application use as an id.
release.state	More information of this version.
release.downloadSetup	URL where you can find the setup of this version.
release.published	Date of publication for this version (YYYY-mm-dd).
release.releaseNotes	URL where you can find the release note of this version.

{
  "name": "MyApplication",
  "description": "Example of RELEASES.json and implementation of AGS-component-check-for-updates",
  "license": "MIT",
  "homepage": "https://github.com/v20100v/autoit-gui-skeleton/",
  "persistUrl": "https://myServer/myApplication/RELEASES.json",
  "releases": [
    {
      "version": "1.0.0",
      "state": "stable",
      "downloadSetup": "https://myApplication.com/download/setup_myApplication_v1.0.0.exe",
      "published": "2018-10-07",
      "releaseNotes": ags-component-check-for-updates
    },
    {
      "version": "0.9.0",
      "state": "stable",
      "downloadSetup": "https://myApplication.com/download/setup_myApplication_v0.9.0.exe",
      "published": "2018-10-07",
      "releaseNotes": ags-component-check-for-updates
    },
    {
      "version": "0.1.0",
      "state": "prototype",
      "downloadSetup": "undefined",
      "published": "2014-03-21",
      "releaseNotes": "undefined"
    }
  ]
}

The RELEASES.json file is used with the AGS-component check-updater. This library provides the function of updating an AutoIt application. Take a look at this sample AutoIt application that implements this component ApplicationWithCheckForUpdates. This application has the following features:

• Check the update when starting the AutoIt application;
• Check the update from an interaction in the menu “? > Check update”;
• Change the application settings from the “Configuration > Settings” view. Changed values are persisted in the ./config/parameters.ini configuration file. In this view, we can set proxy parameters to specify how this application connects to the Internet, and sends HTTP requests.

If the check option for the update to the start application is enabled and a new version of this application is available, then when the user starts the application this component informs the user in a child window :

Configure AGS project

To configure an AGS project, we have:

• A ./config/parameters.ini configuration file, whose parameter values can be modified by users.
• Constants and global variables are defined in ./src/GLOBALS.au3.

Create a configuration file

When you start a new AGS project, you must create this configuration file ./config/parameters.ini. This file is not versioned. You can use ./config/parameters.ini.dist as a ‘template’ of what this file should look like. Set the parameters here that may be different on each application. Only this file is saved with the control version.

If you add an AGS component, you can configure it into this file. For example with AGS-component check-updater you can choose if the application have to search a new update on start-up with the LAUNCH_CHECK_FOR_UPDATE_ON_STARTUP parameter.

[AGS_CHECK_FOR_UPDATES]
; [REQUIRED] Enable/disable the search of a new update on start-up.
LAUNCH_CHECK_FOR_UPDATE_ON_STARTUP=1

For another example with the component AGS-component http-request, we can configure a proxy of the following way:

[AGS_HTTP_REQUEST]
; [OPTIONAL] Use a proxy for http connexion
PROXY=http://myproxy.com:8080

Constants and global variables

All constants and global variables are set in one place ./src/GLOBALS.au3, with the exception to global variables of graphic elements which are set in each specific view file. Don’t forget that constants can’t longer change their value over time, unlike global variables. By convention, all global variables must be written in capital letter and separated by underscore - for example : Global Const $APP_EMAIL_CONTACT.

In this global variables file, we find in particular the following section of the main constants of the application:

;----------------------------;
; Application main constants ;
;----------------------------;
Global Const $APP_NAME = "ApplicationWithCheckForUpdates"
Global Const $APP_VERSION = "0.9.0"
Global Const $APP_WEBSITE = "https://myApplication-website.org"
Global Const $APP_EMAIL_CONTACT = "myApplication@website.org"
Global Const $APP_ID = "v20100v.ApplicationWithCheckForUpdates"
Global Const $APP_LIFE_PERIOD = "2018-" & @YEAR
Global Const $APP_COPYRIGHT = "© " & $APP_LIFE_PERIOD & ", v20100v"

With the component AGS-component check-updater we set the constant $APP_REMOTE_RELEASES_JSON to specifiy where the repository JSON is hosted. This json file must be persisted in a remote server available via internet, and without restriction.

Global Const $APP_REMOTE_RELEASES_JSON = "https://myServer/myApplication/RELEASES.json"

Continue reading ?

2. Code organization in AGS project.