For a list of currently available DBApps go to downloads section
DBApps does not differ from any other web applications except for these points:
- all sources (web pages) must be contained in a folder
- folder name will give the name to the DBApp
- DBApps must have a single entrypoint named start.msp (that need to use the appropriate APP entrypoint header
There can be as many other pages as necessary, and other subfolders as well: a DBApp is a stand-alone web site in all and every aspect.
This picture illustrates the standard layout of a DBApp:
DBApp are portable by definition, because they are pure code (and eventually some images). You can see an example at the bottom of this page.
How to run a DBApp
To run a DBApp on client you need one of these condition to satisfied:
- DBFree (of same version) installed
- DBFree runtime installed (versions previous to V4)
Then all you have to do is to copy the App Box
(the folder containing the DBApp) into the Apps Root
of DBFree (i.e.
Writing a DBApp
Writing a DBApp is considerably simpler than a full application:
- database engine and settings are the same of the host: there is nothing to configure.
- you can rely on the standard login system of the companion site instead o writing your own.
- while the location is predefined databases and tables of your DBApp can be isolated from others or shared, as you like.
On the other hand you must follow some restrictive specifications:
- You must create databases and tables at first use (they cannot be included with the DBApp) and populate them later (usualyy with a separate
set of files) or a separate download.
- all links to CSS,JS and common DBFree components must use absolute paths (i.e. prefixed by a single slash, like in /common/header.h
Choosing the programming style
There are several possibilities, but we recommend to use the webObjects model
for a real-world DBApp, while confining the
Classic CGI model
to the first learning stage.
In the Classic CGI you will have lot of files to deal with, typically pages which work in pairs (a web form and its target page), but that
makes clearer what does what and where.
Using WebObjects you will probably work with a single, very large file (or maybe few others): while this makes a little harder the editing you won't have
to worry about broken links and the related issues.
(for a detailed discussion about WebObjects please refer to the appropriate documentation)
Choosing the right header
This is simple: choose an APP header from the headers section of Code Assistant.
Usually you'll find several headers from which to choose; best practice is to choose the more recents.
are numbered progressively: just check to your target systems is equipped with the same library version of the header you choose.
Tip:If you don't know what library are you actually using just go to Contol Panel, choose Expert Mode and open the MaxScript console.
? libver() and you'll get all details.
To check if your DBFree installation is up-to-date go to DBFree.org home page and compare it with the string of library actually in use (usually it
is in the lower right corner of the window).
You may also want to use a Page Template
: in this case you will have a standard page ready to be tested.
Just remeber that you must have only a single entrypoint page
(with an APP entrypoint header
): all other pages must use either a APP follower
template or a Generic
Why all these differentiations?
Main reason is that the Entrypoint page is the one that sets the Current User Session: as soon as the other pages are called by this first one (and use the
APP follower header) they conserve the session (that is the session variables intializated from the entrypoint page).
This is not a trivial matter as it may seem.
DBFree session system does not consume memory (at least until the user does not reload its page) and can stay on for hours, days or months, without
affecting server's performances.
It is a great advantage that it is better not to give up, especially at the reduced cost of taking care of these small details in the design phase of the application.
We suggest to approach to DBApps with this simple tutorial:
Step 1 - preparing the playground
- Start DBFree Control Center and make sure that the server is running (click on See in browser and see if the companion site opens)
- Click Open web root (now you should see the WEB folder opening in a Windows pane)
- Double click on
Apps folder: then right click and from context-menu choose
- Name the folder something like
- Create a new empty text file and name it
start.msp (be sure to get the correct file extension: in your folder options you should keep
Hide extensions for known file types disabled)
- Double-click on the newly created file: it should open inside PSPad Editor
- Add these lines:
<h1>Hello</h1><hr><h4>This is <%=pagefile()%></h4>
Be sure to save the changes before to proceed.
- Now come back to browser's window, where you should actually still have the Home Page of your companion site open, and from the top menu choose
Applications and then
List all DBApps (or just locate and click the button Application menu in the page ): you'll notice a new item in myApp appeared
in the menu
- Click on the new myApp link and you should see your newly
start.msp page opening.
With an error message like:
** ERROR R0049: procedure/function not found: PAGEFILE
START.MSP interrupted [date and time]
line(2), proc START
Congratulation! It's all ok: you have just started developing your first DBApp.
From now on arm yourself of patience, elbow grease and be ready to start the standard trial-and-errors learning path
We got the first error, so we are going to learn something.
Step 2 - adding the DBFree components to the page
If we look at the error message it says that on line 2 there is an error:
procedure/function not found.
But looking at the code in the line we see there are only HTML tags (that can't cause any errors to the MaxScript interpreter, because it ignores anything
is outside the server-side tags).
So our error must be caused by something contained between <%= and %>, and there is only one candidate
for that: the call to pagefile() function.
If we look at the language reference
we see that
is a perfectly legitimate function.
So, what's wrong? Try to eliminate the offending instruction (delete the fragment of code
and you can see that now the page
works without errors.
This because pagefile() is part of a different library.
And, as we said before, loading libraries is a job for the DBFree headers.
Thus, in our page, where it is that libraries are loaded? Nowhere.
We simply didn't add any header yet.
- Open DBFree.org web site in a separate window of your browser (other than the one with the companion site) and arrange it on the screen so you can
work with both.
- Open the Code Assistant and go to a section which list the available templates.
- Choose a template, open the file, select the code, copy and paste it to our
For your convenience we provide an header here below - you can use this:
myAppId := "myApp"
**************************************** MICRO HEADER 126.96.36.199
zcLib := mspconfigvar("LIBDIR")+"\free.lib"
set maxlib to &zcLib
cSeed := MspFieldValue("XY")
Be sure to paste the above code chunk in the correct place, that is at line 2, right below <!DOCTYPE html><html>
Now the page should work as expected and you should also see the name of the file returned by the function
Having this DBApp doing something
At the time our application (with this code) makes absolutely nothing and does not differ in any way from a static page, if not for the fact
that tells us by itself what is the page that hosts it.
It's now time to add some useful content, like for any normal page. But before of that wouldn't be a good thing to worry about how to gracefully close
Adding a callback menu
This is not a concern: we just need to add a link back to the calling page, the DB Applications Menu. Right?
Wait a moment. Yes, but what exactly was the calling page?
There is a convenient way to know it: just add to the page this chunk:
<hr>This page was called from <%=callingPage()%><hr>
As you see this function returns the complete URL
of the calling page.
So we could store it into a variable and use it for building our back link, this way:
<% cBack := callingPage() %>
<hr><a href="<%=cBack%>">Go to main menu</a><hr>
This code should work, but chances are that, if you're on Windows 10 and using Microsoft Edge as browser
, it won't.
If the above link does not work we need, as first thing, to check what URL
are we passing to the browser. Just modify the code this way:
<% cBack := callingPage() %>
Now you will see what is passed as URL.
At time of this writing MaxScript returns the URL of calling page without the protocol prefix
Notice that Mozilla Firefox and Google Chrome just keep going gracefully without that, while (as for Jan 2015 version) Microsoft Edge ask you to install an application
for managing this situation.
Let's forget why this happens and go on fixing the problem. One immediate solution is to add the missing string this way:
<% cBack := "http://" + callingPage() %>
That should be ok. but what would happen if - for a reason or another - suddenly (with one of the continuos improvement Microsoft does to Windows and its
continuos process of updating) our function would start returning the URL with
the protocol prefix?
Surely would be better to check if the protocol string is already there before to proceed adding in it; this is done by the next lines of code:
cBack := callingpage()
cBack := "http://" + cBack
As you must suspect the function occur(cSearchStr,cText)
accepts a strings and counts how many occurrences match into another.
Now it's all ok. Just a final refinement: instead of a standar, plain link, what about a nice button?
This can be done by using one of the standard user interface
functions of DBFree (button(cLink,cMsg)
<%=button(cBack,"Go to main menu")%>
Now our rough DBApp is ready to receive some code to actually do something useful.
But this is not a topic to be discussed here: from now
on you can treat this page like any other one and follow the explanations relating to that topic elsewhere.
What we need to discuss here instead is what if this DBApp would have some pages other than this one?
Adding other pages
We already know how to add hypelinks, so all we have to know is how to create new pages. And then add as many pages (and as many links) as our DBApp needs
(and this is up tp you, as a programmer).
To add other pages just repeat the same steps seen before but choose the appropriate header, that is a Follower Page header (sometime called Slave page
But, wait a moment: have we choosen the right header for our page?
Well, no. We used a micro header for convenience. It's time to amend this and go to Code Assistant for chosing an header like this
(APP entrypoint header 188.8.131.52) or a newer one, if available:
Hide/Show the code
Now you're really ready to start your development.
DBApps developer's Quick Start
For further informations please visit the Publications section on this site or take a look at
Curious about DBApps? Do you want to know how to build one?
To build a DB app you need to follow these steps:
Step 1 - Preliminary operations
- Create a folder into the Apps Box using the desktop
- Choose an entrypoint template using the on-line Code Assistant
- Create the entrypoint page using the desktop
- Edit the entrypoint page using your PSPAd Editor
Step 2 - Equipping the entrypoint
- add the header Code Assistant
- add the webvars stack Code Assistant
- add standard webvars section Code Assistant
- local settings To be coded manually
- add an empty database section Code Assistant
- add an empty background operations section Code Assistant
- main interface section To be coded manually or using buildmenu() helper
- add basic foreground actions To be coded manually or using Code Assistant
- add the footer Code Assistant or To be coded manually
Step 3 - Designing the data tables
- Creating the master table Tables Wizard
- Creating the slave tables Tables Wizard
- Adding basic background actions for records To be coded manually or using Code Assistant
- Creating basic web forms buildform() helper
Step 4 - Refining the structure
- Adding basic foreground actions To be coded manually
- Creating other web forms for user interaction To be coded manually
- Linking to web grids for table browsing Using Core Templates
- Creating internal web grids for listings To be coded manually or using Code Assistant
- Adding comments on top of page (with value for parameters accepted) To be added manually
You're strongly suggested to use Mozilla's Firefox Developer's edition throughout all the development cycle instead of
Firefox for Developers offers lots of useful functions that will help you to isolate errors and problems otherwise invisible
in a web page, plus offering tons of specialised add-ons for color picking, tags checks and more.
Top of page