Database Elements

Content Database elements are usualy used to store the content of a special part of a page to be generated. Server API Function calls can be inlined in templates, elements and application functions to access the element name, attributes, content and permission.

Elements may be self or pre defined somewhat like in XML. They are inserted into the appropriate templates by the page generation mechanism. For each element an element callback function may be defined.

Please notice the difference between document language elements and database elements stored in the database. If the document language elements and the database elements matches, you can query the SQL database for the language elements!

Accessing Page Elements

Page elements may be accessed via the following function calls. The element functions takes parameters of the form 'parameter name' => 'parameter value':

ElementName

Returns the name of the $i's element

my $ElementName = $Page->ElementName ('Number' => $i);

ElementAttribute

Returns the attribute of the $i's element

my $Attribute = $Page-> ElementAttribute ('Number'=> $i);

ElementContent

Returns the content of the $i's element

my $Text = $Page->ElementContent ('type' => 'parsed', 'Number'=> $i);

For example, you can put the following code in a template. If the 'Number' paramter is omited, all elements of this name are displayed.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>

@{[
$self->ElementContent ('Name' => 'Head', 'Number' => 1)
}] 

</HEAD>
...
...

Element Generation Mainloop

The document generation actually takes place in a page generation main loop. When implementing a sites surface, the generation loops of the related templates must be designed to meet the particular requirement. At this point you may have a look at the ProcessApplication.pm file of the Test server, which is included in this distribution (/maxscape/server/Test/lib/perl/Maxscape/ProcessApplication.pm). The file contains the following example main loop, to generate the content from the page elements using the server API:


sub printElements {
  my ($Page) = @_;
  my $i = 0;
  my $Text = '';
  my $ElementName = '';

  while (defined ($ElementName = $Page->ElementName ('Number' => $i))) {
    if ($ElementName eq 'Text') {
      $Text .= $Page->ElementContent ('Number' => $i);
    } elsif ($ElementName eq 'parsedText') {
      $Text .= $Page->ElementContent ('Type'    => 'parsed',
                                      'Number'  => $i);
    }
    $i++;
  }
  return $Text;
}

Element Callbacks

Element callback functions are executed immediately after the element database lookup. They are bound to the database element names and takes the element attributes and content as the functions parameter.

sub processElement  {
  my $self = shift;
  my $Elements = @_;

  if (${$Elements}{ELEMENT_NAME} eq 'secret') {
    ${$Elements}{ELEMENT_CONTENT} = '';
  }
}

Maxscape::Elements Package

Maxscape::Element Package

Member Functions

Synopsis

use Maxscape::Elements;

Description

The maXscape Maxscape::Elements package supplies the basic functionality to deal with Maxscape database elements.

Examples

new

Synopsis

my $Element = Maxscape::Elements->new ( %P );

Description

Creates a new 'Element' object. Within the runtime system, there is normaly no need to create such an object, cause one is created as a member of the 'Maxscape::Page' object.

Examples

my $Element = Maxscape::Elements->new (Cursor  => $self->{Cursor},
                                       Context => $self->{Context}
);

ElementTableName

Synopsis

my $TableName = $Elements->ElementTableName ($NodeType, $PageGeneration);

Description

fetchElementsByPageNumber

Synopsis

my $ElementList = $Elements->fetchElementsByPageNumber (
                    TableName   => 'TEMPLATES', # default is ELEMENTS
                    PageNumber  => $PageNumber,
                    ElementName => 'Text',
);

Description

Fetches the elements of a page by the given page number.

Examples

my $PageCategory = '/Templates/DB-Template/UserTemplate';
my $PageName     = 'SongList';

my ($PageNumber) = $Page->NodePathToNumber ($PageCategory, $PageName, 'Template');

my $Elements = Maxscape::Elements->new (Cursor => $Page->{Cursor});

my $ElementList = $Elements->fetchElementsByPageNumber (PageNumber => $PageNumber,
                                                        TableName  => 'TEMPLATES',);
my $Text = qq(Element[0]=${$ElementList}[0][0].);

changeElementContentByPageNumberElementName

Synopsis

my $Text = $Page->changeElementContentByPageNumberElementName
                            ($TableName, $PageNumber, $ElementName, $ElementContent);

Description

deleteElementsByNumber

Synopsis

$Elements->deleteElementsByNumber ($TableName, $PageNumber,
                                   $MinElementNr, $MaxElementNr);

Description

openElementFile

Synopsis

$Elements->deleteElementsByNumber ($FileName);

Description

closeElementFile

Synopsis

$Text .= $Element->closeElementFile($FileHandleName);

Description

Not needed, closed already called in 'importElementsFromFile'?

importElementsFromFile

Synopsis

    $Text. = $Element->importElementsFromFile(
               'FileHandleName'      => $self->{CGI}->{uploadFile},
               'TableName'           => $ElementTableName,
               'PageNumber'          => $PageNumber,
               'ElementName'         => $ElementName,
               'ElementAttribute'    => $ElementAttribute,
               'startElementNumber'  => $ElementNumber);

Description

addElement

Synopsis

$ErrorText = $Element->addElement ($TableName,
               $NODE_NUMBER,$ELEMENT_NUMBER,$ELEMENT_VERSION,$LANGUAGE,
               $ELEMENT_NAME, $ELEMENT_ATTRIBUTE, $ELEMENT_CONTENT, $ELEMENT_GROUP
);

Description

Inserts an element to a page. Return an error text on failure, else returns an empty string. Is the same as the insertElement method.

insertElement

Synopsis

$ErrorText = $Element->insertElement ($TableName,
               $NODE_NUMBER,$ELEMENT_NUMBER,$ELEMENT_VERSION,$LANGUAGE,
               $ELEMENT_NAME, $ELEMENT_ATTRIBUTE, $ELEMENT_CONTENT, $ELEMENT_GROUP
);

Description

Inserts an element to a page. Return an error text on failure, else returns an empty string.

countElements

Synopsis

$ElementNumber = $Element->countElements( %P );

Description

Counts the elements of a page.

Examples

$ElementNumber = $Element->countElements ( TableName     => 'ELEMENTS',
                                           PageNumber    => $PageNumber,);

getElements

Synopsis

$ElementList = $Element->getElements( %P );

Description

Examples

$ElementListRef = $Element->getElements( PageNumber    => $PageNumber,
                                      ElementNumber => $ElementNumber,
                                      #ElementName   => $ElementName,
);

$ElementListRef = $Page->{Elements}->getElements (
                                       Cursor        => $self->{Cursor},
                                       PageNumber    => $PageNumber,
                                       ElementNumber => $ElementNumber,
);

getElementsByNodePath

Synopsis

$ElementList = $Element->getElementsByNodePath ( %P );

Description

Gets an element of a node by the node's category and name.

Examples

my $ElementListRef = $Element->getElementsByNodePath(
                                # Cursor        => $self->{Cursor},
                                NodeCategory  => $NodeCategory,
                                NodeName      => $NodeName,
                                # ElementNumber => $ElementNumber,
                                ElementName   => $ElementName,
);
my $ElementContent = ${$ElementListRef}[0]{ELEMENT_CONTENT};
my $Text = $ElementContent;

changeElementContent

Synopsis

$ElementList = $Element->changeElementContent (
                 PageNumber    => $PageNumber,
                 ElementNumber => $ElementNumber,
                 Content       => '',
);

Description

changeElementAttribute

Synopsis

$ElementList = $Element->changeElementAttribute (
                 PageNumber    => $PageNumber,
                 ElementNumber => $ElementNumber,
                 Attribute     => '',
);

Description

ElementsAsHTML

Synopsis

$ElementList = $Element->ElementsAsHTML ();

Description

ElementAsHTML

Synopsis

$ElementList = $Element->ElementAsHTML ();

Description

ElementAsHTMLFilter

Synopsis

$ElementList = $Element->ElementAsHTMLFilter ();

Description

splitLink

Synopsis

$ElementList = $Element->splitLink ();

Description

URLisRelative

Synopsis

$ElementList = $Element->URLisRelative ();

Description

splitPath

Synopsis

$ElementList = $Element->splitPath ();

Description

lookupElements

Synopsis

$ElementList = $Elements->lookupElements ();

Description

Looks up and fetches the elements of the current page.

IndexBody

Synopsis

$ElementList = $Element->IndexBody ();

Description

Synopsis

use Maxscape::Element;

Description

The maXscape Maxscape::Element package supplies the basic functionality to deal with a single element.

Examples

new

Synopsis

my $Element = Maxscape::Element->new ();

Description

Creates a new 'Element' object.