Maxscape Class Library

The Maxscape class library implements the generic functionality to dynamically generate content stored in the Content Database and on the file system.

The objects of the run time system provide the data and methods that are required to answer a client request. CGI variables, node context information, viewer related data, as well as the node elements stored in the database or on the file system can be accessed via the class library API.

As of 27.10.2020 she comprises 81 packages with 1544 methods, 92434 Lines of Perl Code with rudimentary documentation in 98 module files.

The API provides the context, document, template, element and other data in an object oriented way. The library implements a layer between the application and the run time system, so that application code doesn't need to care where it and its content is stored. The hierarchically ordered node tree of the Content Database is simply accessed via the server objects.

Applications use the run time objects via their variables and by calling member functions of the application server's run time objects.

sub MyApplicationFunction {
  my $Page = shift;

  my $ElementName    = $Page->CGI->Query ('ElementName');

  my $ElementContent = $Page->ElementContent (Name => $ElementName,
                                              Type => 'execute');

  return "ElementName=$ElementName, ElementContent=$ElementContent.";
}

The Type parameter of the ElementContent method tells the function to execute the Perl code that is stored in the element content field. Application functions return text to the page generation loop and must not print to STDOUT directly.

Maxscape::Process Class

The purpose of the Maxscape::Process container class is to abstract from the environment and process type they are actual running in. Therefor it is transparent to application server and application code if it lives as a CGI, FastCGI, DCGI, SCGI, a.s.o. type of process.

package Maxscape::Process;

sub execute {
  my ($Process, $Request, $ClientConnection) = @_;

  my ($Context, $User) = $Process->acceptRequest ($Request, $ClientConnection);

  my $Response = Maxscape::HTTP::Response->new;

  $Context->lookupPage ($Response);

  my $Page = Maxscape::Page->new (Request  => $Request,
                                  Context  => $Context,
                                  User     => $User,
                                  Response => $Response,);
  $Response->{Content} = $Page->Document();

  return $Response;
}

Maxscape::Page Class

The Maxscape::Page class contains the node related data and context information and serves as a container for the Maxscape::CGI, Maxscape::Context, Maxscape::Menu, Maxscape::User, Maxscape::Elements, etc. classes of the library. A $Page object is created when the server receives a request from a client and passed through the functions of the content generation loop gathering the data and methods to execute the wanted services and generates the response, that the server then sends back to the client.

As you can see in the example below, the $Page object can be used to retrieve the database elements with the name $ElementName. The content of Elements with a Type='parsed' parameter are evaluated my the Perl interpreter.

package MyModulePackage::MyApplication;
...
sub myMethod {
  my ($self, $Page) = @_;

  my $ElementName = $Page->CGI->Query('ElementName');
  ...
  my $Text = $Page->ElementContent (Name => $ElementName, Type => 'parsed');
  ...
  return $Text;
}
...

Element representation in the Content Databases ELEMENT table is e.g.:

Page number:       1000000
Element number:    100
Element name:      Text
Element attribute: Type="parsed"
Element content:   Some Text with embedded Perl code evaluated by the Perl interpreter,
Element language:  en
...

Maxscape::Page Class Usage in Applications

Using the Maxscape::Page class in applications is easy. Simply access the variables and invoke the methods of the $Page run time object. Either write Perl code that returns a text or embed the code in a piece of text that is evaluated by the Perl interpreter. The storage location is almost completely transparent to the application. Application modules are best placed in the related application module folders and integrated via the application process plugin mechanism.

Application code can be stored or included in process local, as well as in application server and site global files located in the lib folder of each application server. Application packages are simply included with the Perl 'use MyModulePrefix::MyModule;' statement. Applications functions look somewhat like:

# File: /maxscape/server/'AppServer'/lib/perl/Maxscape/ProcessApplication.pm
...
use MyModulePrefix::MyModule;

sub myFunction {
  my ($Page) = @_;

  my $MyModuleObject = MyModulePrefix::MyModule->new;

  return $MyModuleObject->workout ($Page->ElementContent ('Title'));
}
...

The $Page parameter taken by the function is the $Page object containing further server objects like CGI, Context, User, Elements, etc. as members.

You may also explicitly define your method to be in the Maxscape::Page class by issuing a package statement in your module file. Then your application function becomes a method of the $Page class.

package Maxscape::Page;

sub myPageMemberFunction {
  my ($Page) = @_;
  ...
  return 'Its me.';
}

# To call this function, you say:

my $Text = $Page->myPageMemberFunction( ... );

Creating, Addressing and Executing Applications

Application objects can be created and executed at various stages of the generation loop either via callbacks or directly within the content of a requested page. To address the location of a node in the Content Tree the Category and Page CGI variables are used, somewhat like pointing to files of a directories tree, although the destination path is split into the path of the pages category and name.

The URL: http://maxscape.com/?Category=/Profile/Scripting&Page=Index

addresses the Index page of the node tree in the Content Database:

/                 # root category
  Profile         # root sub category
    Scripting     # profile sub category
      Index       # page node
        Elements  # page elements

Embedding Applications in Elements and Templates

Variables are directly embedded in the (HTML) text and functions are executed via Perl closures.

<html>
...
Hey @{[ $Page->User->UserId ]}, it is the @{[ $::WebServer->TimeAsString ]}.
..
</html>

Text, HTML tags, variables and method calls can feely be intemixed. The
output is:

Hey Public, it is the 2024-11-28 13:39:37.