Build your first app

Updated on 20-October-2016 at 10:16 AM

Business Catalyst End of life announcement - find out more details.

Before developing a custom application, you will need to register to the Business Catalyst Developer program. To do this, go to Partner Portal->My Apps and click Enroll. Agree to the Developer Terms and conditions and create your developer prefix.

NOTE: You need to have at least 1 paid site to be able to enroll in the Business Catalyst Developer program.

After you have enrolled in the Developer program, you can start creating your apps. Just go to the Partner Portal->My Apps and click the "Create New App" button. Enter the requested information, following the on-screen instructions:

  • Enter an App name - this will be the name of your application, 
  • Enter an App ID - this ID, combined with your Developer ID will be your App ID. The App ID is the unique identifier of your app and is unique throughout Business Catalyst. It also represents the folder you can install your app within.
  • Choose the site you want to develop the app on

After you submit the form the app will be generated and the basic setup files will be installed on the indicated site. The folder where the app will be deployed is:  

/_System/apps/[app-id]

Structure of a BC app

The components

The 3 main components of a Business Catalyst app are:

  • The menu.json file - accessible under /_System/apps/[app-id]/_config  - this is a file that creates the entries in the Admin Console menu. The users will use these custom menu entries to trigger the app. 
  • The app's landing page - this is the first page the user sees after the app is launched in the Admin Console. This page must be located in the app's folder - "/_System/apps/[application_key]/index.html
  • Any other assets - CSS, JS, pages and other files you need to use. These assets are usually stored in the public folder located in your app's folder

The folder structure

There are only 2 folders that need to be in specific locations:

  • The application's folder has to be /_System/apps/[appID] . For example, if your app name is "Daily Scheduler" and your app key is "daily-scheduler-1" the folder for your application will be /_System/apps/daily-scheduler-1
  • The second folder is the folder that contains the menu.json file. This has to be named _config and placed directly in the app's folder - /_System/apps/[application_key]/_config/menu.jsonhere is how  you can further customize the menu.

Any other assets your app might use like images, stylesheets, javascript files, webpages and so on can be located anywhere on your site except in the folders of other apps.

For example, app "Daily Scheduler" located in /_System/apps/daily-scheduler cannot access a file located in /_System/apps/bc-first-app-hello-world but it can access files in the /images folder located in the root of the site.

Please take a look at the "Best practices " section in order to ensure the files and folder structure of your app is as streamlined as possible.

Back-end or front-end?

An important step of planning your app is to decide how to manage the assets. You should decide if you will be using back-end pages that will be available for users logged into the Admin console and front-end pages available to site visitors.

For example, imagine you build an app that will have a back-end page that allows users logged into the Admin Console to add webapp items and it has a front-end page that is publicly available where site visitors can see the webapps added via the back-end.

In both the back-end and front-end pages you need to link your logo (logo.png) and a background image (background.png).

The correct way to make sure the logo.png and background.png are available to both back-end page and front-end page is to place the assets you want to be rendered in the front-end in the app's public folder. To protect an app's sensitive assets any other app files outside this folder will not be available in the front-end.

This means that if you link in a front-end page to the image /_System/apps/my-custom-app/images/background.png, the site visitor will receive an error and will not be allowed access to that particular asset. The correct way would be to place this image in /_System/apps/my-custom-app/public/images/background.png

Building a basic "Hello World" custom app

Let's consider that you've just created a new app named "Hello World". For this example, we'll say that your app ID is: "bc-first-app-hello-world". This is what you'll find in your site: 

  1. The config file that adds a new menu entry:  _System/apps/bc-first-app-hello-world/_config/menu.json file:{
  2. The app's landing page - /_System/apps/bc-first-app-hello-world/index.html

Open the Admin of your site and navigate to the new "Hello World" menu entry. When you click the menu entry, the index.html landing page loads. Any page linked from the landing page will load in the same context.

After the landing page is loaded and the authentication script executes you can call any of the APIs described in our API reference  or redirect the user to any other page on your site.

Next steps

In the next section , we will take a look at different components you can use with your applications.