How to contribute?

Take a look at the software overview, have an idea about how it works and start contributing.

You can also go directly to the public repository page and start looking at the code

If you already know the software, jump the the development section

Software Overview

ROSWeb is a web application developed using HTML, CSS and JavaScript. It is a supervisory system that groups widgets previous developed and new widgets created to improve the user experience when interacting with ROS through a Web Browser.

Its architecture was developed from the scratch, so no framework was used to create the project.

To automatize some development tasks, it was used GulpJS, which is a NPM package. It's not a problem if you are not acquainted with gulp or NPM. They must be configured before starting the development, but you won't need to change their settings, unless your objective is to improve the development workflow.

About the system

All ROSWeb supervisory system behavior and functionalities were coded in TypeScript and compiled by a gulp task. Those files are inside the /src folder, which is described below:

TypeScript structure

TypeScript code is divided in the following folders:

  • classmodel - Parent classes to be inherited
  • events - Classes that handle all events in the system. They are instantiated just once in the main.ts file
  • helpers - Methods that can be useful for other classes
  • interface - Interfaces to be used as model by classes
  • model - Classes that represents the objects in the screen
  • super - These classes are instantiated just once as global variables. General purpose
  • types - This folder stores types that are used by other classes. These types are used in order to save code and make it easier to maintain
  • typings - Store .d.ts files. Used by TypeScript compiler
Templates

The dynamic content is rendered by Handlebars.js. Template files are stored at /src/hbs. They are interpreted by a gulp task and compressed into a single javascript file, that is used by the application.

JavaScript Libraries

All JavaScript libraries are found at /src/js folder. The libraries used by the core of the application must have a .d.ts file related, to be interpreted by a TypeScript compiler. These libraries are:

  • Handlebars
  • jQuery
  • Roslib

Other libraries used by widgets, written in JavaScript, or another JavaScript library, but not directly by the application (which is in TypeScript), are:

  • EventEmitter2 - used by Roslib
  • MJpegCanvas - used by Camera Viewer Widget
  • Ros3D - used by ROS 3D Viewer Widget

If you are developing a new widget that depends on a third library, this is the correct place to put the necessary files.

Cascading Style Sheet (CSS)

For writting the styles, it was chosen SASS extension. The rules are in /src/sass in separated files, in order to organize them. A gulp task is in charge to compile them and compress into a single file. The file /src/sass/main.scss imports the other files.

Images

All the images are inside the /src/img folder. After compiling the code, a gulp task copy all images to the /dist folder, where the application runs. You just need to place the files here and restart the gulp task to copy it.

About widgets

Widgets are the most important part of the system. ROSWeb itself only hosts a lot of widgets that can be useful for your ROS application.

Widget Structure

All existing widgets are placed in /src/widgets. They are basically generated from 3 files:

  • Template file - index.hbs
  • Stylesheet file - main.scss
  • JavaScript or TypeScript file - main.js/main.ts

It is possible to create new files to organize your widget or even to use webworkers, like the LaserScanner Viewer Widget does. Just make sure those files will be used by the main.js file.

Creating new Widgets

We have a tutorial for creating new widgets, you can see it here.

It is always interesting to take a look at the existing widgets to see how things work.

After creating a new widget, you need to add it to the method _initWorkspace() at the file /src/ts/model/workspace.ts

Start developing

Configuring the environment

Basically, you need to install the dependencies using NPM commands and install Gulp to run the necessary task during the development.

All the necessary steps are described in this contributing.md file, in the project repository.

Did you have any doubt or suggestion reading this page?

This page is generated by a GitHub repository, you can submit changes here or even create an Issue and we'll fix it as soon as possible!

ROSWeb Page Repository