Appogram Fundamentals

In this document we will introduce Appogram fundamentals and key points for architecting an Appogram Appo. It is recommended to read “What is Appogram?” & “FAQ” before this document.

Appogram consist of UI elements and Data Elements. UI elements are Views, Forms, DataLists / ImageLists and DataGrids. Data elements are Profile, Settings Form, Login, Get, Call and Action. You can create lots of services with these elements combination.

View, Forms, DataLists, DataGrids, Actions

In a quick review you will create as many UI elements as you need. Then these UI elements will be linked to each other with Actions, Actions can link Views and forms and pass data between them, also Actions can do some other works like sending SMS, make a phone call and …. .DataLists are customized views for working with a list of items, for example you can use DataLists to create an inbox application. DataLists may show images as a list. With DataGrids you can show a table view of your data. Datalists supports infinite scrolling and data paging.

There are plenty of elements that you can use in Views and Forms, for example maps, location pickers, video and file downloaders and …..

Get, Call, Profile

In each view you can get your needed information from your server with Get, Get is a utility that will call a JSON web service. There is a special Get that we call it Profile, Profile is used just one time at the beginning of opening an Appo. You can use Profile data in all your UI elements. If you want to send any information to your server you should use Call, Calls can be used in submitting forms data or behind any Action. Call and Get data is accessible in their own View or Form but Profile data is global in all parts of your APPO.

Settings

You can show a form to your users and save that data as settings data. Settings are available in all your components and you can use it for user customization. Settings will store on your device and this is the only thing that we store on the device. Settings data are client side data and is not shared between users.

Login

If you want to secure your UI elements you can use Login, Login is a very simple and well-designed authentication form with lots of customization and security features. If you make any View or Form or …and mark as login required then users must login before opening them, after logging in you have access to those UI elements. Login will call a web service from your backend and you can return some data and also a JSON Web Token for more security. The returned Login data will be accessible globally in all your Appo’s UI elements.

Most of Appogram elements connects to web services, this integration is very simple and straight forward. Each element just needs very little settings to get data and show it, without any programming. To keep simplicity and eliminate complex setting you must create web services with Appogram standards. Web services returns JSON format. In reference documentations you can find proper format and structure suitable for each element.

After logging in to any Appo, the JSON Web Token (JWT) will be passed to web services in all HTTP/s server calls, so you can manage your security.

Get

Get is a function to fetch a JSON web service with a simple URL. You can put many Get functions on your views. Get web services must return a single not nested JSON object. Get functions are called before any other parts of the view. You can easily use returned data with a simple command: @{get.getId.alliceFieldId}

In Get you can change name of returned fields and use your allice name instead of JSON keys. Get data is just available in current view.

If you are using login, all your Get and … will contains your login JSON Web Token, so your server is responsible for validating the token. It is extremely recommended to use SSL protocol in all your web services.

Profile

Profile is a custom Get function that will invoked on entering Appo. Profile data will be available in all views. Profile data source is a simple JSON object as mentioned in Get function documentation. You can easily use returned data with a simple command: @{profile.alliceFieldId}

All security issues of Profile is same as Get function.

Call

Call is a function to post some data to a JSON web service. You can use any URL and post your data and get the returned JSON, The retuned JSON must be a simple single level object as Get functions. The post data is a list of key values that will create a simple JSON object for the web service. In Call you can define a Success and a Failure message that will create a toast message on your device. Call functions only can be used in Actions. After triggering an Action for example by a button then the Action will invoke the Call function and the returned values is available in the current view or could be used to setup Action return values that will be passed to the next view.

Login

Login is another simple web service call with authentication purpose. You can define a web service that will get a JSON object containing username and password and returns a JSON web token as the success authentication result. The JSON web token can contains simple not nested JSON object and you can access its values with @{login.keyId}. You can check if a user is authenticated with @{login.loggedin} and these values are available in all views. If authentication failed, web service must return http 401 error code. There is a LoginRequeired check box for all view types that you can use to restrict access only for logged in users. For security issues you should use SSL protocol in your web service.

Action

Actions are key linking and routing part of designing an Appo, You can use Actions in many components and views. Action is a routing function that can be triggers by buttons and many other controls for example map points click and …. .

Actions has three types of targets

View and forms and ..: these actions will route users to another view.

Quick Actions: these actions can make a phone call, open web browser, send SMS, etc. When you select a Quick Action you can set its parameters.

Refresh: This type of action will keep the current view and let you use return values of a Call function.

In routing actions you can pass a list of key-value data to the target view and use that data with this command: @{action.actionKeyId}. So each view has access to the Action of its predecessor view.

In Actions you can define Call function that the action must invoke before routing or any other function. You can use many Call functions in one action.

Development concepts:

Versioning

Each Appo has a simple lifecycle, first you create an Appo and add a new version to it. this version is just for development & test and is just available by scanning the QR code. After passing tests and preparing for release you can deploy an Appo and after that you cannot change it any more but you can create a forked version and develop it until its release time then deploy this forked version. The new deployed version will replaced the old one.

Geo Points

You can add some GPS points to an Appo, then if your Appo is marked as public, users can search for you with nearby search in Appogram application.

Designer Variables

While developing an Appo you can use some non-runtime variables for enhancing development tasks. For example you can use ${myserverURL} as a variable and change it anytime. These variables are not run-time and are just for development and will be replaced by values at test / deploy time. This model of addressing web services will help you for exporting/importing Appo from one account to another account.

Public / Private Appos

Public Appos can be searched by Appogram users but private Appos are hidden in search results but both of them are available with URL and QR scan. If you need more confidence you should use login in your Appo.

Testing an Appo

You should test your Appo before deploying it as a released version. Testing an Appo is as easy as scanning a QR code with your Appogram application. You can get some logs of your Appo errors in Appogram application menu.

Deploying an Appo

After testing an Appo you can deploy it. When a version deployed it will be updated on all devices. You can disable an Appo after deploying.

Service Designer and Fake Data

In Appogram studio you can define all your web services in Service designer and then create some fake data and conditions for them, these fake data could be used in testing a test version of your Appo without any need to be connected to real web services. This approach of service modeling will help you create your Appo independently of your backend team.

Service designer has many templates for better compatibility with data component so you just select a chart type then you will see the JSON format of the data.