Red Panda Apps logo 3D Printing Other Projects About Me

How to Write an Extension (For Beginners)

Note: This tutorial was first posted here.


Basic knowledge

App Inventor extensions are developed in Java, so a bit of knowledge is required. Developing extensions is only possible because the App Inventor source code is open source. Most extensions work on all App Inventor platforms. The exact instructions strongly depend on your OS, but I will try to keep them as general as possible. I am a beginner myself, so any help and suggestions are welcome. This tutorial will give you a general view from newbie to newbie.

What software you will need

  • Java Development Kit (JDK): Download here
  • Apache Ant: Download here
  • Google Appengine SDK: Download here (Make sure to download Standard Java Environment)
  • The App Inventor Sources: Download here
  • An editor for Java code (I use Notepad++)
  • Git to run Apache Ant: Download here
Maybe you are going to regret that later, but I decided that running a build server are not needed for newbies.

ATTENTION: Unlike previously stated here, Git is necessary to run Apache Ant.

Setting up your development environment (document)

Download the above mentioned software and unpack them respectively install them. Then set your Environment Variables. Under Windows 8 and higher do right click on Windows logo -> System -> Advanced Configuration -> Enviroment Variables. Add your ant and Java home directories to your path variable (use the /bin folder for that). Then add two new variables ANT_HOME and JAVA_HOME with the corresponding folder paths. Last but not least you need to add ANT_OPTS with the parameter -Xms512m. Detailed information can be found here

Things to notice

Make sure that the JRE and JDK are the same version. Make sure that your environment variables are set correctly. It is easier to put JDK, ant and appengine in a folder that does not contain spaces. If you do that, you have to add apostrophes before and after every path you write in the command line.

Using Git software

You can use a Git GUI for easier version control. You can use any Git software you want e.g.

  • GitHub
    most popular website, used by MIT to control contributions
  • Bitbucket
    similar to GitHub
  • GitLab
    For more professional users

Fork or Clone?

Clone the App Inventor Sources if you are a beginner and do not plan to change App Inventor's core components. Fork them if you plan to contribute to the App Inventor Sources or if you think you'll mess up something. Branches have the advantage that you can easily switch back to a working branch if you mess up something.

Instructions

For command line tools use the instructions at the bottom of the official instructions (Appendix A). Instructions for GitHub for Desktop: Sign up or in to your GitHub account. Go to the official App Inventor Sources repository on GitHub. Click "Clone or download" and then "Open in Desktop". Follow the instructions to clone the repository. If you want to to create a new branch, in GitHub desktop, click "Branch" and then "New branch..." and follow the instructions. Alternatively, use the shortcut "Ctrl+Shift+N" to directly create a new branch. You can also download a .zip file if you don't want to create a GitHub account (not recommended).

Procedure (document)

The App Inventor team did sum this up very good:


Here are the steps we recommend in building an extension component. [...]

  1. Set up a local version of App Inventor for your own use, building a simple extension component for it, as practice.
  2. Build your desired component for your local instance and test it carefully.
  3. Modify your component to have the correct package name.
  4. Generate an aix file, so that the extension can be imported.
  5. Test the aix file by importing the extension into a project you build on the public App Inventor server.
  6. Publish your extension.

But let's do this step by step. If you are familiar with using extensions, you can start with chapter 3 of the official instructions. Anyway, run ant to make sure that everything is working correctly. It takes a few minutes, but should display "BUILD SUCCESSFUL Total time: xxx minutes"

1. Your first extension

For your first extension, add your own lines to the description under @DesignerComponent of an existing component. You find all existing components in the folder /appinventor-sources/appinventor/components/src/com/google/appinventor/components. Save the file and launch a local App Inventor instance (see command below) to see your changes. Make sure to run ant MakeAuthKey before your first launch.

2. Your first own extension

Then start with a new file called ExistingExtensionAlt.java (e.g. CameraAlt.java) in the appinventor/components/src/com/ directory. The folder structure behind src/ will be your package name. I recommend com/yourname/ as folder structure and com.yourname.extensionname as package name. These should be written in lowercase. Note: Your package name should be unique to prevent incompatibility issues. Copy the code of ExistingExtension.java to your file. Now this is "your" component and you have to make some changes to make it working. First and most important, change all appearances of ExistingComponent to ExistingComponentAlt. Your file name is your class name and extension name and must be in CamelCase. Now you have to modify some lines of code to make this an external component.

3. Things that are required

  • Your file name will be your extension name and must be your class name. All must be in CamelCase
  • Your (unique) package name
  • Import of App Inventor's core libraries
  • @DesignerComponent properties
    • A version number in integer format, specified by version
    • A good description what your extension does, specified in the field description
    • category = ComponentCategory.EXTENSION, nonVisible = true cannot be changed
    • Your extension icon, specified in iconName. You can use a link to a publicly accessible image or you can pack it with your extension. Remember that loading images from the web can be slow. If you want to pack your image with the extension, put it in a folder called aiwebres and refer to it as aiwebres/[YOUR_ICON_NAME].png. The icon should be a 16x16 png image
    • Everything separated by a comma
  • @SimpleObject(external = true), all before your class.
Again, save the file and launch a local App Inventor instance to test it. Run ant extensions to pack your extensions and share them.

4. Now you're ready to rock

Now the only thing left is learning Java (if you have not already done that) and rock the community! You can now write extensions with the help of Android Java. Awesome! If you don't know where to start, take a look at the open source extensions below. And if that doesn't help, look in the forum what extensions people need. See this documentation to see how to add components. You can download my example extension here.

Note:

  • Don't leave the @UsesPermissions annotation empty, it prevents users of your extension from uploading it to Google Play
  • @DesignerProperty has to be accompanied by an @SimpleProperty annotation, use @SimpleProperty(userVisible = false) to hide it from the user

Used commands

All commands must be executed in your appinventor folder (the folder that contains e.g. the build.xml and the Readme). Use the command line tool of your OS for them.

  • ant
    Compiles your local App Inventor instance and builds it
  • ant extensions
    Compiles your extension(s) and generates the .aix file(s)
  • ant clean
    Cleans your workspace. Has to be run before every build. Can be useful sometimes
  • (path_to_appengine)/bin/dev_appserver._(file)_ --port=8888 --address=0.0.0.0 appengine/build/war/
    Launches an App Inventor instance on your local machine. Replace (path_to_appengine) with the actual path and _(file)_ with cmd (for Windows) or sh (for Linux/macOS)
    You have to run ant MakeAuthKey once to use your Local App Inventor Instance
    Type localhost:8888 in your browser to use it
  • ant RunLocalBuildServer
    starts a local build server (the local App Inventor instance cannot compile apps)