Developing Web Apps with DBFree 1

New to DBFree?

Better to start from here DBFree for Newbies!


Open in a new tab
jump to Creating a Web App step-by-step

Introducing DBFree V4

DBFree is the name of the project and also of all of the final products (the "distros") we release: currently DBFree has 3 major releases (V2, V3 and V4). This document refers ONLY to the latter.
DBFree is a framework for web applications that makes use of various software tools, mostly Open Source, that includes a webserver, a database engine and one or more script interpreters togheter with other tools to let you develope and run web applications from a single package, easily portable from a server to another.

Among other advantages this approach completely eliminates the need of installing and configuring on each server (or PC) a separate database engine and all the complications of their backup systems.

DBFree is intended to be light, fast and simple:
many compromises has been made to avoid complications and to keep it easy to handle and administer. For this same reason it is missing lot of the things available on most of the frameworks or languages around.

We literally stripped down the product to what seems to us the essential to make it something different and not a competitor of the too many fully-fledged giant frameworks already on the market.
Less features to deal with, higher the chanches you'll get it working soon.

DBFree was born to promote the use of MaxScript, the only modern Xbase language born for the web, and MaxScript still remains the script language upon the whole structure is developed. Anyway DBFree makes in some parts use of PHP and LUA (also part of DBFree installation), and obviously Javascript. Except for Javascript (wich is provided by the browser in use) all the other languages are fully server-side and are embedded into DBFree distro and not available for external use.

DBFree is not a Clipper clone. That is a common misconception. During its development the product was only targeted to modern web applications, not for converting old xBase apps. Nevertheless it conserves a strict reseblance with its ancient inspirer.

DBFree offers all you need in one package

With DBFree V41 you have already all you need to start developing your own solutions for the web: it may be not a collection of best software around (everything is or freeware or open source) but it does the work, and does it immediately (no configuration needed):

Serving Web Apps to users

The fundamental purpose of a website is to allow external users to get contents on request. To do this we need to have:
  1. A public IP address where users can send their requests by using a standard web browser
  2. A router connected to internet that enables connections on that IP address
  3. A web server towards of which all incoming requests are routed
  4. A website that accepts and matches the requests by providing the responses

Serving pages through a web server is a process that is accomplished in two steps:

1 - The server receives the requests from remote user
2 - The server send back to user the content relating the request made

The request is made using the http protocol, but how this happens is not something that should be of interest to the programmer. We just know that it works.

The round-robin trip of the pages that go up and down from browser to server is very practical but has an important drawback: the pages shown on client-side are usually stateless, that is once the page is received from server the connection is close and there is a complete absence of further links between what is shown to user and what happens on server.
At least until the user refresehes the page (i.e. requests the same page again).

On the one hand this allows the server to satisfy thousands of requests, because it sends the page and immediately forgets about it (not even waiting an aknowledgment that the page has been received), but on the other hand this mechanism leaves the pages received by user in a constant state of uncertainty.
In other words there is no guarantee that the data shown in a web page are still valid: it is valid only on the spot.
If something changes on server the user won't be informed and he has no ther way to know check than connect again and reload the page.

This is one of the aspects of Web Programming that programmer must always keep in mind and that makes building Web App so different from traditional desktop applications where there is a constant link between the output supplied to users and its source.

Of course there are technologies that consent to partially remedy to this inconvenience and provide a more fluid user experience, closer to that offered by a desktop application. Anyway this is an advance topic that we can't discuss here.
(For these aspects we invite you to consult more specific publications available on DBFree.org.)


Introduction to Web Apps

Before to start is better to agree on what exactly is a Web App: in general a web application (or web app) is any software that runs in a web browser. As such there is no difference if it relies on local resources (the Javascript engine embedded with the web browser) or remote resources (anything running server-side that produces the output sent to browser).

Incidentally the Web Page approach (one window visible, one web page at a time, in sequence) is very similar to old terminal model Xbase was developed for. And this proved invaluable during the development of DBFree, as we will see later.

DBFree offers different programming models: you can keep everything (data, program logic and GUI elements) on server (a.k.a totally server-side mode) or keep on server only the data and the bare minimum logic, delegating to user's browser (and CPU) most of the work of producing the final page.

By default DBFree V4 offers a mixed-mode that we found to be an effective compromission among server charge, bandwith consumption and performances on browser.

DBFree is also offering a rich-web GUI interface derived from Twitter's Bootstrap (one of the most used on web) that unavoidabily adds another layer of complexity to the code. Is up to you decide if use it or not, but nevertheless the layer is there, even if you don't use it, so arm yourself of some patience and try to get familiar with it.

Bootstrap is an HTML5-CSS3 framework, and it is almost a language by itself. This means that if you intend to use it you will need to learn its sintax and rules, aside some javascript and of course the plain HTML skills you should already have.

This also means that at any given point you will have some 4 different pseudo-languages in the same page to handle, each one operating at a slightly different level.

There is nothing you can do about it: rich-web interfaces todays are a must, expecially because this is the easiest way to make you web app effective and usable on mobile devices. The good news are that DBFree considerably ease yourself into doing this, but this will be covered in deep later.

Web sites and web applications

As we said before anything doing some job done inside a web browser can be seen as a web application: for DBFree this terminology must be sharpened a little.

DBFree runs always one web site at a time (for multiple web sites you will need DBWeb): this one site can be made of a single page (that can do anything you want from nothing to any complex program logic) or from thousands of pages grouped into folders and subfolders nested at will.

Even if you can organize your website hosted by DBFree in any peculiar way comes you to mind, if you are expecting DBFree components other than most basic ones to work you must conform your code to some commonly used specifications and programming rules.

DBFree considers Hosted Web Apps all the collection of pages that follow the DBApp specs and that reside into the APP Root - which is a predefined folder that should be provided with any DBFree-powered site.

Don't worry, the specs are very simple:

Any other combination of pages that do anything but do not fullfill the above requirements are considered as part of the website, not as Web Apps.

This worths a short explanation: we decided that our Web Apps (a.k.a dbApps) must be portables. And portables means that to make them work on another server (that is installed on another host, under another disk letter and domain name) all you have to do is to copy them (i.e. the folder that contains each of them) from one computer to another. And eventualy reset to their default values.

About safety

DBFree uses a drastic approach to safety: almost all the administrative tasks can be done from the server console, but only from there. There is nothing (unless you put it there) to operate from web. This means that to manage the server you must be sitting at its desk or use the Windows own Remote Desktop.

This may sound annoying and imposing severe limitations, but only apparently.

DBFree V4 is born for the cloud, and if you move your servers to the cloud they will be accessible only from a remote access of some kind (mostly RDP), so sooner you get use to it better you will find yourself. And if you're running a server from you own home or office, well, you're already at the console, so you won't notice the difference anyway.

And now consider the good points: your website will as safe as your Windows installation itself. If an intruder wants to break in must break out the operating system at once, not exactly something easy to do. And you will rely on Microsoft security updates, not those of ourselves.

Administrative tasks consists mainly into editing, copying, deleting or moving files inside and outside DBFreeV4 installation folder, being databases, sources or configuration scripts. And backups can be easily demanded to batch scripts and the use of a file compressor, and then scheduled by using Windows own tools.

Administering DBFree can be also be done (partially) using the WAI (Web Administration Interface) but only through a local connection.

As you see there are few ways to breach such a simple system. Basicly the only way is stealing the keys and entering the server room (virtually or phisically). And this is valid for any system in the world, not only DBFree servers.

Web Apps targets

DBFree rely on Bootstrap 3: as such it offers an acceptable compromise of optimization among desktps and mobile devices. The defaults tends to be more mobile-friendly than tailored to large full-HD monitors.

What your Web App cannot do

dbApps are not intended to produce graphics from data, to manage sprites and manipulate images and handle directly the HTTP protocol. You won't directly manage, produce or send massive mail with DBFree, neither serve audio or video streams.

Furthermore, because of safety restrictions imposed by browsers, a Web App cannot write on user's mass memory. This means that you must rely almost always on server storage for anything (with the only exception of cookies and its modern counterpart localStorage, or those that support this feature).

MaxScript is derived from xBase, that was borne for business use, and still follows that path. DBFree is not tailored for general-purpose: it is made to do business applications, not games.


Programming for DBFree

Programming with DBFree means to build Web Apps, and Web Apps are made of web pages.
Thus building Web Apps with DBFree consists before of all in building a web site: the application logic, the MaxScript code and the Data come after.

As we know web pages primarily made of HTML.
Thus you as first thing must acquire a good familiarity with HTML.

Fortunately, at least for the limited scope of this publication, all the HTML you have to know are a bunch of tags that probably you are alredy familiar with:


Structure of a Web App

Here below you see an example of a standard Web Applications for DBFree:


In the example above we see a Web App with a single DBApp.
The Entrypoint of the whole application is the Home Page placed in the Web Root (i.e.c:\maxsis\dbfreev41\web\ (if you're using DBFree V41) or ::\dbw\srv\servername\web\ (if you're using DBWeb) while the only DBApp is reached by using the stock indexer page list_apps.msp (available from Code Assistant).
The DBApp is placed inside the APPS Root (i.e. c:\maxsis\dbfreev41\web\apps\) in its own folder (the App Box). Its entrypoint must have the name start.msp (otherwise it won't be recognised by the indexers) and contain the appropriate header for a DBApp.
The indexer page automatically detects how many boxes there are and produce a link for each of them.
Depending by the implementatios the indexer may also produce some ancillary file that you can the edit for providing a caption and a description of the DBApp that will be shown in the list.
Usually the indexer looks for a file named app-lev.ini (and if it doesn't find it will create it) for establishing an access threshold, anarbitrary value that can be used to determine whether a user may access or not that specific application.

How large is a Web App?

The previous drawing outlined a simple Web App: in the real usage you probably will end up with structures like this or even more complex:


There are no limits on how many pages you can put into an application (let aside the disk space on server).
Keep in mind that a given time only the pages that are actually requested by users are loaded in the server's memory, and many of those will remain in memory only for few milliseconds, thus the linit - for your application - won't be a matter of how many pages there are but how many will be loaded at the same time.
For a normal usage this is not a problem, but for heavy traffic sites it would: fortunately there are advanced tecniques that will unload the server's burden that you, as programmer,can adopt. (But this is not a topic to be discussed here and now).
By now just keep in mind that a large Web App (like DBFree.org) can be made of several thousands of pages without affecting server performance.

But how large can be a page?

Being so big a Web App, how large can be a single web page of an application?
Here we have a limit: a page should remain below 64Kbytes of MaxScript code.
In facts the limit is flexible, because is influenced by many factors (server performances being the first) but 64K of code are quite a lot of stuff if we exclude from the count the HTML content of the page.
Anyway the programming style you adopt can gratly influence both dimension and performances of the page. This is another advanced topic that we are not going to discuss here, but keep in mind that WebObjects of 10 thousand lines are common. ASP or CGI-Style pages, on the other hand, should not exceed 2 or 3 thousand lines.

Structure of a web page

Basically a .msp page for MaxScript is divided in these 6 blocks:
This doesn't differ so much from a normal .htm page:

In both cases the Javascript functions block and the HTML footer block are oprional, thus the only real diference is the Max Header.

This is an example of MaxScript page, divided in the blocks explained above:

<!DOCTYPE html><html>
<% *-- USING ASP MIXED-MODE  
***************************************** MY HEADER
xcLib := mspconfigvar("LIBDIR")+"\free.lib"

set maxlib to &xcLib
//-- switch to enable the web mode (mandatory)
web()
//-- initialize a variable
cSelf := pagename()
****************************************** END HEADER
%>
<!-- this loads the HTML header for an external file //-->
<%=include("/common/header.h")%>
<!-- ############# START OF USER INTERFACE ############# //-->
<body>
<%=container()%>
<h3>Empty Page</h3>
<hr>
<%=button("/home.msp","Home")%>
<%=button("http://dbfree.org","Visit us")%>
<!-- ############# END OF USER INTERFACE ############# //-->  
</body>
<!-- this loads an optional footer from another external file //-->
<%=include("/common/footer.h")%>
</body>
</html>

The page illustrated above is an empty page.

Anyway, even if in the browser the page looks like any other HTML page, under the surface things are very different, and MaxScript has had his work cut:

These operations of automation can relief the programmer from writing and rewriting the same code over and over again on any page.


Standard Web Pages

DBFree is highly modular: it extends MaxScript by using external libraries and predefined components. Before talking about that we want to introduce a standard page, that looks a bit different from what shown before:
Here you see the internal structure of a standard page. It is called standard not only because is standardized, but to distinguish from the more common WebOjcets pages (that we will discuss soon).
DBFree uses Stock components and Parts taken from a common repository.

Usually you can choose between different versions of the same components, with a good chance they will work togheter without need of changes.

Components themselves are mostly made of standard parts ( smaller chunks of code) that could eventually be used elsewhere or to build new components of your own. But let's take a look at some components:

DBFree Header

You can find many headers using the Code Assistant under the section Pages Usually you'll want to use the latest headers (e.g. thise with higher number). Often headers are retro-compatibles among same numeration (i.e. 3.0.0.1 with 3.0.5.3 or 4.0.1.2 with 4.0.1.7).

Here below an example of header:

********************************************* MICRO HEADER V4.0.1.4
library := mspconfigvar("LIBDIR")+"\free.lib"
set maxlib to &library
web()
cSeed := iif(empty(mspfieldvalue("XY")),getSeed(),mspfieldvalue("XY"))
qq := "XY="+cSeed+"&Z="
restoreSession(cSeed)                                  
preload("/common/header.h",cSeed,"XYZ","pagetitle","DBFree "+filebone(pagefile())) 

********************************************* END OF MICRO HEADER V4.0.1.4

Handlers section

Here you will usually place Components and Parts, like these:
'98'8

Database section

xcDbPath := setDb("demo")
if not isdir(xcDbPath)
   maketree(xcDbPath)
endif

xcTable010  := xcDbPath+ "FLOW.DBF"
xcIndex011  := xcDbPath+ "FLOW_IP.MTX"
xcIndex012  := xcDbPath+ "FLOW_SESS.MTX"

if not file(xcTable010)
   aInit( "aField","d_reg","t_reg","ip_addr","sess_id","referer","url","visit_cnt","cargo","l_date","l_time")
   aInit( "aType","D","C","C","C","C","C","N","M","D","C")
   aInit( "aSize",8,10,15,20,80,80,6,10,8,10)
   aInit( "aDec",0,0,0,0,0,0,0,0,0,0,0,0,0)
   create (xcTable010) from aField, aType, aSize, aDec 
endif

use (xcTable010) in 0 alias MASTER  
if used()
   select MASTER  
   if not file(xcIndex011)
      index on IP_ADDR to (xcIndex011)
   endif
   if not file(xcIndex012)
      index on SESS_ID to (xcIndex012)
   endif
endif

Programming for Web Pages

Among the different programming styles and models adopted in the past years the most practical (and recent) are basically the Hybrid and the WebObject models.
DBFree offers the maximum freedom of choice under this aspect, but you'll get the most out of DBFree V41 by adopting one of these (or building your own custom variant using them as foundations).

Hybrid model

WebObject model

(You may find more accurate informations about this topic int the DBFree documentation available on other sections of this site.)

Creating your first Web App


a - How to create a sample Web App

Better way to learn about building DBFree Web Apps is to start one from scratch and use it in place of the existing Companion Site that is supplied with every installation of DBFree. Of course this will be visible only on your workstation and only when visiting localhost:8088 (or whatever URL you assigned to it) unless you already configured DBFree and its host PC to act as a server on onternet or you LAN/VPN.

a1 - General outline of a web application

The default location of the Web Root is c:\maxsis\dbfreev41\web (determined by the Civet configuration file) while the default location for databases is c:\maxsis\dbfreev41\db (determined by DBFree general settings andfrom the global variable _DATADIR)
Since the DB Root path is external to the Web Root at this stage it won't be accessible from outside your PC (Intranet or Internet), thus your data are safe, at least as much as it is the system as a whole (meaning for system your entire PC, Operating Sysytem and other software installed).

Safety of a server is a complex topic we are not going to introduce now. DBFree as fresh installation is safe as a rock, because is not exposed to internet or to your intranet (unless you voluntarily did so), thus it is not a concern now. For safety measures to adopt on a production server see separate documentation.


a2 - What you will need

This information refers only to DBFree V4.1 (it may also apply to V4.0 but it is not guaranteed to work).
All you will need is to have DBFree installed and to keep the Code Assistant Service page of DBFree.org web site open on your desktop.

Step 1 - preparing DBFree

From the Control Center
  1. Click on Open web root
  2. Navigate to its upper folder (i.e. c:\dbfreev41)
  3. Rename your actual WEB folder to something else (i.e. WEB1)
  4. Create a new folder and name it WEB (like the previous one)

Step 2 - getting the framework

Download, from this section of the Assistant, the following compressed files:
  1. css.zip : contains the folder with all the CSS you will use in your web app.
  2. js.zip : contains the folder with jQuery, Bootstrap and jMax javascripts.
  3. common.zip : contains the basic files of the DBFree Application Framework.
You can store these files somewhere or use them immediately opening them from browser. We suggest to store it for later re-use.
(As alternative you can simply copy the existing folders css, js and common from older web to the new one)

Step 3 - preparing the ground

Open the new web folder, that is empty. Now you should populate it by uncompressing the zip files you downloaded and extract the folders they contain, so to create this tree structure:
c:\-+--DBFreeV41--+         +-- common
                  |         |
                  +-- WEB--+-- css
                            |
                            +-- js
Check to have correctly unzipped all files of each folder.
Now the basic framework for your new application/web site is ready to accept the web pages.

Step 4 - Adding web pages

Download the following compressed files:
  1. webroot_files.zip : contains the WEB entrypoint file and some other to populate your app.
  2. images_kit.zip - contains the image folder with some icons and images that can be useful.
Repeate the process of uncompressing so to have this final structure:
c:\-+--DBFreeV41--+        +-- common
                  +--WEB---+-- css
                            +-- js
                            +-- images
                            +
                            home.msp (ecc)
DBFree code is highly modular: for example have a look a the internal structure of the home page

.

Your new Web App is now ready for customization.

a3 - Customizing

By far, the simplest way of customizing your application is to add first the static contents and only then, once you are satisfied of the look of your pages, proceed
with developing the code to provide live data.
Editing pages is simple: it can be done by double-clicking on the file (i.e. the home page we have here in our new site): if you have installed DBFree correctly you should see the page opening into PSPad editor.
If this does not happens you should set the files with .msp extension to be always opened by using PSPad using Windows own procedure.

Of course a web application is seldom implemented by using a single page (even if is not so uncommon as it may seems), so sooner or later you will need to add some toher pages. This is easy.


Step 5 - Adding new web pages

The standard procedure to add pages is this:
  1. right-click on the WEB folder
  2. from context menu choose New Text Document
  3. change the default name to desired one and the extension from .txt to .msp
  4. Go to Code Assistant and choose a page template that fits for the intended use of the page (i.e. 4017-STD page template)
  5. copy from the template and paste into your newly created page
  6. save the page and start editing (i.e. put a link to go from this new page back to home page)
Don't forget to go to your home page and add a link to the new page.

a4 - Where to get help with HTML

HTML5 is reach of options and opens lot of possibilities. Too many to memorize them all.
We suggest you to keep a window open on w3schools.com for getting a quick help on HTML (and Javasript) syntax and tag features.
You may also find useful information on DBFree.org using the Code Assistant.

a5 - From a simple web to a Web App

If you followed the instructions so far you should have a web fully working, made out of dynamic pages, but that does nothing more than a static, classic web site.
So far you just spared some time comapred to building it piece-by-piece by hand but substantially it seems the web site does the same job.
In facts there is a difference: if you click on List of files of this folder you will get a self-updating list. It means you don't have to update manually each and every link everytime you add a page or change its name.
It's not bad, but of course we expect much more from our efforts and to justify the hassle to install a language for the web. Well, this is not even a foretaste of what DBFree can do.

a6 - Adding features

To really see the difference you should add some other components to your web:
Download, always from this same section, the compressed file:app_folder_kit.zip.
Do the usual process of uncompressing so to have this final structure:
                           +-- APPS----- (subfolders)
                           |     
c:\-+-DBFreeV41--+        +-- common  
                  +--WEB--+-- css      
                           +-- js     
                           +-- images          
                           +
                           home.msp (etc)
Now refresh your home page: if you did everythng well you should see that a new button appeared: List availabel DBApps.

a7 - Building DBApps

Still from Windows, double click on the newly added APP folder and open it:
  1. Right-click and from context menu choose New Folder
  2. Name your newly created folder something like MyFirstApp (or anything else, but avoid blank spaces)
  3. Open the new folder and create, with same system, a new text file then name it start.msp
The final structure should be something like this:
                            +-- APPS------------+--list_apps.msp
                           |                    |
c:\-+-DBFreeV41--+        +-- common          +-- MyFirstApp--+--start.msp 
                  +--WEB--+-- css                              | 
                           +-- js                               +-- (other files)
                           +-- images          
                           +
                           home.msp (etc)
Now if you click on List availabel DBApps in your Home Page you'll see a menu and your new DBApp listed.

Now, by beginning editing this new start page you are ready for developing. This means adding the correct header, the code and all the program logic you'll need until you'll have the application doing what you plan to make it do.

But starting from a blank page is not the easiest way, isn't it?

Step 6 - Adding a pre-built DBApp

Having something to start from may really be of great help.
  1. Download the compressed file:Demo_DBApp.zip.
  2. The file contains a folder: uncompress it into your APPS folder
  3. Come back to click on List availabel DBApps
  4. Click on the button to launch the application
                            +-- APPS------------+--list_apps.msp
                           |                    |
c:\-+-DBFreeV41--+        +-- common          +-- yourApp1---start.msp (etc)
                  +--WEB--+-- css             +-- yourApp2---start.msp
                           +-- js              +-- (etc)
                           +-- images          
                           +
                           home.msp (etc)
Now you have a working demo application to study and use as inspiration. And eventually start modifiying to see what happens.

a - Summarizing

After all the steps followed so far you should have your canvas ready. The next step is complete the application, that will follow this overall scheme:
(Notice that names above are are only a suggestion. You may change them with your own, but for the purposes of this tutorial we suggested to leave them.)

b - Modifying your Web App

Before to start writing your own code it's better to have a general understanding of the organization of the hosting environment.

b1 -Home page

The home page of your web application is responsible of initializing the whole thing by mean of the MAX Header that sits on top.
The header does the followings:
  1. loads the necessary library (there are many of them, for special purposes and different versions of DBX family of products: in this case we use a generic one ideal for DBFree)
  2. initializes the global variables that holds the values that apply to any page and for all users (the common parameters for all the application, like folders to use and the like)
  3. initializes (or recall) the user's sessions that keeps isolated the variables of the same names that you use in the code from one user to another.
  4. sets the database driver to use (in this case the proprietary MaxScript engine): as you may suspect MaxScript can work with different databases, but DBFree usually supports only the proprietary one. With this driver you can use Clipper and FoxPro indexes. DBase and ODBC are only supported using optional drivers.
  5. check if the folders necessary to the application exists and in case creates them
  6. check for incoming parameters (WebVars) and stores their values into memory (local) variables to be used with MaxScript

b1 - Structure of a generic web page

Basically a .msp page for MaxScript is divided in these 6 blocks:
This doesn't differ so much from a normal .htm page:
In both cases the Javascript functions block and the HTML footer block are optional, thus the only real difference is the Max Header.

This is an example of MaxScript page, divided in the blocks explained above:

<!DOCTYPE html><html>
<% *-- USING ASP MIXED-MODE  
***************************************** MY HEADER
xcLib := mspconfigvar("LIBDIR")+"\free.lib"

set maxlib to &xcLib
//-- switch to enable the web mode (mandatory)
web()
//-- initialize a variable
cSelf := pagename()
****************************************** END HEADER
%>
<!-- this loads the HTML header for an external file //-->
<%=include("/common/header.h")%>
<!-- ############# START OF USER INTERFACE ############# //-->
<body>
<%=container()%>
<h3>Empty Page</h3>
<hr>
<%=button("/home.msp","Home")%>
<%=button("http://dbfree.org","Visit us")%>
<!-- ############# END OF USER INTERFACE ############# //-->  
</body>
<!-- this loads an optional footer from another external file //-->
<%=include("/common/footer.h")%>
</body>
</html>

The page illustrated above is an empty page.

Anyway, even if in the browser the page looks like any other HTML page, under the surface things are very different, and MaxScript has had his work cut:

These operations of automation can relief the programmer from writing and rewriting the same code over and over again on any page.


b2 - Standard Web Pages

DBFree is highly modular: it extends MaxScript by using external libraries and predefined components. Before talking about that we want to introduce a standard page, that looks a bit different from what shown before:
Here you see the internal structure of a standard page. It is called standard not only because is standardized, but to distinguish from the more common WebOjcets pages (that we will discuss soon).
DBFree uses Stock components and Parts taken from a common repository.

Usually you can choose between different versions of the same components, with a good chance they will work togheter without need of changes.

Components themselves are mostly made of standard parts ( smaller chunks of code) that could eventually be used elsewhere or to build new components of your own. But let's take a look at one of this component:

b3 - Database section

xcDbPath := setDb("demo")
if not isdir(xcDbPath)
   maketree(xcDbPath)
endif

xcTable010  := xcDbPath+ "FLOW.DBF"
xcIndex011  := xcDbPath+ "FLOW_IP.MTX"
xcIndex012  := xcDbPath+ "FLOW_SESS.MTX"

if not file(xcTable010)
   aInit( "aField","d_reg","t_reg","ip_addr","sess_id","referer","url","visit_cnt","cargo","l_date","l_time")
   aInit( "aType","D","C","C","C","C","C","N","M","D","C")
   aInit( "aSize",8,10,15,20,80,80,6,10,8,10)
   aInit( "aDec",0,0,0,0,0,0,0,0,0,0,0,0,0)
   create (xcTable010) from aField, aType, aSize, aDec 
endif

use (xcTable010) in 0 alias MASTER  
if used()
   select MASTER  
   if not file(xcIndex011)
      index on IP_ADDR to (xcIndex011)
   endif
   if not file(xcIndex012)
      index on SESS_ID to (xcIndex012)
   endif
endif

 


b4 - Session handling

Session handling would require an entire chapter to be explained: fortunately you don't need to know all details (at least not straight away) and all you need to know is that for preserving the values of variables you will have to use the seeds.
cSeed := getseed()

What is a seed?

The seed is only a number, generated by the server, that identifies univocally a given user and its connection. This number is assigned automatically whem the users connect (via their browsers) the first time and then it is stored into browser's memory.
DBFree V41 uses a feature of modern web browsers HTML5 compliant (the vast majority) called local storage to accomplish this task.

This feature consents to store arbitrary values into browser's storage system without using a cookie and is by far the most efficient method to identify an user that connects from internet.


b5 - How do you will use seeds?

You should pass the seed to any page below your home page.
There are two basic methods to do that: We are not going to discuss this topic here: just keep in mind that even if you don't pass the seed the code in the DBFree headers will try to recover it automatically, so - in theory - you could omit to pass the seed from one page to another and rely to the automatisms.
Anyway, considered the many browsers and versions crawling around the web, it's better to use seeds whenever possible (or adopt more advanced techniques not discussed here).
 

b6 - Structure of Web App


C - Building a simple DBApp

This kind of application is to be installed as subsystem of an existing DBFree Web Application (a full Web Site) and can not run alone.
It must be completely contained in a subfolder to place under APPS folder of the host application.
There are basically two sub-models (variants): DBFree V4.1 supports only the Adaptive Interface, that is a compromise between the conflicting demands of wide screens of desktop computers and the vertical orientation common on most mobiles.
1

c1 - Create the App Box (the folder for your DbApp)

Building DBApps is considerably simpler than building an entire new Web App.
DBApps rely on the existing DBFree framework of the host (the default companion site) and inherits its current configuration.
All you have to do to start developing a DBApp from scratch is to open the App Root and add a new App Box (that is  create a new subfolder under the folder APPS) and then add a starter page (that is any page named start.msp.This can be done directly from Windows desktop with usual procedures (you won't need a code editor or any tool for that).

Depending from the distro version (and the companion you're using) the look of the home page may vary, but usually all of them provide some kind of automated link to the DBApps installed (i.e. they look into APPS folder for any subfolder containing a file named start.msp, and create a link for it).
Notice that you don't need to keep the actual aspect of the home page: you can chage it anyway you like to reflect the scope of your application as soon as you provide yourself the necessary link to APPS folder and its indexer page (or to the individual APPS you will place there).


2

c2 - Create an entrypoint

Once you have your new empty file named start.msp (which is the entrypoint of you DBApp) you must start adding the code to it:
you don't need to write everything from scratch. MaxScript pages are modular so most of the code you need can be taken from this repository.
For an entrypoiny page like the on we are considering the best choice is to take the entire page from a template and paste it as-is.
You will find what you need in the section Basic Templates: just choose one of the APP Entrypoint pages.

3

c3 - Create the pages

Now is time to create the pages that will implement the logic of your application:
Just create an empty file for each of them, then add the right header and then the basic parts that you need.
Parts are standardized chunks of code that perform common tasks:you find them under the section Page Parts.
You will need to choose the parts you need in this order:
  1. Max Header - from Headers
  2. Standard WebVars
  3. Background MaxScript actions (optional)
  4. HTML shared header
  5. HTML body
  6. User Interface Components - from User Interface Components
  7. Foreground MaxScript actions (optional)
  8. HTML shared footer (optional)
  9. Local MaxScript procedures (if any)
  10. User Defined Functions (if any)

c4 - An example

Here it is an example of single-page DBApp:
Hide/Show code


Conclusions

We hope this publication has been useful for you,
For a more detailed discussion of DBApps please read Creating_a_new_DBApp from Quick Start section.
For other topics of creating a web app read the other documents of this section.
To go deeper on DBFree, please consult the specific publications available on this site.

 


Top of pageNext Chapter