Hello dear reader and welcome to the basic training course for the APP builder, an essential part of ONE DATA.
In this training, we will teach you the basics of an APP, so you can build one of your own, in a wonderful way - you will be learning APPs while working on/with an APP itself, discovering and changing it around to find out the possibilities that you have at hand to build your own.
In order to have the best experience as well as the best training outcome, we highly recommend that you read thoroughly through this article! The article will give further information on the software of APPs as well as tips & tricks how you can more easily steer through the training courses.
The following topics will be covered in the remainder of this article:
Prerequisites of the Training
Before you dive into the training, we would quickly inform you about some prerequisites to the training course. These are not a necessity - you do not have to do learn these things before you can start the course! -, but having knowledge about it will help you out a lot in order to understand APPs and get them going quicker.
The most important prerequisite is some basic knowledge on JSON, which is a lightweight text-based open standard designed for human-readable data interchange and also being "self-describing" and easily understandable. This among other reasons is why APPs does also utilize JSON as their code foundation. Every APP consists of JSON code, therefore it is useful to be accustomed to JSON before starting the training course. (There are quick tutorials that require only about 10 minutes of your time, like this external Article or this YouTube video.)
Similar to, but not as important, as the JSON for APP code is SQL. In some APP elements it is useful to filter the results that you want to see, for example in the case of listing data of a data table. To do so, you can add SQL statements that will directly be used on the input for the respective element. Here again, it is useful if you know your way around SQL. For the training however, we will support you with the SQL queries that you will need. (You can also find tutorials for SQL quickly, like the one supported by w3schools.)
Last but not least, it is useful if you know your way around a ONE DATA workflow in order to support data for your APPs and to know where you can find the relevant IDs of the datasets you would like to use in your APP. The following GIF will show you with a very simple workflow, how you can find out the ID of a data table:
The important points to take away are summarized:
- Your workflow must end in the persisting of a data table (generally you use the "Data Table Save" processor for this). Otherwise your data does not get persisted in a way, so that the APP Builder can access it.
- Make sure you run your workflow (at least once), so that the data table as a result can be persisted. Rerun the whole workflow, if you have done updates to your input data.
- Always give your data table to persist a name.
Overview of the Training Course
The overall training will cover different topics that are the basic building blocks for an APP. As it was promised in the introduction of this article, the training itself will be held inside of an APP. Code comments inside this respective APP will conveniently guide you through the learning process - so the actual thing learned will be directly communicated to you at the place inside the APP where you need it. To convey the leaning material, the training course will be split into modules, which are self-contained in their content, but tie together when you create an APP with all the features.
A training module will be split into two parts:
- A description page will give you all the information that you need to understand the learning topic of the respective module. A pre-created APP will thereby allow you to see how a finished APP could look like. With descriptive comments, you are asked to change various things of this description page and APP. With the preview of the APP directly next to what you change in the JSON code, you can directly see how those changes affect the APP.
- A task page covering exactly what you've then just discovered in a description page will present small assignments to foster what you have just learned. A target solution already included will let you test if you fullfilled the assignments correctly. Every description page will have a link to its associated task page.
Content-wise, the modules that are covered in this basic APPs training are the following:
- Pages and Layouts - teaching you how you can structure your APP placing down containers for elements to come
- Elements - giving you the possibility to create first elements like charts or KPIs
- Datasources - allowing you to connect your APP to data (originating from ONE DATA or mocked directly in the APP)
- Navigation - enabling the possibility to add different actual pages to your APP and the navigation between them
- SyncSets - as a powerful tool in order to connect elements, which allows you to make it possible that a click on one element (for example selecting a certain data entry) affect another element in changing its display
At certain points during the training, we will point you to the integrated documentation articles about APPs, which are contained in ONE DATA. But also we would like to highlight that you can find some specification documents also in our knowledge base here.
Explanation of the APP Builder, APP Viewer and Their Connection to ONE DATA
For the basic APPs training course, two modules of ONE DATA are in the key focus: the APP Builder and the APP Viewer. You can see their general interplay in the picture below.
The APP Builder is the key access point to actually creating APPs in the first place and it will also be the central point you will use during the APPs training. By now, the builder features an own IDE to support the creation of APPs, what is produced is the aforementioned JSON code.
When an APP is created, it can be accessed via the APP Viewer. It is important to mention here, that you can fine-tune the access to your APP via the User Management (which will not be covered in this training, but most likely in a later one. When you create an APP; only you will be able to access and view it by default).
The last building block of the picture consists of the preceding modules of ONE DATA, which deal with the processing and editing of (raw) input data. After the processing is done, data is readily prepared (visualized as "Data 1", "Data 2", and "Data x") to be displayed in an APP. This is done by persisting the data as a data table, which can then be connected to respective APPs via its ID. You have already read about how to find these IDs of data in the Prerequisites of the Training.
This overall shows the modular structure of ONE DATA: by themselves isolated modules are loosely tied together, allowing specialists to only focus on their target (processing of data or building APPs for example), connecting the results only with predefined "interfaces" between the modules.
Basic Layout of an APP and the APP Builder's IDE/Editor
You can also find a lot of tips and tricks for the APP Builder targeted to beginners in this article: APPs Building - Nifty Tips & Tricks for Beginners
As you have read up to now, JSON plays a central role in building APPs. Every APP itself consists of a series of JSON objects that will be interlinked. The following picture will give you a list of all the empty but essential top-level objects of an APP - do not worry about the content, you will learn how to fill these during the training!
While the above APP is empty, the following code snippet shows how an APP will look like with some meat to the bone in some of the top-level objects:
A powerful tool that will help and guide you through the process of building an APP is the IDE editor, which is now introduced to the APP builder. "IDE" stands for "Integrated Development Environment" and is a concept which supports you creating code for the respective target, in this case the JSON The following picture shows how the IDE would look like building an APP. Thereby, the core IDE elements you can see are the following:
- On the far left side of the screen you can see three little icons that stand for "Editor", "History", and "Settings".
- You can see the editor view in the picture below, which lets you edit your currently selected APP. The settings page allows you to change configurations like user access and visibility of the APP (we will cover this potentially in a future training or give you documentation about this).
- The history of your APP can come in quite handy. With every change of code, a new version is created and tracked. This lets you jump back to older versions in case a recent adjustment led to faulty configurations. So you do never loose the past status of your APP. Conveniently, green dots indicate "working" versions, so versions that had no failure included and therefore work as intended.
- The next thing on the left side is the structure bar of your current APP. There you can see an enlistment of all the top-level JSON objects, which are expandable in order to show you the single entry objects per top-level object. Furthermore, you can click on those entries to just view the code of the respective entry, rather than the whole APP code (which is called "RAW"). This increases the convenience of creating your APP and lets you gain more detailed access to single elements, rather than having to search through the whole code.
- Next up, in the middle of the picture is the actual editor, in which you can edit your APP.
- Last but not least, on the right side you can see the preview, which is updated live every time you change something in the APP's code. At the top right of the preview you can change the layout distribution between editor and preview.
After all this explanation about the APP builder itself, we would like to give you two nifty tricks that will heavily increase your convenience level in APP building.
Firstly, there is the possibility of adding entries to a top-level object of an APP by clicking the little plus sign next to the respective top-level object entry in the structure bar. It appears once you hover over the list and by clicking it, it adds an empty entry to the respective top-level object automatically. This relieves you of creating the respective JSON code yourself, and it always adds the entry in the correct place of the current APP.
Secondly, the preview of the APP builder allows for more convenient navigation inside the JSON APP code. You can at any point do a right click on an element in the preview and a dialogue opens, offering you three possibilities to navigate. The editor panel will then directly jump to the selected APP element's code.
We highly suggest using this functionality in the APPs training course! It will save you a lot of time searching for the correct element to view and edit!
Setup of the Training Course
To begin with this APPs training course is actually pretty simple. Please visit the designated OD instance (https://training.onedata.de/) and enter the APP builder. You can find the training's code (which is an APP itself) in the attachment of this article. Just download it, create a new APP in the APP builder, insert all of the code you've just downloaded into the editor, and you are ready to go!
What will not Be Covered in This APPs Course
After you have finished the APPs training course of this article, you will have learned a lot about creating your very own APP. But actually, this only scratches the surface of what APPs in ONE DATA can do!
The following is a short sneak-peek on a selection of other features that you can build into your APP:
- Custom Components/Elements: The APP builder does already support you with many different elements (mainly charts etc.) that you can use directly and out-of-the-box when you start building your APPs. There are however many other chart forms, which you might want to include.
To do exactly this, the APPs builder does support you with the functionality of including own chart types. The main task that you have to fulfill here is that you define how the data should be mapped to which data points of the chart.
The big benefit here is, that when you created one of your custom elements once, you can always use them in other APPs as well!
- Triggering Underlying Workflows in your APP: Up to now, the APPs that you have created with the info of the training course rely on static data, which is supported by the datasource that you connected to your APP. In most cases however, this datasource is not static by itself, as it is fueled by a workflow in ONE DATA that calculates and adapt its input data; the output of the workflow is then supported for the APP. So if this input data would change, also the output data for the APP might change.
As a solution to this, you can connect your APP to the underlying workflow and allow a triggering of the workflow directly. Doing so, the workflow will calculate "new" data, and the view of the APP will automatically be updated to the newly received and adapted data.