Lets get started!
A new documentation site is under construction. It will feature the new v2.0 API. You can check it out now but beware, it is still under construction.
New Documentation PageThis documentation has been written to help developers get into grips with the whole concept and approach to web-application development in NitroJS. Our API documentation is meant to provide detailed (yet easy to understand) information about a given feature or method.
By using this documentation, you should be able to learn and utilise NitroJS and its components. Please remember, this documentation isnt just for those starting out in web-application development, it is also for those legendary developers out there looking for a reference.
We also have an option for those who learn better while working; Head over to our kickstartNew! page, to get started with our mini step-by-step NitroJS development guide!
As we continue to develop and expand the capabilities of NitroJS and its components, we may have to break older API in order to ensure NitroJS remains a secure platform. This can be annoying if you have a large code base, therefore, we have created an API versioning system which allows you to force the old API even after a modular API change. We do NOT recommend this as it may render your application unsafe in the future.
The default API-blocks (aka block modules) will not be changed. We will only ever add to the Block modules list.
Every NitroJS application has to start from a manifest file called the json-nitro-10 (JNX). Manifests in NitroJS are written with the JSON syntax (javascript object notation). They provide the NitrixCore with information about the web-app it is about to run. Manifest files contains things like name, version, runtime information, icons etc. Web-streamed application also require a manifest file. All NitroJS application manifests must have the '.jnx' extension.
{
"manifest_version":3,
"application":{
"name":"my Application",
"version": "2.0.1.6",
"homepage":"*/index.html",
"icon":"*/star.ico",
"permissions":["fs","app"]
},
"runtime":{
"version":"1.0.0.6",
"gpu_acceleration":false,
"api":"v1.2"
}
}
Asterisks are used to get the current directory of the manifest. Manifest version is required in order for NitroJS to work correctly. Here is what each version allows:
| Version | Action |
|---|---|
| 1 | Retreives Application Name, Version and Homepage from the manifest |
| 2 | Retreives Application Name, Version, Homepage and Icon path from the manifest |
| 3 | Retreives Application Name, Version, Homepage, Icon path, gpu acceleration and Runtime Version from the manifest |
In order for your application to access system level information and capabilities, you will need to declare something called permissions. Permissions give you extended features and access to parts of the system, enabling you to utilize the whole environment. In order to run block Modules, you will need to request permission to use them from NitroJS, in turn preventing unauthorised access. Although permissions is a block module, it does not have to be declared itself. Setting permission is easy, permissions are defined in the manifest under the application object properties:
{
"manifest_version":3,
"application":{
"name":"my Application",
"version": "2.0.1.6",
"homepage":"*/index.html",
"icon":"*/star.ico",
"permissions":["fs","app"]
},
"runtime":{
"version":"1.0.0.6",
"gpu_acceleration":false,
"api":"v1.2"
}
}
To remove permissions:
permission.remove("fs"); //access to fs will now be denied
permission.remove("storage"); //access to storage now denied
Getting started with NitroJS just as easy as making a basic HTML webpage. However, if you want to add awesome functionalities to your application, you will need to set and initialise NitrixCore. This is an example of how you would set things up:
var Nitro = new NitroCore(); //sets new object to be used
Nitro.import("jquery"); //prepares library to be imported when needed
Nitro.addPermission("app"); //sets permission to use "app" block module
var appName = app.get("applicationName"); //gets the application name
var username = app.get("currentUser"); //gets name of user currently logged on
alert("Hello " + username + ", you are currently using " + appName);
The NitrixCore is the main engine behind all of the content computation. It works together with NitroJS and the NitroCore to provide user-level access and information, as well as entry-level communication with the system. In other words, the NitrixCore provides native-feel and speed while the NitroCore and NitroJS prepares and formats the web documents to be processed by the NitrixCore :)
The NitrixCore (with the help of the NitroJS) gives you the ability to stream your web-application directly to your client-side. This allows you to push updates almost instantly; as soon as an update is made, your users will automatically be running the latest version all without having to restart the NitroJS environment. Note: The downside to this is that your users will be prompted to grant access to the permissions you define every-time your app runs.
This block module allows you to access application-level information, while changing the environment's properties:
app.get('applicationName'); //returns the application name
app.get('applicationVersion'); //returns the application version
app.get('runtimeVersion'); //returns the runtime version
app.get('Name'); //returns the text displayed in the titlebar
app.get('currentUser'); //returns the name of user currently logged in
app.all(); //returns an object of all the information as properties
Using this block Module, you can directly control the environmnet and runtime of your application:
app.close(); //asynchronously closes the application
app.restart(); //quick-restarts the application
app.maximize(); //maximizes the window
app.minimize(); //minimizes the window to taskbar
app.normal(); //sets the windows size to normal
app.showBorder(boolean); //sets the visibility of the borders
app.setpos(x,y); //asynchronously sets the position of the window
app.setsize(width,height); //asynchronously sets the size of the window
app.getpos(); //asynchronously returns xy property values
app.getsize(); //asynchronously returns width and height property values
app.setminsize(side,value); //choose to set the minimum width or height
This block module allows you to retrieve access information for other block modules. 'debug' and 'permissions' are not bound by permission; they do not need to be defined. Once the permission of a block module has been added, that module can be used for the rest of the webapp's running lifetime (unless permission is removed) As of API v1.8 you can no longer dynamically request access via JS code. All permissions must now be requested in the manifest file before the application runs.
permission.remove('block-module-name');
/*revokes all access to specified block module
(user will be prompted to regrant access if permission is re-added) */
permission.list(); //returns a string of permissions delimited by a comma
To see how to define permissions in the manifest, visit the manifest section.
Using the 'system' block module, we are able to directly communicate with the host shell, here is how you would run a program with administrative rights:
var options = {useShell:"true", app:"applicationpath.exe", asAdmin:"true"};
system.run(options);
//NitroJS will formulate the options and pass it to the NitrixCore which then communicates with the appropriate service, passing the options as parameters.
We can also use the 'system' block module to get system-level paths and directories on the user's machine:
system.path("appdata");
system.path("mydocuments");
system.path("mycomputer");
system.path("desktop");
system.path("mymusic");
system.path("mypictures");
system.path("myvideos");
system.path("root"); //returns the directory where the operating system is installed
system.path("launch"); //returns the folder where NitroJS is installed
Just like we were able to run other external application from 'run', we are able to use 'system' to execute scripts or files:
system.execute("scriptpath.bat"); //runs the script from command line/terminal
system.execute("application-with-ext"); //runs the application from command line/terminal
The 'net' block module allows you to natively upload, download, ping and check computer connectivity:
var myAppdata = system.path("appdata");
net.secureDownloadFile("http://example.com/file.txt", myAppdata, "username", "password", completedCallback, progressChangeCallack); //with login
net.downloadFile("http://example.com/file.txt", myAppdata, completedCallback, progressChangeCallack); //without login
net.uploadFile(myAppdata+"/file.txt", "http://example.com/file1.txt", "username", "password"); //with login
net.uploadFile(myAppdata+"/file.txt", "http://example.com/file1.txt"); //without login
net.ping("http://google.com"); //pings the website, returns availability as boolean
net.available(); //returns true if computer is connected to the internet
net.uploadFileFTP(myAppdata+"/file.txt", "http://example.com/file1.txt", "username", "password"); //with login
net.uploadFileFTP(myAppdata+"/file.txt", "http://example.com/file1.txt"); //without login
The 'fs' block module allows you to have filesystem-level access and control. It enables you to quickly and asynchronously ammend files on the system.
var filepath = system.path("desktop") +"/file.txt";
var newpath = system.path("mydocuments") + "/file.txt";
fs.createFile(filePath); //creates the file
var theContent = 'hello ';
fs.writeFile(filePath,theContent,false); //sets contents of the file to 'hello', overwritting old content
console.write(theContent);
fs.writeFile(filePath,'world',true); //adds 'world' to existing content in file
var finalContent = fs.readFile(filePath); //reads the file
console.write(finalContent);
fs.deleteFile(filePath); //deletes the file
fs.checkFile(filePath); //checks if file still exists
fs.moveFile(filePath, newpath); //moves the file
fs.renameFile(filePath, "file2.txt"); //changes the name of the file to 'file2.txt'
fs.moveFolder(oldLocation, newLocation); //moves folder from one directory to another
fs.renameFolder(oldLocationAndName, newName); //changes the name of the folder
fs.createFolder(folderNameAndPath); //creates a new folder
The 'storage' block module allows you to temporarily store information without having to write to disk. All data pushed to be stored is converted into an object for storage. As no data is written to disk, all data is lost when the app shuts down.
storage.store("myname", "bob"); //temporarily stores the word "bob" into storage compartment named "myname"
storage.fetch("myname"); //returns 'bob'
Creating and maintaining an app is hard work, specially if your users are running into errors which they cant understand and you cant see. So we have enforced webapp error logs. From API v1.2, every webapp will have an error log enabled by default. In order to access this log, you can use the debug block module. The debug block module does not need to be defined in permissions. Having this great feature allows developers to automatically send themselves the error log if their users are running into errors.
debug.getErrorList(); //returns a string-list of every error encountered by your webapp
debug.logError('errorTitle','error description'); //Logs an error retrievable
When the NitroJS runtime first runs, it requires information about the web-app it will be loading in order to make the whole experience fast, secure and fluid. It gets this information from the manifest file of the web-app. In order to retreive the information, you will need to either call the 'StartX' function from the NitroJS helper or manually load the file yourself.
//easy way:
StartX();
//long way:
var Nitro = new NitroCore(); //sets new object to be used
Nitro.addPermission("fs"); //sets permission to use "fs" block module to access the manifest file
var jsonContent = fs.readFile('manifest.json');
var load = new loader(); //creates a new NitroManifest loader
load.manifest(jsonContent); //loads the manifest
This block module allows you to request and retrieve access information for other block modules. 'debug' and 'permissions' are not bound by permission; they do not need to be defined. Once the permission of a block module has been added, that module can be used for the rest of the webapp's running lifetime (unless permission is removed)
permission.add('block-module-name'); //defines permission request to use block module
permission.remove('block-module-name'); /*revokes all access to specified
block module (user will be prompted to regrant access if permission is re-added) */
permission.list(); //returns a string of permissions delimited by a comma
permission.addList('block-module-name', 'block-module-name2', 'block-module-name3')
//asynchronously defines the specified permissions