JWebDesktop Documentation

Only prerequisite JWebDesktop has is, every platform running JWebDesktop (or applications packaged with JWebDesktop) must have Java 1.6 or above installed. The web application you develope and package with JWebDesktop too should be compiled with 1.6 target.

1. OS support

JWebDesktop is based on swing/swt and theoretically supports all 3 major platforms (Windows, Linux and OSX/Mac) - both 32 bit and 64 bit. You need not do any special setup, JWebDesktop binary automatically picks up OS information and initializes GUI according to that.

Having said that, I have tested it only on Windows and Linux. I do not have access to Mac machine, so I won't be able to either test or fix any Mac specific bug. If you have tested it on Mac or ready to fix any bug, you are welcome to contribute your code into the project. You can get the project's Github source link in overview section of this site.

2. Browser support

JWebDesktop uses system default browser as embedded browser. That should mean IE for windows, FF for Linux and Safari for Mac - unless user have changed the preference explicitely(I personally use chrome in windows). Again no special setup is required. You have a option to use XULRunner (i.e. FF) as internal browser in all platforms by bundling a xulrunner instance along with your app. Please see customization section below to find out how to do this.

Follow instruction below to install JWebDesktop in your machine and bundle your web app inside it.

1. Download latest JWebDesktop release. Unzip it in somewhere in your hard disk. It will create a folder like [place where you unzipped]/jwebdesktop. From now on, we will mention this location as [install_dir]
2. Go to [install_dir]/bin and invoke executable for your platform. The application should start and you should be able to see application widow with a succes message. Congratulation! JWebDesktop is ready for your use.
3. At this point, you should start developing your web application (if you haven't done so already). The web application is standard java application, however you need to take care of following :
   Note

   1.Must be compiled with Java 1.6 target (or below)
   
   2.JSP 2.1 and Servlet 2.5 version is supported (Jetty 6.1.26)
   
   3.Your web application must contain a default startup page (index.jsp or index.html etc) which must be placed at same level of WEB-INF (i.e. invoking http://localhost:port/ should invoke this page)
   
   4.You should not assume or use any server port number in your code. JWebDesktop by default start internal jetty at port 8080, but if this port is occupied for some reason, it will scan next 100 ports to find out a available one.
   
   5.Although JWebDesktop will process normal JSP files, it's a good idea to precompile them into servlet. This will speed up your application start up and also prevent clients from seeing your JSP code. Instructions are given here
   Lets call this web application MyApp.
4. Go to [install_dir]/jwebdesktop/config/embedded-server/webapps and put contents of your MyApp application there (delete existing default application contents that comes bundled with JWebDesktop binary). If you are extracting a war file, be careful not to create a "MyApp" folder inside webapps directory. All your resources (WEB-INF, index.jsp etc) should be directly under webapps.
5. Start the JWebDesktop application. Opened application should now show your applications start page.
6. Once you test your application working properly with JWebDesktop, it's time to do some branding and customization. See next sections for details.

In this section, you will change different poperty files and icons/images to add your branding information. To start with branding, you should have following items ready :

1. splash.gif : Image file for splash screen. Image size should be 473 x 300
2. frame.gif : Used as icon on top left application window. Must be of 16 x 16 size.
3. frame32.gif : Used as application icon on windows alt+tab. Must be of 32 x 32 size.
4. frame48.gif : Shown on linux . Must be of 48 x 48 size.
5. about.png : Shown in Help->About dialog in application. Must be of 532 x 254 size and type png.

Once you have above items ready, follow the procedure below :

1. Go to [install_dir]/custom-branding-script/ directory. Copy in this directory all image files you repared above.
2. Open build.properties file to make following changes:
   • Change APPLICATION_TITLE property value to appropriate value. This will be shown in your appplication's title bar
   • Change SPLASH_WINDOW_TITLE property value to appropriate one. This text is shown on splash image when application starts up.
   • Change ABOUT_BOX_DESCRIPTION property value to appropriate one. This text will be shown in Help->About dialog and generally provides a brief description about your company or product. You can use simple text or html as property value.
   • Change URL_ON_IMG property value to url of your company or product.
   • Save and close the file.
3. From command prompt, go to [install_dir]/custom-branding-script/ directory and run Ant. You should have Ant version 1.8.0 or above installed.
   Note

   custom build script changes many property files, one of which is [install_dir]/jwebdesktop//config/application.ini. This file contains many properties to control application behaviour. You may like to play with it to suite your needs. The ini file contains explanation comments for each property.
   
   Ant versions prior to 1.8.0 doesn't retain comments while updating a property file. Be aware of this issue if you plan to run custom branding script with any prior Ant version.
4. Once Ant build runs successfully, start the application and test. All icon/image and/or title,text etc - whatever you have changed so far, should show up properly.
   Note

   sometimes, you may need to clear application cache to see the changes. Application cache is generally created in system's temp folder. You can find the exact location in Help -> About dialog.
5. We are almost done with branding. Last thing left is rebranding the executable (i.e. [install_dir]/bin/jwebdesktop.exe and [install_dir]/bin/jwebdesktop)
6. Rename the executables to whatever name you prefer (i.e. myapp.exe etc.)
7. For windows platform, you may want to change the executable icon (i.e. for [install_dir]/bin/jwebdesktop.exe). To do so, download free ReplaceVistaIcon.exe from RealWorld Graphics. The executable icon can be simply changed by invoking : ReplaceVistaIcon.exe [install_dir]/bin/myapp.exe YourIconFile.ico
8. Congratulation! Branding is complete. You can delete [install_dir]/custom-branding-script/ directory if you want. This is not used by runtime and not required to be bundled with application.

While not essential, you may want to do some further tuning to customize your bundled application. Below are some important pointers.

Using bundled browser

By default, applications packaged with JWebDesktop will use system default browser. This may present a challange for application developers, as you will have to test your application for different browsers (IE, FF, Safari, Chrome etc) and different versions (IE 5, IE 7 etc) to verify whether your application is rendered properly.

JWebDesktop provides a facility to bundle a XULRunner (i.e. Firefox) instance along with applictaion and use it as embedded browser. XULRunner version 1.9.2 is supported(Check FAQ section to find out why higher versions are not supported). Detailed instruction to bundle XULRunner is in [install_dir]/jwebdesktop/config/xulrunner/Readme.txt file inside JWebDesktop binary.

Other customization options

[install_dir]/jwebdesktop/config/application.ini defines various parameters to control applictaion behaviour. Change it to fit your needs. The ini file contains detailed comments on what each parameter means.