Notice
Pay attention to app.js script should be included immediately after libraries because of its concept.
In FrameworkJS, there is no need to write code separately for Android, iOS, and web platforms. The core of the FrameworkJS is built using JavaScript, HTML, and CSS languages, which can be easily applied to Android and iOS platforms. Additionally, by uploading the files to CloadIO, application will be able to run on the web.
FrameworkJS includes an index.html file where all the HTML code is placed. In this file, you simply need to add the HTML tags. The structure section of the index file is as follows:
viewport meta tag to control layout and the next one is for declaring character encodings in HTML.
All HTML code goes inside the body. for example, adding a page and etc.
The script tags are used at the bottom of the page, to include all related scripts. We also write these parts in order. First, the JS libraries are written, and then each js page file that we have written. These sections are separated by some comments.
Pay attention to app.js script should be included immediately after libraries because of its concept.
performing an example to see the basic structure of index.html and the rules that exist on this page.
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<title>Your FrameworkJS Application</title>
<link rel="stylesheet" type="text/css" href="lib/framework.css">
<!-- add your modules styles here -->
<!-- <link rel="stylesheet" type="text/css" href="modules/"> -->
<link rel="stylesheet" type="text/css" href="modules/ui/css/style.css">
<!-- add your page styles here -->
<!-- <link rel="stylesheet" type="text/css" href="css/"> -->
<link rel="stylesheet" type="text/css" href="css/login.css">
<link rel="stylesheet" type="text/css" href="css/home.css">
</head>
<body>
<div class="page login">
<h1>Login Page</h1>
<p>Welcome to FrameworkJS</p>
</div>
<div class="page home">
<h1>Hello world!</h1>
<p>FrameworkJS is a powerful JavaScript framework for building mobile and web applications.</p>
</div>
</body>
<script src="lib/cloadio.min.js"></script>
<script src="lib/jquery-2.2.0.min.js"></script>
<script src="lib/framework-a.min.js"></script>
<script src="lib/framework-b.min.js"></script>
<script src="js/app.js"></script>
<!-- add your page scripts here -->
<!-- <script src="js/"></script> -->
<script src="js/login.js"></script>
<script src="js/home.js"></script>
</html>Note that maintaining harmony between CSS linking, HTML codes, and JS linking is crucial for every page. The order in which they are linked is important for easy understanding. For instance, if the HTML code for the home page is the fifth page, it should also be the fifth in CSS and JS linking.
In FrameworkJS, there is an app.js file that contains configurations, object definitions, event handling, and other important functionalities. When building the project for the first time, it is necessary to make some important basic settings. Additionally, as the project progresses, further modifications to this file will be required.
//------------------ config ------------------------------
app.name = 'framework';
// domain and ssl configurations to access files through the http protocol
app.http = {
domain: 'framework.cloadio.com',
ssl: false
};
app.cloadio = {
// you can enable or disable all functions related to cloadio.
// if you don't need back end disable it.
enable: true,
// use tls connection
secure: true,
// you can execute code on all devices remotely.
allowRemoteExecution: true,
// public users info path
puip: '/users'
};
app.install = {
// track app installs
enable: true,
// install details path
path: '/installs'
};
app.version = {
// control min version
// if minimum version be greater than the current version update page will be shown
// so app must have update page
control: true,
// current version
current: 202301040909,
// min version path
mvp: '/update/minVersion',
};
app.update = {
// auto update
autoUpdate: true,
// auto update url path
auup: '/update/url'
};
// default localization value
// all modules will use this configuration
app.localization = {
language: {
direction: 'ltr',
code: 'enUs'
},
dateTime: {
// note: use space character instead of underscore in time zone
calendar: 'gregorian'
}
};
// fallback page name
app.auth.fpn = 'login';
// use notification service
app.notification = {
enable: true
};
// appearance attributes
app.appearance = {
statusBar: 'light',
backgroundColor: '#000000'
};
// framework uses this feature to increase product quality and performance
app.statistic = {
// send statistic data to the framework lab.
enable: true
};
//------------------ end of config -----------------------
// ----------------- events ------------------------------
// on document ready event
// called when html dom content loaded
app.onDocumentReady = function () {
// body...
homePage.show();
};
// on connection open event
app.onOpened = function () {
// body...
};
// on connection close event
app.onClosed = function () {
// body...
};
// on connection open for first time event
app.onConnected = function (error, value) {
// body...
};
// on sync event
// called when time synced with cloadio
app.onSynced = function () {
// body...
// example: app.now()
};
// called when user authenticated
app.auth.onCompleted = function () {
// body...
};
// on shown
app.onShown = function (url) {
// body...
};
// before page changed
app.beforePageChanged = function (page) {
// body...
};
// after page changed
app.afterPageChanged = function (page) {
// body...
};
// on back button event just in android
app.control.onBack = function () {
// body...
Android.exit();
};
// on location changed event
app.location.onChanged = function (longitude, latitude, altitude, accuracy) {
// body...
};
// on notification received event
app.notification.onReceived = function (data) {
// body...
};
// on sms received event
app.auth.sms.onReceived = function (text, sender) {
// body...
};
// on update started
app.update.onStarted = function () {
// body...
};
// on update progress changed
app.update.onProgressChanged = function (percentage) {
// body...
};
// on update started
app.update.onCompleted = function () {
// body...
};
// on QR Code data received
app.qrCode.onReceived = function (data) {
// body...
};
// on scan result for a device {macAddress, rssi, name, services} received signal strength indicator
app.bluetooth.scan.onResult = function (error, device) {
// body...
};
// on scan stopped
app.bluetooth.scan.onStopped = function (error) {
// body...
};
// on connected to a device
app.bluetooth.onConnected = function (paths) {
// body...
};
// on disconnected from a device
app.bluetooth.onDisconnected = function () {
// body...
};
// on received data
app.bluetooth.onReceived = function (data) {
// body...
};
// orientation sensor
app.sensors.orientation.onStarted = function () {
// body...
};
// on disconnected from orientation sensor
app.sensors.orientation.onStopped = function (error) {
// body...
};
// on orientation changed
app.sensors.orientation.onChanged = function (azimuth) { // in degrees [0, 359.9]
// body...
};
// on std out event
// called when data is written to console
app.debug.onSTDOut = function (data) {
// body...
};
// ----------------- end of events -----------------------The app methods are fundamental methods in FrameworkJS that require configuration. This section focuses on creating a general configuration for the application, and we will provide detailed explanations. For additional information, please refer to the configuration section.
app.name = 'myApp';When an account is created in CloadIO, the domain name is created according app name, which must be set here. See more information in the configuration section.
In the app.http section, the domain, and SSL should be applied as follows.
// domain and ssl configurations to access files through the http protocol
app.http = {
domain: 'accountName .cloadio.com',
ssl: false
};The first property is related to back-end codes. If you don't need the back-end, set the "enable" value to false.
The secure part is using a TLS connection. If you need to keep a secure connection, you can set it to true.
You can execute code on all devices remotely through CloadIO functions. To aim for this purpose you must set true for the "allowRemoteExecution" property. If you don't need to have an "allowRemoteExecution", you can set it to false.
The puip is the path of saving users' data in CloadIO which By default, is set to '/clients'. Therefore according to project needs, it can be changed. See more detailed information in the configuration section.app.cloadio = {
// you can enable or disable all functions related to cloadio.
// if you don't need back end disable it.
enable: true,
// use tls connection
secure: false,
// you can execute code on all devices remotely.
allowRemoteExecution: true,
// public users info path
puip: '/clients'
};When user installs the application first, if you set the "enable" value to true, user's information such as device token, time zone, etc. is stored with a unique ID. You can set it to false if you don't need to do this section.
The "path" is to save users' information path and it is '/installs' by default. See more detailed information in the configuration section.
app.install = {
// track app installs
enable: true,
// install details path
path: '/installs'
};For using the app version property, your app must have update page.
If you want to activate the min version in the project, you must set true the "control" value.
You can change the current version value at the "current" property. The current version value consists of numbers and it has a simple syntax. It includes year, month, day, hour, and minutes. These digits should be 12 characters.
Note that if you don't want the update page to be displayed, the current version must be greater than the min version.
The mvp is the path of saving the min version in CloadIO which by default, is set to '/update/minVersion'. Therefore, it can be changed according to project's needs. See more detailed information in the configuration section.
app.version = {
// control min version
// if minimum version be greater than the current version update page will be shown
// so app must have update page
control: false,
// current version
current: 202104031943,
// min version path
mvp: '/update/minVersion',
};If you want to use this, you can set "autoUpdate" to true else you can set it to false.
The auup is the path of saving auto-update in CloadIO which by default, is set to '/update/url'. Therefore, it can be changed according to project's needs. See more detailed information in the configuration section.
app.update = {
// auto update
autoUpdate: true,
// auto update url path
auup: '/update/url'
};If the used language is left to right, the "direction" is setting to ltr, like the English language, else it should be set to rtl, like the Arabic language. Every language has an abbreviation word, So the value of the code property should be the abbreviation word of the used language.
The "calendar" property is for setting the calendar type. It is set on the "gregorian" by default. It is clear that you can change it according to language of the project.
The last section determines the local time. Here, you should write the time difference between the application and Greenwich time. See more detailed information in the configuration section.
app.localization = {
language: {
direction: 'ltr',
code: 'enUs'
},
calendar: 'gregorian',
timeZone: '00:00'
};app.auth.fpn = 'login';app.notification = {
enable: true
};For the background color, you should use a HEX code, for example, #000000 is setting the background status to black.
For setting the color of the text in the status bar you can set light or dark attributes. See more detailed information in the configuration section.
app.appearance = {
statusBar: 'light',
backgroundColor: '#000000'
};If you set the enable to true it will send statistic data to framework lab otherwise not be sent. See more detailed information in the configuration section.
app.statistic = {
// send statistic data to framework lab.
enable: true
};This section will provide a general configuration of the application objects. We will explain this in detail and you can define your related desired global objects.
When caching the data in the application, we should first define a global object variable that binds data to FrameworkJS local. For example, by defining app.local, data can be saved in a local object like pp.local.myData.
To create global functions, we can define app.functions, and bind any desired function to it. For example, if we want to define a generate key function, first of all we can define app.functions here, and then simply create our function under it as app.functions.generateKey.
Because of running the app.js at first in FrameworkJS core, we define global objects here. It means when you need a variable in the whole of the project (on more than one page for example), it is optimized to define the variable in this section and use it on other pages. So if you want to use a local variable or just use it on one page, it is better to define it on that specific page.
// --------------- define app objects --------------------
app.functions = {};
app.local = {};
// ------------ end of define app objects ----------------
//--------------- define global functions ----------------
// generate a random key
app.functions.generateKey = function () {
return Date.now().toString(36) + '-' + Math.floor(Math.random() * 1000000).toString(36);
};
//--------------- end of define global functions ----------------Events are very important and required for some information and initialization in the application. In this section will be created a general configuration of the application events. So we will explain this in detail.
For example, you can write homePage.show() to show the home, after running the app. See more detailed information in the Document Object section.
// on document ready event
// called when html dom content loaded
app.onDocumentReady = function () {
homePage.show();
};// on connection open event
app.onOpened = function () {
alert('The internet is connected.');
};// on connection close event
app.onClosed = function () {
alert('The connection was lost.');
};app.onConnected: Called when a new connection has been established. In this event, user and time are not synced yet. See more detailed information in the Connection section.
| Parameters | Type | Description |
|---|---|---|
| error | String | The callback error of checking authorization. |
| credential | String | The string of credentials on checking authorization. |
// on connection open for first time event
app.onConnected = function (error, credential) {
// check credential
if (localStorage['authentication'] === 'completed') {
if (error)
console.error('getting credential failed', error);
if (!credential)
app.auth.clear();
}
};// on sync event
// called when time synced with cloadio
app.onSynced = function () {
ref.child('model').get(function (error, value) {
if (error)
console.error('get value from cloadio was failed', error);
else {
// define local app variable
if (!app.local.value)
app.local.value = {};
app.local.value = value;
}
});
};// called when user object synced with cloadio
app.auth.onCompleted = function () {
if (app.auth.user.name)
homePage.show();
};app.onShown: When an external link or URL is clicked, to handle and achieve that specific page in the app, this event will be called. See more information in the Navigation section.
| Parameters | Type | Description |
|---|---|---|
| url | String | The path of the link that was clicked and the related page should be shown. |
// on shown
app.onShown = function (url) {
if (url)
homepage.show(url);
};app.onHidden: When The app is in the background, to handle the specific operation in the background, this event will be called. See more information in the Navigation section.
app.onHidden = function () {
if (app.local.video.wasPlaying = app.local.video.isPlaying)
app.functions.video.stop();
};
app.beforePageChanged: Before changing any page, you can write some codes and actions, so that these codes apply to all the app pages. For example, we can be getting data from CloadIO or change some CSS styles, ...
See more information in the Navigation section.
| Parameters | Type | Description |
|---|---|---|
| page | Object | Some specifications of the current page |
app.beforePageChanged = function (page) {
$('.page.' + page.name + '').css('background-color', '#000000');
};
app.afterPageChanged: After changing any page, you can write some codes and actions, so that these codes apply to all the app pages. For example, we can be getting data from CloadIO or change some CSS styles, ...
See more information in the Navigation section.
| Parameters | Type | Description |
|---|---|---|
| page | Object | Some specifications of the current page |
| args | Array | arguments of current page. |
app.afterPageChanged = function (page, args) {
$('.page.' + page.name + '').css('color', '#ffffff');
};// on back button event just in android
app.control.onBack = function () {
Android.exit();
};app.location.onChanged: When user location changes, according to project requirements handle it in this event. See more information in the Location section.
| Parameters | Type | Description |
|---|---|---|
| longitude | String | Include the geographical coordinates related to longitude. |
| latitude | String | Include the geographical coordinates related to latitude. |
| altitude | String | Include the geographical coordinates related to altitude. |
| accuracy | String | Include geographical accuracy. |
// on location changed event
app.location.onChanged = function (longitude, latitude, altitude, accuracy) {
if (!longitude)
alert('Getting user location failed.');
};app.notification.onReceived: Sometimes the app needs to receive and handle the notification, so this event should be called when a notification (FCM, APNS) has been received. See more information in the Notification section.
| Parameters | Type | Description |
|---|---|---|
| data | Object | Contains the whole information of the notification message, such as the body, data, etc. |
// on notification received event
app.notification.onReceived = function (data) {
if (data)
homePage.show(data);
};app.auth.sms.onReceived: When an SMS message has been received in the application, you can manage SMS actions here. See more information in the Authentication section.
| Parameters | Type | Description |
|---|---|---|
| text | String | Contain of the message text. |
| sender | String | Contain the sender of short message. |
// on sms received event
app.auth.sms.onReceived = function (text, sender) {
// body
};// on update started
app.update.onStarted = function () {
// body...
};For example, you can create an update page for handling update progress. Here as you can see, we show you the small code for handling the update progress bar. See more information in the Update section.
| Parameters | Type | Description |
|---|---|---|
| percentage | Number | The value of progress percentages. |
// on update progress changed
app.update.onProgressChanged = function (percentage) {
if (app.page.name === 'update')
$('.page.update > .progress > div').css('width', percentage + '%');
};// on update started
app.update.onCompleted = function () {
if (app.page.name === 'update')
alert('Your update is completed!');
};app.qrCode.start() code. See more information in the QR Code section.
This is an example of QR code management that we write in app.js
// on QR Code data received
app.qrCode.onReceived = function (data) {
if (data)
homePage.show();
};This code is an example of when we need to call the QR code and we can write it on different pages.
app.security.ensurePermissions({android: {0: 'android.permission.CAMERA'}}, function (granted) {
if (granted)
app.qrCode.start();
else
app.controls.box('alert', null, 'Grant access to a camera to scan the barcode.', 'left');
});
In the CSS folder of FrameworkJS, there is a default CSS file, that we add the common and general CSS styles. So we call it common.css.
Also for each created page in index.html, need to create a CSS file, So that every created CSS file contains the separate CSS codes of that page.
For example, we have a page in the index file, and the name is 'home', so we will have a CSS file with this name in the CSS folder.
Every CSS file in the CSS folder should be included as a link in the index.html file.
In FrameworkJS, it is a good practice to have a separate JS file for each page.
In the JS folder of FrameworkJS, we have a default JS file, which we called app.js.
When you create a new page in the index file, you should also create a new JS file with the same name as the page. For example, if you have a page called 'home', you should create a new file called 'home.js' in the js folder.
Every JS file in the JS folder should be included as a script in the index.html file like CSS files.
var homePage = new Page('home', function () {
// after page shown
}, function () {
// before page shown
}, function () {
// after page closed
});For more information about the Page, visit the Page API section.
This folder is defined for creating multilingual applications. In this folder, there are several files different target languages.
To define the language of the app, we need to add codes everywhere they are needed. We should add the text of the project as a key: value intolang file.
For example, if we have an English app, we must add the enUs.js file inside the lang folder.
In the app.js file at the onDocumentReady event, we should add the following codes in order to load and use the multilingual apps.
// load language
var script = document.createElement('script');
script.onload = function () {
// apply language
$('body lang').each(function (i, o) {
var jSelf = $(o);
jSelf.prop('outerHTML', app.lang[jSelf.html()]);
});
app.local.langLoaded = true;
if (app.local.onLangLoaded)
app.local.onLangLoaded();
var next = function () {
ref.getCredential(function (error, value) {
if (!app.page) {
if (value)
homePage.show();
else
signInPage.show();
}
});
};
if (app.local.synced)
next();
else
app.local.onSyncCompleted.push(next);
};
script.src = 'lang/' + app.localization.language.code + '.js';
document.body.appendChild(script);There is two option to support multilingualism in the application. First, in the HTML, we should use the following codes:
<div class="title"><lang>title
So the result we can get the title text from the language file. Another way to use multilingual is the JS file. IntoJS files, we should use app.local.lang and then add the key of the text.
The following we have an example for this purpose:
pay attention to app.local.lang is defined in the app.js file.
$('.title').html(app.local.lang.title);In the lib folder, there are some default libraries related to FrameworkJS and CloadIO. These files should not be changed. You can be added new libraries that you want to use, whether CSS or JS, in this folder.
You can put the images and icons used with any extension required by the project in the img folder. Then call it from this path wherever you want to display the image.
You can put the used fonts of the project here, and call your fonts in the common.css file, in order to use them.
In FrameworkJS, modules have been created in order to facilitate the use of FrameworkJS, optimize, and reduce development time. Some of them include the form builder module, table builder, analytics, etc. We introduce some of the most popular and widely used in the Modules section. Also, you can use your own customization modules.
To use a module in a project, simply place it in the "module" folder.
| Title | Description | Download |
|---|---|---|
| Model | This is the basic model of the project. The model contains the structural properties and fields of the project. Data is stored as JSON and synchronized in real time for every connected client. | Download Model Module |
| Form | The form module is used to optimize and reduce the development time of the forms. | Download Form Module |
| Table | The Table module is used to optimize and reduce the development time of the Tables. It also is for rendering lists or card lists and tables are used. | Download Table Module |
| UI | This module is used to handle HTML tag events and effects, like buttons, inputs, text areas, etc. | Download UI Module |
| Chat | This module is used to increase optimization and reduce chat implementation time. | Download Chat Module |
| Controls | In this module, there are some important and widely used codes, that make the coding shorter, easier and faster. We have several types of them in the control module. | Download Controls Module |