Context Package

Maxscape::Context Package

Member Functions

_initialClientRequestCallback
addQueryParameterToMe
Category
CategoryBasename
ClientType
ContentType
CreationTime
decodeCategory
fetchPageHierarchy
fetchPageLevelNodesAndHierarchy
findPageIndexInHashOfLists
findPageInListOfHashs
firstCategoryLevel
GroupClause
GroupId
HierarchyCategory
HierarchyPathToWhereClause
initialClientRequestCallback
lastModificationTime
lookupCurrentCategories
lookupPage
Me
new
NodeExist
NodeType
Page
PageGroup
PageGroups
PageName
PageNumber
PageOwner
PagePermission
PageType
ParentCategory
PathToList
popParentCategory
QueryNodeByNumber
QueryNodeByNumberHash
QueryNodeByPath
QueryNodeNumberByPath
QueryNodeTypeByNumber
QueryNumberOfSubNodesByPageNumber
QueryNumberOfSubNodesByPath
registerUser
SCRIPT_URI
SCRIPT_URI_Method
setContext
SqlClauseArraytoString
StringToWhereClause
TemplateName
TemplateNumber
TemplateType
UserGroupToWhereClause
UserId
UserIsAllowed
UsersInGroupsWhereClause

Synopsis

use Maxscape::Context;

Description

The 'Context' package is used to provide the context, in which a page is generated. Usualy, it is a member of the 'Page' object ($Page->{Context}). Besides the data from the 'PAGE' database table, a 'Context' object holds some objects as members, as there are:

'PAGE' table data

page, category

CGI environment

user data

First, it provides two member functions, returning the path of the page to be displayed:

$Context->Category()
$Context->PageName()

CGI Member Object

Second, the 'CGI' member holds the values from the CGI 'QUERY_STRING' variable the CGI environment. In application modules, you may asign the 'CGI' member to a local variable:

my $CGI = $Page->{Context}->{CGI}

You may then access values of the hash using the notation:

# value returned
my $ValueFromCGI = $CGI->Query{KeyOfValueFromCGI}

In case of multiple values for a given key, use:

# list reference returned
my $ValueFromCGI = $CGI->Query(\'KeyOfValueFromCGI\')

Other Context Members Objects

Depending on the context, a \'UserData\' object is added to the generation context of the page, to allow individualized content.

Context Callback Function

You can define a callback function, that is executed *before* any other evaluation is done. So, you can e.g. redirect to another page. The callback function has to be defined via the process plugin and must be called 'DocumentCallback'.

Examples

my $Page           = $self;
my $Context        = $Page->{Context};
my $PageType       = $Context->PageType();
my $CGI            = $Context->{CGI};
my $myCGIParameter = $CGI->Query ('myCGIParameter');

if ($Context->{CGI}->Query ('myCGIParameter')) {
  return 'Parameter:' . $myCGIParameter . ' found';
} else {
  return "My name is:" . $Page->{Context}->Page() . $::BR;
}

new

Synopsis

my $Context = Maxscape::Context->new (CGI => $CGI, DB => $::DB);

my $PageName = $Context->Page();
my $Category = $Context->Category();
my $UserId   = $Context->UserId();

Description

Creates a new new Maxscape::Context object. The 'DB' is an object of the 'DataBase' class (defaults to the global $::DB object).
The new functions takes the 'Page' and 'Category' variables from the CGI environments 'QUERY_STRING' variable and instanciates the object.
A unique user identification is set by the authentification system, also.

registerUser

Synopsis

$Context->registerUser ($UserData);

Description

Registers a user.

initialClientRequestCallback

Synopsis

$Context->initialClientRequestCallback ('ContextCallbackFunctionName');

Description

The subroutine takes a name of a global function and executes that function. The callback function takes a '$Context' object as a parameter.
To configure the callback function within the maXscape runtime system, set the variable '$::WebServer->{"Context.InitialClientRequestCallback"}' to the name of your callback function and add the function to your application modules.
The callback is called after initialisation of the 'Context' object including the 'CGI' and 'UserData' members, but before any database query to document data are issued.
The function can be used to alter the name and the category of the page to be generated, before the database is queried for the data in the 'PAGE' table. This gives applications the chance to redirect the requested page to another, as given by the 'Page' and the 'Category' CGI variables, maybe in depency of some other CGI variables.

_initialClientRequestCallback

Synopsis

$Context->_initialClientRequestCallback ('ContextCallbackFunctionName');

Description

Private method used in the initialClientRequestCallback method.

lookupPage

Synopsis

my $Message = $Context->lookupPage ($Response);

Description

This function gathers data stored in the 'PAGE' database table about the context of the page to be generated.
If the process is personalised and the page path matches the users home category, the page request is rederected to that page (the 'UserData' object has a property 'HomeCategory' set).
The database query mode of this function can be configured via the related entries in the '$::WebServer' object. The mode can be set, that the database PAGE table is queried for data of the:

requested a single page (Context.Mode = ''): Only the data of the current page is queried.
requested page and the page parent categories (Context.Query.Hierarchy = $NumberOfLevels): In this mode the function sets the context objects 'PageHierarchy' member to a list, that contains the data of the parent categories. The 'Context.Query.Hierarchy' can be set to number of levels above the current are queried, if possible (e.g. the root category has no parent).
requested page and all nodes of the current page level (Context.Mode='Mode'): In this mode the function sets the context objects 'Categories' member to a hash of arrays, that contains the database entries of the categories of the current page.
a combination of both: the requested page and all nodes of the current page level and the parent categories

If 'Context.Style' is set, queries categories and pages, defaults to fetch only categories.

setContext

Synopsis

$Context->setContext (Category     => '/',
                      Page         => "myBar",
                      ErrorMessage => "Page redirected to path '/myBar'");

Description

This function resets the context to a new page path ('Category', 'Page'). To have any usefull effect, the function has to be called, before any database query to the context data of this page is issued.

lookupCurrentCategories

Synopsis

$Context->lookupCurrentCategories ($Query);

Description

Fetches the nodes from the database page table. As a side effect, the objects 'Categories' member is set to what was fetched from the database.

Examples

my $Text;
$Context->lookupCurrentCategories (
    "select $PathQueryColumns from PAGE where "
      . "(PAGE_NUMBER >= $MIN_CATEGORY_COUNTER "
      . "and PAGE_NUMBER <= $MAX_CATEGORY_COUNTER and "
      . "PAGE_CATEGORY='$self->{Category}' and NODE_TYPE='Category') "
      . " or (PAGE_NUMBER >= $MIN_PAGE_COUNTER and "
      . " PAGE_CATEGORY='$self->{Category}'"
      . ") order by " . $order
      );
foreach (keys (%{$self->{Categories}})) {
  $Text .= $self->{Categories}{$_}[$i];
}

GroupClause

Synopsis

my $GroupClause = $Context->GroupClause ($ColumnName, $ColumnOperator,
                                         $String, ListOperator);

Description

Translates a comma separated list into an SQL statement.

Examples

$self->GroupClause ('PAGE.PAGE_CATEGORY', 'like', "Public,Users", 'or');

UserGroupToWhereClause

Synopsis

$Context->UserGroupToWhereClause ($ColumnName, $ColumnOperator,
                                  $String, ListOperator);

Description

Translates a comma separated list into an SQL statement.

Examples

$$Context-->UserGroupToWhereClause ('PAGE.PAGE_CATEGORY', 'like',
                                    ',Public,Users,', 'or');

StringToWhereClause

Synopsis

$Context->StringToWhereClause ($ColumnName, $ColumnOperator,
                               $String, ListOperator);

Description

Translates a comma separated list into a SQL statement.

Examples

$Context->StringToWhereClause ('PAGE.PAGE_CATEGORY', 'like',
                               ',Public,Users,', 'or');

SqlClauseArraytoString

Synopsis

my $Query = $Context->SqlClauseArraytoString ($ColumnName, $ColumnOperator,
                                              @List, $ListOperator, $CaseInSensitive);

Description

Translates a list into a SQL statement.

Examples

my $Query = $Context->SqlClauseArraytoString ('PAGE.PAGE_CATEGORY', 'like',
                                              'Users,Visitor', 'or', 1);

UsersInGroupsWhereClause

Synopsis

my ($where, $TableName) = $Context->UsersInGroupsWhereClause (
                            UserGroupType => 'PersonalUserGroups',
                                             #CommonUserGroups
                            PageGroupType => 'PublicPageGroups',
                            UserId        => $UserId,
                            TableName     => 'USER_PROFILE',);
);

Description

Returns the appropriate the USER_PROFILE 'USER_GROUPS' property.

Examples

my ($where, $TableName) = $Page->{Context}->UsersInGroupsWhereClause (
                            UserGroupType => 'PersonalUserGroups',
                            PageGroupType => 'PublicPageGroups',
                            UserId        => $Page->{UserData}->UserId(),
                            TableName     => 'USER_PROFILE,USERS',);

PageGroups

Synopsis

my $PageGroup = $Context->PageGroup;

Description

Returns the pages group.

fetchPageLevelNodesAndHierarchy

Synopsis

my ($Categories, $HierarchyList, $MainCategories) =
                             $Context->fetchPageLevelNodesAndHierarchy ($Query);

Description

Fetches and returns the $Categories, $HierarchyList, $MainCategories.

findPageInListOfHashs

Synopsis

$Context-->findPageInListOfHashs ($List, $self->{Category}, $self->{PAGE_NAME});

Description

Finds the nodes index of the node in the $HashOfPageLists hash of lists. If nothing was found, returns -1;

findPageIndexInHashOfLists

Synopsis

my $i = $Context->findPageIndexInHashOfLists ($HashOfPageLists,
                                              'myCategory', 'myPage');

Description

Finds the nodes index of the node in the $HashOfPageLists hash of lists. If nothing was found, returns -1;

UserId

Synopsis

my $UserId = $Context->UserId();

Description

Returns the user's user identification (USER_ID). If authentification is not enabled, the variable is set to the value of $::WebServer->{'User.defaultUserId'} configuration variable (default is 'public').

GroupId

Synopsis

my $UserId = $Context->GroupId();

Description

Returns the user's group identification. If authentification is not enabled, the variable is set to the value of '$::WebServer->{'User.defaultGroupId'}' configuration variable (default is 'Public').

Page

Synopsis

my $PageName = $Context->Page();

Description

Returns the name of the page to be displayed.

PageName

Synopsis

my $PageName = $Context->PageName;

Description

Returns the name of the page to be displayed.

Me

Synopsis

my $Me = $Context->Me();
return "This is a hyperlink to this page.";

Description

Returns a string containing the full process script name and the context CGI Category and Page variables in the form '/www.fcg?Category=/myCategory&Page=myPage', as it is usefull to self referencing a page.

CategoryBasename

Synopsis

my $CategoryBasename = $Context->CategoryBasename();
my $CategoryBasename = $Context->CategoryBasename("/foobar/myBaseCategory");

Description

Returns the page's category basename, if no parameter is provided. Else takes an optional string parameter of the form e.g. '/myCategory/mySub' and returns it's base name.

PageNumber

Synopsis

my $PageNumber = $Context->PageNumber();

Description

Returns the number of the page.

firstCategoryLevel

Synopsis

my $firstCategoryLevel = $Context->firstCategoryLevel();
my $firstCategoryLevel = $Context->firstCategoryLevel( "/foobar/bar/foo" );

Description

Returns the page's category first level, if no parameter is provide. Else takes an optional string parameter of the form e.g. '/myCategory/myCat' and returns it's first level name.

ParentCategory

Synopsis

my $ParentCategory = $Context->ParentCategory();
my $ParentCategory = $Context->ParentCategory("/foobar/bar/foo");

Description

Returns the page's category parent category, if no parameter is provide. Else takes an optional string parameter of the form e.g. '/myCategory/myCat' and returns it's parent category name.

decodeCategory

Synopsis

my $decodedCategory = $Context->decodeCategory();

Description

Decodes categories.

PathToList

Synopsis

my @PathToList = $Context->PathToList();
my @HierarchyList = $Context->PathToList('/zz/uu/oo/yyy');

Description

Returns all category levels in as a list.

HierarchyPathToWhereClause

Synopsis

my @HierarchyWhereClause = $Context->HierarchyPathToWhereClause
                                 ($HierarchyDepth, $HierarchyOrder,
                                  $Operator, $Order);

Description

Returns a SQL where clause for the category levels above the current.

fetchPageHierarchy

Synopsis

my $PageHierarchyListOfHashesReference = $Context->fetchPageHierarchy();

Description

Fetches the the page hierarchy from the PAGE table. Must previously be initiated by a SQL query statment to the PAGE table. Returns the list of parent categories of the current category of the page tree.

HierarchyCategory

Synopsis

my $Level = 0;
my $ParentCategory = $Context->HierarchyCategory($Level);
return ${$ParentCategory}{PAGE_NAME};

Description

Returns a reference to a hash containing all the data about a parent category previously fetch from the database. The parameter taken is the level above the current (e.g. 0 is the parent category, 1 is the parent of the parent, ...).

NodeType

Synopsis

my $NodeType = $Context->NodeType();

Description

Returns the node type of the current node. Currenty 'Category', 'Template', 'Document' and 'Link' are defined. 'Process' is for future purposes.

QueryNodeTypeByNumber

Synopsis

my $NodeType = $Context->QueryNodeTypeByNumber($PageNumber, $Cursor);

Description

Makes a query to the database and returns the node of a page by its PAGE_NUMBER. perposes.

Examples

my $NodeType = $Context->QueryNodeTypeByNumber($PageNumber);
my $NodeType = $Context->QueryNodeTypeByNumber($PageNumber, $Cursor);

QueryNodeByNumber

Synopsis

my ($Category, $Name, $NodeType) = $Context->QueryNodeByNumber ($PageNumber);

Description

Queries a node by its page PAGE_NUMBER.

QueryNodeByNumberHash

Synopsis

my $NodeHashReference = $Context->QueryNodeByNumberHash ($PageNumber);

Description

Queries a node by its page PAGE_NUMBER. All PAGE columns are returned.

Examples

my $NodeHashReference = $Context->QueryNodeByNumberHash ($PageNumber);

my $Category = ${$NodeHashReference}{PAGE_CATEGORY};
my $Name = ${$NodeHashReference}{PAGE_NAME};
my $NodeType = ${$NodeHashReference}{NODE_TYPE};
my $PAGE_OWNER = ${$NodeHashReference}{PAGE_OWNER};
my $PAGE_WRITE_GROUPS = ${$NodeHashReference}{PAGE_WRITE_GROUPS};

QueryNumberOfSubNodesByPageNumber

Synopsis

my $SubNodesNumber = $Context->QueryNumberOfSubNodesByPageNumber($PageNumber);

Description

Makes a query to the database and returns the number of sub nodes.

Examples

$Counter = $Context->QueryNumberOfSubNodesByPageNumber($PageNumber);
$Counter = $Context->QueryNumberOfSubNodesByPageNumber($PageNumber, $Cursor);

QueryNumberOfSubNodesByPath

Synopsis

my $SubNodesNumber = $Context->QueryNumberOfSubNodesByPath($Category, $Page);

Description

Makes a query to the database and returns the number of sub nodes.

Examples

$SubNodeCounter = $Context->QueryNumberOfSubNodesByPath($Category, $Page);
$NodeNr = $Context->QueryNumberOfSubNodesByPath($Category, $Page, $Cursor);

NodeExist

Synopsis

my $exists = $Context->NodeExist ($Category, $Page);

Description

Makes a query to the database and returns the number of sub nodes.

Examples

QueryNodeByPath

Synopsis

my ($NodeRef) = $Context->QueryNodeByPath($Category, $Page);

Description

Queries a node by category and page name. Returns a hash reference. perposes.

Examples

my $Node = $self->{Page}->{Context}->QueryNodeByPath($Category, $lastPathNode);
if (${$Node}{NODE_TYPE}) {
  ..
}
$Node = $Context->QueryNodeByPath($Category, $lastPathNode, $Cursor);

QueryNodeNumberByPath

Synopsis

my $NodeNumber = $Context->QueryNodeNumberByPath($Category, $Page);

Description

Queries a node by category and page name. Returns the node number. perposes.

Examples

my $NodeNumber = $Context->QueryNodeNumberByPath($Category, $Page, $Cursor);

popParentCategory

Synopsis

($ParentCategory, $AbsolutePath) = $Context->popParentCategory($CategoryName);

Description

Returns the parent category and the category name from a category name.

Examples

($ParentCategory, $AbsolutePath) = $Context->popParentCategory($AbsolutePath);

PageType

Synopsis

my $PageType = $Context->PageType();

Description

Returns the generation type type of the current page.

ContentType

Synopsis

my $ContentType = $self->ContentType();

Description

The content type of a page is given by the member function ContentType.

TemplateType

Synopsis

my $PageTemplateType = $Context->TemplateType();

Description

Returns the template type of the current page.

TemplateName

Synopsis

my $TemplateName = $Context->TemplateName();

Description

Returns the template name of the current page.

TemplateNumber

Synopsis

my $TemplateNumber = $Context->TemplateNumber();

Description

Returns the template number of the current page.

CreationTime

Synopsis

my $CreationTime = $Context->CreationTime();

Description

Returns the creation time of the current page.

lastModificationTime

Synopsis

my $lastModificationTime = $Context->lastModificationTime();

Description

Returns the time, when the current page was last modified.

PageOwner

Synopsis

my $PageOwner = $Context->PageOwner();

Description

Returns the owner of the current page.

UserIsAllowed

Synopsis

my $UserIsAllowed = $Context->UserIsAllowed();

Description

Returns the permission setting of the current page.

PageGroup

Synopsis

my $PageGroup = $Context->PageGroup;

Description

Returns the pages group.

PagePermission

Synopsis

my $PageGroup = $Context->PagePermission ($WebServerName, $User);

Description

Returns the pages permission of a user.

ClientType

Synopsis

my ($HTTP_USER_AGENT, $Browser,
    $BrowserVersion, $Language, $OS) = $Context->ClientType();

Description

addQueryParameterToMe

Synopsis

$Context->addQueryParameterToMe (name => 'Name');

Description

To be added.

SCRIPT_URI

Synopsis

my $SCRIPT_URI = $Context->SCRIPT_URI;

Description

Returns the URI of a script.

SCRIPT_URI_Method

Synopsis

my $SCRIPT_URI_Method = $Context->SCRIPT_URI_Method;

Description

Returns the method of a script URI.