Skip to content

Latest commit

 

History

History
259 lines (157 loc) · 8.37 KB

README_EN.md

File metadata and controls

259 lines (157 loc) · 8.37 KB
Raw

SpiderBite

This english translation was kindly provided to me by Robert A. Rioja. 🌼

Something on my own behalf

If you like my work, I would be happy if you would support me with a small donation.

What the hell is this?

SpiderBite is a preprocessor for SpiderBasic that allows you to mark areas in a code that are executed on the web server, the so-called server code as PB2Web users know it.

As known, the code generated by SpiderBasic cannot, and must not, directly access the hardware of the web server.

Thus, it is not possible to execute direct database queries, file system accesses or anything else from SpiderBasic.

The procedure so far is to program a server-side component, be it as CGI or PHP (ASP, Python, ...) script, and then call this component in SpiderBasic using HttpRequest(). That actually works quite well, but in my opinion it's not very comfortable.

For this reason I decided to develop SpiderBite.

A simple example

EnablePbCgi

  ; The code in this block is executed on the server.

  ProcedureDLL.s myPbCgiProcedure()
    ProcedureReturn "Hello from myPbCgiProcedure"
  EndProcedure

DisablePbCgi

Debug myPbCgiProcedure()

The code noted above in the EnablePbCgi/DisablePbCgi block is extracted by SpiderBite before the actual conversion process and compiled into its own PureBasic executable (a so-called CGI-EXE), which is then executed on the server. The entire PureBasic command set is available in the ServerCode block.

Besides the ability to create PureBasic CGI, block areas for PHP, ASP and ASPX are also available. An example for PHP:

EnablePHP
  
  ProcedureDLL myPhpProcedure()
    ! return "Hello from myPhpProcedure";
  EndProcedure
  
DisablePHP

Debug myPhpProcedure()

The PHP commands are marked with a leading exclamation mark.

It is possible to use different block areas in one source (here: PbCgi and PHP):

EnablePbCgi
  ProcedureDLL.s myPbCgiProcedure()
    ProcedureReturn "Hello from myPbCgiProcedure"
  EndProcedure
DisablePbCgi

EnablePHP
  ProcedureDLL.s myPhpProcedure()
    ! return "Hello from myPhpProcedure";
  EndProcedure
DisablePHP

Debug myPbCgiProcedure()
Debug myPhpProcedure()

Block areas for NodeJs and Python are planned.

System Requirements

  • SpiderBasic

  • PureBasic (to compile the sources and in case PB Cgi should be created)

  • Any web server (Apache, IIS, nginx, ...)

Installation

GitHub connoisseurs clone this project on your data carrier to a place of their choice. People who are not familiar with GitHub can download the sources as ZIP:

Then the PB sources (SpiderBite.pb, SpiderBiteAfterCreateApp.pb and SpiderBiteConfig.pb) must be compiled with PureBasic and set up as tools in SpiderBasic.

Set up SpiderBite as SpiderBasic Tools

After the sources have been compiled, SpiderBite is installed as SpiderBasic tools. Make sure that "%COMPILEFILE" is specified as the transfer parameter. The two checkboxes "Wait until tool quits" and "Hide tool from the Main menu" should also be activated.

Before Compile / Run

This tool comes into action when Compile/Run is called in SpiderBasic. So every time <F5> is pressed.

Before Create App

This tool comes into action when in SpiderBasic Create App... is called to create an app.

After Create App

Important! Due to a bug in SpiderBasic, the generated temp file is not used as basis for the app to be created, but the original source. Until this bug is fixed, some tricks have to be done here and a separate program (SpiderBiteAfterCreateApp.exe) has to be set up as a tool.

And so it looks then, if all tools are correctly registered:

SpiderBiteConfig

With SpiderBiteConfig profiles can be created, which are then specified in the SpiderBase code:

For example, if you want to create a PureBasic CGI, you have to specify in SpiderBiteConfig where the PureBasic compiler is located. Furthermore you have to specify where the CGI should be stored (PbCgiServerFilename) and how it can be called from the browser (PbCgiServerAddress). Finally, a template can be selected, which is used as a basis for the CGI to be created. If no template is specified, a standard template is used.

Furthermore the file SpiderBite.sbi must be included. It is located in the include folder.

XIncludeFile "[PathTo]/SpiderBite.sbi"

#SpiderBite_Profile = "default" ; here the profile is specified

EnablePbCgi
  ProcedureDLL.s myPbCgiProcedure()
    ProcedureReturn "Hello from myPbCgiProcedure"
  EndProcedure
DisablePbCgi

Debug myPbCgiProcedure()

Alternatively the file SpiderBite.res can be copied into the Residents folder of SpiderBasic.

SpiderBiteConfig can optionally also be installed as a tool to manage the configurations comfortably from SpiderBasic.

Synchronous Communication vs Asynchronous Communication

SpiderBite uses Ajax calls for communication between client (browser) and server. These can be synchronous and asynchronous.

The advantage of a synchronous call is that the return value is available in the same line in which the function is called.

Synchronous call:

Enable*
  ProcedureDLL.s myProcedure()
    ProcedureReturn "Hello World"
  EndProcedure
Disable*

Debug myProcedure() ; here the return can be evaluated.

The disadvantage of a synchronous call is that the code waits in the line of the call until the server returns the return value.

This can cause the browser to stop responding if the server takes too long to return the return value (for example, if the connection between client and server is poor, or if procedures run for long periods of time).

For this reason, it is recommended to use asynchronous calls. Although this results in more programming effort, it results in a browser that reacts at all times.

An asynchronous call occurs if the client code contains a procedure with the same name and an attached Callback:

Server-Code: myProcedure()

Client-Code: myProcedureCallback()

An asynchronous call would accordingly look like this:

Procedure myProcedureCallback(Success, Result.s)
  Debug Result ; hier wird der Rückgabewert des Aufrufes
               ; myProcedure() geliefert.
EndProcedure

Enable*
  ProcedureDLL.s myProcedure()
    ProcedureReturn "Hello World"
  EndProcedure
Disable*

myProcedure() ; no return value is returned here!

If 1=2
  myProcedureCallback(0, "") ; a 'blind' call
EndIf

Important: SpiderBasic optimizes the code. Unused procedures are not compiled. Since SpiderBite replaces the myProcedureCallback call in the ServerCode block with an Ajax call, SpiderBasic 'thinks' that the procedure will not be called. As a result, it is removed by SpiderBasic. For this reason, we must simulate the call elsewhere:

If 1=2
  myProcedureCallback(0, "") ; a 'blind' call
EndIf

Public and private procedures

Starting with version 01.10.2017, a distinction is made between public and private procedures. Public procedures can be called on the client side, private procedures cannot.

Public procedures are specified with ProcedureDLL().

Private procedures are specified with Procedure().

Example:

EnablePbCgi

  Procedure.s myPrivateProcedure()
    ProcedureReturn "Hello from myPrivateProcedure"
  EndProcedure
  
  ProcedureDLL.s myPublicProcedure()
    ProcedureReturn "Hello from myPublicProcedure"
  EndProcedure
  
DisablePbCgi

Debug myPublicProcedure()

Debug myPrivateProcedure() ; this will generate the error 'myPrivateProcedure() is not a function, array, list, map or macro.'

Templates

{ToDo}

ToDo

  • Currently, only simple transfer parameters (strings and numbers) are allowed.

  • ServerCode is currently not included in included ((X)IncludeFile()) files are processed.

Any questions? Suggestions? Error messages?

SpiderBasic-Forum (englisch)

SpiderBasic-Forum (german)

License

MIT

Something on my own behalf

If you like my work, I would be happy if you would support me with a small donation.