Manage Data Your Way
Creating FuguHub Applications
FuguHub is designed for non-technical users, so you do not need to know anything about programming when installing or using FuguHub. This tutorial is intended for programmers who want to tinker, customize, or write new applications for FuguHub.
Easy to learn scripting language for beginners to hardcore programmers
You will have to learn the Lua language and server side web development if you plan on writing your own applications, but you do not have to write any low level C or C++ code. However, users with C/C++ experience can optionally extend the server with new functionality by loading additional C libraries at runtime.
The Lua Scripting Language
Lua Server Pages makes developing web applications extremely fast, simple, safe, and fun. Notably, it isn't limited to developing web applications, but can also be used to provide high-level socket APIs that make developing secure socket applications very easy. We also provide HTTP client libraries, SMTP (mail) libraries, database integration (SQLite is embedded in FuguHub), and other options.
Lua Server Pages are based on the Lua Scripting Language. Getting started with LSP is easy if you have previous experience with similar technologies such as PHP or ASP.
The about FuguHub page includes an introduction to how FuguHub is assembled, and explains how this consumer product was developed using the Barracuda Application Server "C" library. Real Time Logic's core business is to provide this C library to engineering companies, who in turn embed the code in device firmware.
As illustrated in the figure to the right, the FuguHub server's two main components are the generic Barracuda Application Server "C" Library and the C/C++ code designed specifically for FuguHub. In addition, a number of LSP applications are bundled with FuguHub such as the CMS and the forum. The LSP applications are delivered as source code, so you are free to study and modify this code. See the FuguHub Parts List for a detailed explanation of all parts delivered with FuguHub.
Lua Server Pages Programming API
since FuguHub is developed by using the Barracuda Application Server C Library, all of the Barracuda Application Server's Lua API's are supported, enabling you to write anything from easy to advanced server side web applications.
Application Server and Lua
We recommend reading the Barracuda Application Server article What is an Application Server? if you are uncertain about the difference between a web server and an application server or if you are new to writing server side web applications. We also recommend reading the Lua fast-tracks web application development article if you are new to Lua and web design.
Dynamically Generated Pages
Lua Server Pages (LSP) can be freely intermixed with HTML or XML. LSP tags are XML compliant
LSP Page Counter Example:
<?lsp page.count=page.count and page.count+1 or 1 ?> <html> <body> <p> You are visitor <?lsp=page.count?>. </p> </body> </html>
FuguHub provides Lua bindings (interface from Lua to C code) for the following integrated components: the Barracuda Application Server, SharkSSL SSL/TLS duo stack, Lua Server Pages, SMTP Client, HTTP(S) Client, AJAX, JSON, JSON-RPC, XML-RPC, SOAP Web Services, WebDAV Server, the EventHandler, High Level Secure Sockets, the SQLite Database, the GD Graphics Library, and Lua LPeg. You can dynamically load additional Lua bindings at runtime such as an API to your own hardware, but this requires that you also master C code.
Getting Started With LSP
To get started with FuguHub, install the server on your own computer, but skip the Internet Wizard. The server you install on your own computer will be your test server. You can start developing LSP applications as soon as you have installed the server, but we recommend that you download the API documentation and complete a tutorial before attempting to write any LSP applications.
- Download and install FuguHub.
- Download the "Barracuda Application Server" documentation badoc.zip.
- Download the "Do It Yourself" tutorial diy.zip.
- Move the two downloaded files badoc.zip and diy.zip to the FuguHub application directory. The FuguHub's application directory can be found as a sub-directory in the FuguHub installation directory.
- Using a browser, navigate to FuguHub, menu, Administrator Panel, Application Manager, Load, and click the load button to load badoc.zip and diy.zip.
- FuguHub will add links to the left menu, under section "Loaded Applications" for the documentation and the Do It Yourself Tutorial.
- Using FuguHub, complete the Do It Yourself Tutorial and use the loaded documentation for reference.
Using LSP in FuguHub
You have three options when it comes to writing LSP applications in FuguHub.
- Use the CMS and add LSP directly into the CMS pages.
- Add LSP files to the cmsdocs directory.
- Create a new FuguHub application.
Option two is for applications that should be an integral part of the CMS web pages. You can add LSP pages directly to the cmsdocs directory and/or to any sub-directory in the cmsdocs directory. For example, creating index.lsp in sub-directory 'shopping' can be access as http://my-server/shopping/ and http://my-server/shopping/index.lsp. Be careful with creating pages with the same name as pages in the CMS. Your own pages take precedence over pages in the CMS. For example, adding page index.lsp directly in the cmsdocs directory replaces the CMS main page when you navigate to your server.
Option three is for standalone or advanced applications. How to create and load new applications are briefly explained in the FuguHub help-file under Administrator Panel, Application Manager, New.
When you create a new application you must first create a new sub directory in the FuguHub installation directory. This directory will be the base for your application. In other words, the web pages for your application are stored in this directory. Using a browser, navigate to FuguHub, menu, Administrator Panel, Application Manager, New. Click the browse button, browse and select your newly created directory. Use the directory name as the "Application Name" and click Submit. On the next page, select LSP and click Submit.
When creating a new application, you will get the option of creating a regular application or a root application. A root application is as the name implies, an application that starts with the URI /. For example, an index.lsp page in the application folder is accessible as http://myserver/. A standard application starts with the base name you selected as the application name. For example, an application named myapp and with index.lsp in the application folder is accessible as http://myserver/myapp/
The CMS delivered with the FuguHub server is configured as a root application. You can easily verify that the CMS is a root application by navigating to http://myserver/. You should see the CMS main page.
FuguHub can load multiple root applications. Resource (name) conflicts are resolved by the application's priority. For example, two root applications with an index.lsp are resolved by executing the index.lsp page in the application with the highest priority. You can dynamically change the priority for any root application by clicking on the root application name in the FuguHub's application list. Note: you can only change the priority for root applications in FuguHub.
You can optionally deploy an application when you have completed the development. Deploying an application is done by zipping all pages and data in your application directory and placing the ZIP file in the FuguHub "applications" folder. Using a browser, navigate to menu, Administrator Panel, Application Manager and stop the development version. Click the Load menu link and then click the load button to load your newly deployed application.
You can also unpack any of the FuguHub applications such as the CMS. You can that way easily modify any of the applications that are delivered with FuguHub. Copy the unpacked content to a new directory and use the Application manager to load the non deployed application. Follow the steps above for creating a new application when loading a non deployed application.
You can remove the LSP applications delivered with FuguHub if you want a complete custom solution. However, the internal user interface (uri /rtl/) cannot be removed. The server will not start if it is unable to load bd.zip.
Creating libraries, re-usable code, or non web applications
At this point you are ready to make your first LSP application(s). The rest of this document is tailored for advanced application design.
FuguHub has the concept of an application environment. The environment for an application is a location where you can keep commonly used Lua code i.e. library functions. This environment is available to LSP pages in the application, but not to LSP pages in other applications. The application environment is referred to as the application table in our documentation. FuguHub provides a number of environments that can be used by LSP programmers. See the "Lua -> overview" in the Barracuda document for more information.
The Lua code is typically not embedded in LSP pages if you write functions that are designed to be re-used by several LSP pages or if you write Lua code that is using the more advanced features of the Barracuda Application Server API's. FuguHub looks for the file ".preload" when loading applications. You can place your generic functions in this file as well as any code that is not directly associated with a web page.
Functions and data in the .preload script are added to the application table. You can access this table from an LSP page as "app". For example a function such as myfunc() can be accessed from an LSP page as app.myfunc().
The .preload scripts are executed when FuguHub starts and when an application is started by using the FuguHub Application Manager. You can use the Application Manager to load your new version at any time during development. Click the stop button and then the start button to reload the script.
When an application is stopped by FuguHub, code in the .preload script will eventually become garbage collected by the Lua virtual machine. However, sometimes you may want to do an immediate action when an application is stopped. FuguHub looks for the function "onunload()" just before stopping an application and executes this function if you have created such a function in your .preload script.
The CMS is a deployed application that has a .preload script internally located in the ZIP file. This file is executed by FuguHub when the CMS starts. The CMS preload script is in turn looking for a .preload script in the cmsdocs directory. You can extend or add your own functions to the CMS by creating a .preload script in the cmsdocs directory. For example, adding a function such as myfunc() to the .preload script in the cmsdocs/ directory can be accessed from LSP enabled CMS pages and LSP pages in the cmsdocs/ directory as app.myfunc().
CMS .preload script example
The following example shows how you can create a custom 404 handler by creating a text file cmsdocs/.preload in an editor and then copying and pasting the following Lua code into the .preload script.
The above example is specifically designed for the CMS .preload script. The cmsdocs directory is chained in such a way that response:forward() cannot find files in the cmsdocs directory. We have to use response:redirect() as an alternate solution. Notice how we have the special construction that prevents recursive calls.
Note: the cmsdocs/my404.lsp must be an LSP page that includes the following LSP code:
<?lsp response:setstatus(404) ?>
Modifying FuguHub's Internal Resources
Starting with FuguHub (BD) 6.0, the server's internal resources can be loaded in non deployed mode. The resource files are located in bd.zip. The following instructions are for unpacking this ZIP file and for requesting BD to load the unpacked (non deployed) resources.
- In the BD installation directory, create a new sub directory such as bdzip.
- Unzip bd.zip into this directory.
- Open a command window in the BD installation directory.
- Set the environment variable BD_ZIP=bdzip, where bdzip is the directory where you unpacked bd.zip. For example, use the following command on Windows: set BD_ZIP=bdzip.
- Start BD as a foreground process on the command line. For example, use the following command on Windows: bd -console.
- You can now actively edit and modify the BD resources using an editor. Pressing the refresh button in the browser reloads your modified content.
Extending FuguHub with Custom C or C++ Code
FuguHub C Source Code
The FuguHub C source code is available at SourceForge. The source code is provided as a Mako Server plugin. See the Mako Server Source Code page for details.
Beginning with FuguHub 5.3, the Lua to C API in FuguHub (lua bindings) can be extended. Shared libraries (DLLS on Windows) can be dynamically loaded by Lua scripts at runtime. Loading shared libraries at runtime is in Lua terminology called loading a module and is performed by calling require("module-name") from a Lua script or LSP page.
Building C modules is an option available to developers with C experience. A Lua C module makes it possible to extend the server's API with new functions. For example, you can add new Lua functions that accesses your serial or USB driver and that makes it possible to manage hardware via a web based user interface. Building modules for FuguHub is identical to building modules for the Mako Server. See Building C/C++ Modules for the Mako Server for more information.