Portable DBApps Open on a page of its own


For a list of currently available DBApps go to downloads section
DBApps does not differ from any other web applications except for these points:
  1. DBApps rely on resources (libraries,CSS,javascripts) of the host (the DBFree main installation)
  2. all sources (web pages) must be contained in a folder
  3. folder name will give the name to the DBApp
  4. 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: 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. c:\maxsis\dbfreeV41\web\apps).

Writing a DBApp

Writing a DBApp is considerably simpler than a full application:

On the other hand you must follow some restrictive specifications:
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.
DBFree Headers 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. Then type ? 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 header.

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.


Quick Start

We suggest to approach to DBApps with this simple tutorial:
Step 1 - preparing the playground
  1. Start DBFree Control Center and make sure that the server is running (click on See in browser and see if the companion site opens)
  2. Click Open web root (now you should see the WEB folder opening in a Windows pane)
  3. Double click on Apps folder: then right click and from context-menu choose New Folder
  4. Name the folder something like MyApp
  5. 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)
  6. Double-click on the newly created file: it should open inside PSPad Editor
  7. Add these lines:
    <!DOCTYPE html><html>
    <h1>Hello</h1><hr><h4>This is <%=pagefile()%></h4>
    </body></html>
    
    Be sure to save the changes before to proceed.
  8. 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
  9. 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.

Why?
If we look at the language reference we see that pagefile() is a perfectly legitimate function. So, what's wrong? Try to eliminate the offending instruction (delete the fragment of code <%=pagefile()%> 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.

  1. 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.
  2. Open the Code Assistant and go to a section which list the available templates.
  3. Choose a template, open the file, select the code, copy and paste it to our start.msp file.
For your convenience we provide an header here below - you can use this:
<%
myAppId := "myApp"
**************************************** MICRO HEADER 4.0.1.2
zcLib := mspconfigvar("LIBDIR")+"\free.lib"

set maxlib to &zcLib
initlib()
*****************************************
cSelf :=pagename()
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 pagefile().

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 the App?
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.
Why?
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 (i.e. http://. 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()
if occur("http",cBack)=0
   cBack := "http://" + cBack
endif
%>
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 header).
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 4.0.1.6) or a newer one, if available:
Hide/Show the code

Now you're really ready to start your development.

For the lazy ones

In a hurry? Just give a try to this Single-page, ultra-light, 260 rows DBApp: Simple App Demo (with source code)


DBApps developer's Quick Start

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

  1. Create a folder into the Apps Box using the desktop
  2. Choose an entrypoint template using the on-line Code Assistant
  3. Create the entrypoint page using the desktop
  4. Edit the entrypoint page using your PSPAd Editor

Step 2 - Equipping the entrypoint

  1. add the header Code Assistant
  2. add the webvars stack Code Assistant
  3. add standard webvars section Code Assistant
  4. local settings To be coded manually
  5. add an empty database section Code Assistant
  6. add an empty background operations section Code Assistant
  7. main interface section To be coded manually or using buildmenu() helper
  8. add basic foreground actions To be coded manually or using Code Assistant
  9. add the footer Code Assistant or To be coded manually

Step 3 - Designing the data tables

  1. Creating the master table Tables Wizard
  2. Creating the slave tables Tables Wizard
  3. Adding basic background actions for records To be coded manually or using Code Assistant
  4. Creating basic web forms buildform() helper

Step 4 - Refining the structure

  1. Adding basic foreground actions To be coded manually
  2. Creating other web forms for user interaction To be coded manually
  3. Linking to web grids for table browsing Using Core Templates
  4. Creating internal web grids for listings To be coded manually or using Code Assistant
  5. 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 Microdoft Edge.
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.
For further informations please visit the Publications section on this site or take a look at http://dbapps.dbfree.org.
Top of page