beap beta - README Welcome to beap - the Browser Enabled Application Platform Project Status -------------- { "BeapStatus" : 201, "StatusDescr" : "closed beta", "Result" : "vers 1.3.3 - 06.02.2013", "Contact" : "mail@beap-code.de" } What's inside? -------------- A complete beap installation consists of three main parts: - the beap backEnd server - the webserver (Hiawatha as default) - the beap frontEnd framework and a few additions: - the beap browser - a svn client - a PDF client Not part of the standard installation is BeapDB, a javascript/node.js-based application database. Installation ------------ At the point of this beta-release, only a Windows installer package is available. Versions for Mac OS X and Unix/Linux are functional/under active development but no installation packages so far. We apologize for this inconvenience and ask for your patience. The installation package will install all required components to get You started. You may want to read the evaluation license file before installing beap beta. A online version of the license can be found at http://www.beap-code.de/license.txt Executing the package requires administration privileges. IMPORTANT: The current version of beap is not compatible with File System Virtualization as used by versions of Windows since Windows XP. To prevent compatibility issues, the default installation path {beap} is currently set to C:\beap. You may choose to select another path or disk, except the windows programs folder. We apologize for this inconvenience. Upon uninstallation, it will be necessary to manually remove this folder. This is because whilst the setup program runs with elevated privileges the uninstaller does not. Elevated privileges are required because the installer adds the following registry entries: [HKLM\Software\Beap] [...] - this is where beap stores its settings (see below) [HKLM\Software\Microsoft\Windows\CurrentVersion\Run] - to ensure beap starts with Windows Getting started --------------- After installing beap you will find a link to the 'beap browser' on your desktop, which will automatically connect to the local server. Alternatively you can enter the following URL in your browser: "http://localhost:9999/" The opening [ Main Page ] is this README file as html version. On top of the page you will find the links to the standard application and the beap test page. The standard application of the beap beta installation is its documentation. After starting the 'beap browser', the standard application defined in the index.html file is loaded; in this case the documentation alongside with the template app. For further details on this pages, see the [ Documentation ] section below. What is it? ----------- The basic idea behind beap is to create a platform for desktop applications using the flexibility of HTML and CSS for the user interface in combination with the strength and speed of compiled libraries and native system ressources. Particular attention is paid to allow consistent, OS-independant system access while ensuring security. beap backEnd server ------------------- The beap backEnd server comes with a set of options to restrict and manage secure access to the underlying OS, as well as providing a mechanism to integrate the communication between "number crunching", compiled libraries to the web frontend. The beap server is designed for a minimum footprint on system resources. Thus it may operate as single user application backend on a workstation or notebook with low impact to system performance. The same objective, as well as its high security standards led to the choice of Hiawatha as the sandard webserver. Using the beap backEnd server on a dedicated machine as "blackbox" application server for multiple users in an intranet environement is onother option. In this case we recommend using a different setup requiring additional configurations and installations: Apache httpd webserver, user-based permissions, additional network security measures. Such setup was tested but would exceed the boundaries of this beta release. beap frontEnd framework ----------------------- The beap frontEnd framework provides a full set of libraries for building HTML/javascript-based user interfaces with extended functionalities taking advantage from the event-based, asynchrounous execution possibilities of a web-based frontend. It has no dependencies on any other javascript library. The main goal of beap is to create business-grade desktop applications. Therefore a standard set of scriptable common UI-elements and controls (views, menues, context-menues, message- and progress-boxes, login, file viewer ...) is integrated in the framework. To display or submit deeply nested structured data, input masks and forms can be generated at runtime from structure definitions. Usage of the frontEnd framework is not mandatory. You may choose to implement the user interface in basic HTML/CSS/JS, you may also use your favourite javascript library. Anyway we do not recommend using the beap frontEnd framework alongside with another javascript library like jQuery. beap browser ------------ The beap browser is a QT/Webkit based viewer. This browser is as minimalistic as it can be - for security considerations. It has no address bar, no menues etc., so it is quite unlikely that it can be 'abused' by end users. It is also important to note that the beap-browser has no vendor-specific keyboard shortcuts or non-cancelable context menues. Especially in an business environment the beap browser will be the best choice to implement a full-fledged Desktp application with a common look and feel upon starting its main window. other browsers -------------- Also, you may of course use any other browser to connect to the beap application. Whilst any standards compliant brower should work, the following have been qualified of being compatible with the beap frontEnd framework: - WebKit based browsers [ Chrome, Safari ] - Gecko based browsers [ Firefox ] - Presto base browsers [ Opera - still some glitches ] - any IE with Chrome Frame AddOn [ no pure IE, sorry ] Using the beap frontEnd framework with mobile devices is functional but highly depends on the processing capabilities of the device, its browser and the requirements of the beap application. Additional Note for Internet Explorer: As Microsofts JScript engine is way behind the javascript enginges of other browser vendors, and the beap frontEnd framework highliy depends on this enhanced features, it will not run in pure IE. Installing the Chrome Frame AddOn requires no elevated privileges for the users, it meets the javscript requirements and produces better rendering results for the beap UI elements. Anyway, using plain HTML/CSS/JS with a javascript library supporting IE is fine. The standard beap installation comes with two additonal utilities not used in the beta release yet: - the svn CLI-client is used for remotely updating the "soft" parts of the software (mainly wwwroot). If you are interested in this option and need more details, please feel free to contact us. - the 's, a single
for the results, styles and javascript are inline. Although this seems to disregard any www best practices, it is by purpose. Mainly to demonstrate in compact form the minimum requirements for a successfull communication with the beap backEnd server. You may develop a beap based application without using the fronEnd framework, only using basic HTML, CSS, javascript. In this case this test-page gives a minimum set of code snippets to do so. Beap Requests and Responses --------------------------- Any beap request is basically a HTTP POST to /cgi-bin/beapx.cgi with its corresponding BeapId as the first parameter (this is mandatory). The order of all other parameters does not matter, unknown fields will be ignored. Malformed or missing parameters will cause an error message to be returned. You will also find additional description on the individual operations in the document "beap Core Operations". All processed requests will yield a JSON response. Responses are sent as "Content-type: text/plain" and contain at least the values: - 'BeapStatus' as integernumber status codes are derived from the standard HTTP status codes with a few exceptions and additions. - 'StatusDescr' as string a short description of what was happening behind the scenes. Examples: { "BeapStatus":200, "StatusDescr":"OK" } { "BeapStatus":404, "StatusDescr":"Cannot Open File" [...] } { "BeapStatus":418, "StatusDescr":"Not Acceptable - BeapId not found" } beapStatus 418 Informs you that there was a problem with the beap ID in your request. Either the ID was missing or it was not at the beginning of the request. Some requests (e.g. BeapDirList) will return "payload data" in the JSON response. Especially File IO may contain JSON or javascript as payload, they will be quoted accordingly. Although the beap core functions use their own naming conventios for their results, the standard return value/payload will be in the response JSON object under: 'Result' (as JSON). The result may be of variable type, depending on BeapId or beap module. From the frontEnd framework's view, the responses can be in "loose JSON format": the response may contain comments of both styles, javascript references or function declarations. Circular references, multiline strings or function calls in the response will cause an error under all circumstances. Another standard field in the JSON response is 'BeapDebug' (as string). If the module under the requested BeapId supports this feature, debugging informations are returned to the browser in this field. It is strictly a string, escaped, and may contain HTML code. The debugging informations may be more descriptive than the 'StatusDescr', if desired (and properly HTML-formated) they may also be presented to the user. Both fields, 'Result' and 'BeapDebug' are optional, also any other return field. A JSON response containing only 'BeapStatus' and 'StatusDescr' is valid in any case. In conclusion, as standard beap response looks will like this: { "BeapStatus" : , "StatusDescr" : "", "BeapDebug" : "", "Result" : A minimum beap response looks will like this: { "BeapStatus" : , "StatusDescr" : "" } The beap frontEnd framework has representations for all core backEnd functions. They handle the AJAX request, parsing/unescaping of the responses and catching exceptions. In case you do not want to use the frontEnd framework, the choice of using plain old xmlHTTPrequest, parsing/unescaping with vanilla javascript is up to you. Final remarks ------------- At this state of development, many features and caveats are not fully documented and still under active development. The backEnd server is single threaded at the moment. Although accepting further requests, the server executes them one after another; this will change soon. In case you are proficient in javascript and take the effort to browse through the beap frontEnd framework, please be lenient with us above the numerous /* ToDo */ and /* provisional */ comments, still a lot of way to go ;-) If you need further, more detailed information or find any bugs please feel free to contact us. Any suggestions for improvement are highly appreciated. Links ----- evaluation license http://www.beap-code.de/license.txt latest README.txt http://www.beap-code.de/README.txt Copyright & Contact: -------------------- copyright: 2012, the beap team Siggi Gross Jürgen Kraus contact: mail@beap-code.de