-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hi.
First, I'm finished with my studies, the diploma thesis is finished, and I'm finally able to free some time for midgard again. Attached to this Mail is the first Draft over a thing we here at Linksystem Muenchen call the "Midgard Components" Framework. It is still incomplete, but take a look and tell me what you think! Live long and prosper! Torben Nehmer - -- Torben Nehmer, Munich, Germany http://www.nathan-syntronics.de, mailto:[EMAIL PROTECTED] PGP Public Key ID on wwwkeys.(de.)pgp.net: 0x7E9DE456 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (GNU/Linux) Comment: Weitere Infos: siehe http://www.gnupg.org iD8DBQE8hPveJPh4Kn6d5FYRAqhSAKCMZKrOX/Fx5/Syo+iwf2MLqE3MJwCg/VEl 4mnBj2zqj0fUbPL/VfjPASs= =iGmi -----END PGP SIGNATURE-----
RFC: Midgard Components (MidCom)
================================
Author: Torben Nehmer, Linksystem Muenchen GmbH <[EMAIL PROTECTED]>
Date : March 4th, 2002
Abstract
--------
This document represents a draft about a component architecture for the Midgard
Content Management System. Its intend is to provide an easily extensible
Application Framework based on Midgard. It should -- in its ultimate
extent -- enable end users to "click their sites together" using common
Components for news tickers, discussion boards or similar things.
Table of Contents
-----------------
1. Design Goals
2. Application Infrastructure Overview
3. Components
3.1. MidCom Hooks
3.2. Component Code
3.3. Administration Interface
3.4. Layout Hooks
3.5. Configuration
4. Namespace Conventions
4.1. SnippetDirs: Component Storage
4.2. Global Variables
4.3. Class and Function identifiers
4.4. Namespace "midcom"
5. Interface Definitions
6. Preparing a Site for Components
7. Using Components
8. Automated Administration Interfaces
9. Advanced Layout Engine
10. Navigation Access Points (NAPs)
11. Debugging
1. Design Goals
---------------
What Midgard currently lacks most is an easy way of importing applications into
an existing site. Most written applications are site-specific and can hardly be
exported into another site without great customization. This is where Midgard
Components come in:
Every MidCom application is contained within a Component with an explicitly
defined interface to the world. Controlling infrastructure is the topic tree
not the page tree giving you a far greater flexibility. The code itself is
completely encaspulated in snippets, making replication very easy.
A framework is used to manage the components, both for public and private sites
such as a web site and its administrative site. In theory this could even
automate the building of administration interfaces by "traversing" every active
component.
2. Application Infrastructure Overview
--------------------------------------
The basic idea is that the regular Midgard Program Flow (see midgard-root.php)
is enhanced by the MidCom Framework. It uses the "code-global", "code-init"
and "content" (magic) page elements to relay execution to the different
components. Basically you can treat a MidCom as a fully encaspulated package
that provides hooks for the following program flow:
Step 1: <[code-global]>
<? Component Configuration ?>
<[code-global-local]>
Step 2: <[code-init]>
<? URL Parsing ?>
<? Component Initialisation ?>
Step 3: <[content]>
<? Component display ?>
Except from the call to <[code-global-local]>, every call is handled by the
component framework, basically giving you this:
Step 1 loads all necessary functions for the component framework, initialise
the system and loads the component information along with its
configuration. The framework also calls the custom element
<[code-global-local]> where you can place site-specific, not MidCom-related
configuration directives.
After that the real processing starts in Step 2. A URL Parser is used to map
the request URL to the given topic tree. Every component has the chance to
manipulate this process. The parser design is two-staged: First the given
component gets the chance to evaluate the URL. If this is successful, parsing
stops and execution continues. If not, the system executes MidCom's default
handler, which tries a direct mapping between the topic tree and the URL.
If no error occurs during parsing, the component-specific initialisation code
is called. It prepares everything for the final display in the "content"
element.
Further Notes (-> things to incorporate into the rest of the document):
- The components store "layout hooks" within itself, similar to style
elements. Each of these "hooks" is represented by its own snippet within the
component. You can either store your layout code there directly (as with the
default layout), or you can replace it with a call to a style element
(preferred way for complex layouts). By default you'll get a very simple
layout, that should be sufficient for small websites.
- The components are configured in two steps: First a global configuration is
attached to the component itself, which is loaded during Step 1. Second it is
customized on a per-use basis by parameters that are attached to the
controlling topic/article/attachment.
- It is very important that each component is replication-save. Most complex
sites require a staging-live setup, so the replication of the whole system is a
basic necessity.
- This might also require versioning of MidCom Data Elements. Each one should
store the version number of the MidCom it was created with. This enables a
MidCom programmer to update a MidCom without loosing backward-compatibility
with an existing site.
- Inheritance has to be enabled explicitly for each subtree if desired. If no
Component handler is defined either through direct accociation or through
inheritance, a predefined default Component is used.
- Idea: It could be possible to define mulitple component handlers for a single
object, especially if using inheritance. Along with a precedence, MidCom would
traverse the list of handlers and execute the first one, that actually declares
to be able to handle the request.
3. Components
-------------
Technically a MidCom is delivered as a repligarded SnippetDir with a defined
layout. Basically there are five parts of a MidCom, each contained in its own
SnippetDir below the main one:
1. MidCom Hooks: Hooks for the MidCom Framwork, required to handle the
Component
2. Component Code: The Application itself
3. Administation Interface: Snippets for the Admin Site Builder
4. Layout Hooks: Snippets to control the output of a MidCom
5. Configuration: Global Configuration of the MidCom
While the first three parts should not never be touched by an end-user, the
last two most certainly will be. This should be kept in mind that those parts
of a MidCom should _not_ be replicated in updates. (Repligard would
overwrite the customized snippets with the default ones. A good idea(tm) for
repligard would be an option to copy the imported data, especially usful in a
situation like this.)
3.1. MidCom Hooks
-----------------
This is the real interface to the outside world. It defines a set of classes
that the Framework uses to access the Component. The classes found here have to
present a defined interface for the different operations. Entry points are
defined for:
- Global Component Initialization
- URL Parsing
- Local Component Initialization
- User Interface Display
- Administration Interface Display
- Navigation Access Points
3.2. Component Code
-------------------
This is the place where you write all your component code. Call it Application
Logic, Business Logic or whatever you want, but this is the place where you can
roam around. But keep the Namespace Conventions (see below) in mind!
Component Code is privat, which means that it will not be called from anyone
else as your own component. Even the MidCom Framework uses the Hooks to access
these classes.
3.3. Administration Interface
-----------------------------
Even though this part is theoretically already covered under "Component Code",
it is separated to make a component more clearly structured. It contains all
necessary Classes to dynamically create an administration interface to the
MidCom. The classes in here have to follow a defined Interface to enable the
automatic interface-building.
3.4. Layout Hooks
-----------------
This SnippetDir roughly works like a Style. It gives you a number of Snippets,
each representing a part of the interface layout. Whether you write the HTML
Code directly into those snippets or not is your choice.
Concerning Replication: Since the Layout Hooks SnippetDir is not in the
upgrade-XML file, special care has to be take here if you introduce new
Elements. Preferably you explicitly export those new elements into the
upgrade-XML file to ensure completness of the Component.
See also: "Advanced Layout Engine"
3.5. Configuration
------------------
Put the global Snippet Configuration (i.e. for I18N ...) into this
SnippetDir. A single Snippet called "config" in this SnippetDir will be
included during the Global MidCom Initialization Stage. This Snippet can then
call other Snippets as it is required.
4. Namespace Conventions
------------------------
Very important is the Namespace Convention of the whole framework. Current
Midgard Solutions often have no explicit Namespacing (since it isn't supported
by PHP or Midgard anyway), which often results in a certain chaos if you try to
integrate multiple applications into one site.
The basic idea behind MidCom Namespacing is a System similar to Java's Package
Hierarchy. To achieve globally unique Package identifiers it suggests using
Internet Domain Names as a Hierarchy. This leads to package Names like
"de.linkm.newsticker". This path, called the "MidCom Path", represents the
MidCom Namespace of Component itself. It is used everywhere to seperate
different Components from each other.
A component's name must match this regular expression:
[a-z][a-z0-9]*
All non-valid characters (i.e. "-" in Domain Names) have to be dropped.
4.1. SnippetDirs: Component Storage
-----------------------------------
Translated into Snippetdirs path results "/de/linkm/newsticker/". This path
is used to store the Components in an hierarchical order.
Each component has the five defined snippetdirs form chapter 3, which in
addition are the only reserved names for SnippetDirs. Therefore a MidCom
package is valid if and only if a SnippetDir contains all five SubSnippetDirs
and the defined set of classes (see below) in the MidCom Hooks Section. This
gives us this Basic Layout:
/------------------------------------------------------------------------------
| Figure: Basic MidCom Package Structure
|------------------------------------------------------------------------------
|
| de
| \-linkm
| \-newsticker => Base SnippetDir
| |-_component
| |-_adminsite
| |-_midcom
| |-_layouthooks
| |-_config
| \-_documentation
\------------------------------------------------------------------------------
This structure leads to the conclusion, that every element within this tree can
be both a component and a container for further components. An exception are
the Top-Level Domains (com, net, org, de ...), which must not be used as a
Component.
Although it is possible to put additional Components "into" an existing one,
this is strongly discouraged, because it makes the whole tree difficult to
read. If you require it (i.e. to extend an existing site), the defined
SubSnippetDir's are all prefixed with an "_" to get them at the right place in
the sorting order.
Idea: Should there be a SnippetDir "Documetation" ??? -> Sure, i.e. Admin Site
Help Files ...
4.2. Global Variables
---------------------
Each Component will most probably require a number of global variables for
processing. Again we use the MidCom Path as a prefix for the variables,
replacing the dots with underscores. In our example the newsticker Component
would call its Global Variables de_linkm_newsticker_...
Idea: There should be a global place where a component could register global
Variables. This would require working references withihn PHP (I've never tried
this...). If it is good enough, you could use this "Registry" to avoid global
variables by putting all values in a Reference List accociated with your
Component.
=> The Registry approach should be prefered!
4.3. Class and Function identifiers
-----------------------------------
Basically this works like Global Variable naming above.
4.4. Namespace "midcom"
-----------------------
This is a special Namespace on the same level as the top-level domains. It is
used as entry Point into the MidCom Framework. Anything below midcom.* is
therefore not allowed for any Components (shouldn't be the case anyway).
Idea: It might be necessary to create "System Components", all those will also
go under the midcom Namespace Tree, following all other conventions above.
4.5. Parameters in the Topic Tree
---------------------------------
MidCom uses Parameters to Content Objects (topics, articles, attachments) to
control the whole web site. Again the Component Path is used to set
configuration Parameters. The Domain "midcom" is used to control MidCom
itself. Important is the Parameter midcom.component, which contains the Path to
the component MidCom should load at this point. Component Specifc Parameters go
into a domain named after the MidCom Path, in our example
"de.linkm.newsticker".
5. Interface Definitions
--------------------------
While you could use inheritance to create the MidCom Hook Classes, this is not
necessary - PHP doesn't support abstract classes anyway. Due to this an
approach similar to the Standard Template Libraries "Concepts" ist taken here.
A definition of required methods is defined for every Interface, which are
needed by the Framework.
2DO: Interfaces have to be defined for
- Component Management
- User Interface
- Admin Interface
- Layout Management
- URL Parsing
6. Preparing a Site for Components
----------------------------------
>> Allgemein:
>>
>> Ich w�rde diese default-fallbacks (topic/article-admin,
>> urlparser-defaults) nicht als bestandteil der
>> komponentenarchitektur betrachten, sondern als "mitgelieferte
>> standard-komponenten". Die haben strukturell mit dem modell
>> nichts zu tun, ausser dass sie entweder in der globalen
>> Initialisierung speziell als Defaults registriert werden oder
>> einfach per Namenskonvention definiert sind.
Basically (not including MidCom Installation...):
- Create the site, with a single, active page
- Write <[code-global]>:
Instantinate MidCom Main Application Object
- OPTIONAL: Write <[code-global-local]>:
Put your custom Init Code here.
- Write <[code-init]>:
Call MidCom's code-init-Method
- Write <[content]>:
Call MidCom's content Method.
- Create Main Site Style, not referencing to any other page-element then
<[content]>
- Use MidCom Functions to dynamically place Navigation Elements within
the Style tree
- Configure MidCom (most probable in <[code-global]>:
- Define root Topic
- ...
7. Using Components
-------------------
Basically the only thing you have to do is put a Parameter to an Article or
Topic referencing a MidCom and, if neccessary, some parameters.
8. Automated Administration Interfaces
--------------------------------------
-> Uses the same infrastructure as the public site to display the Admin
interfaces of the different used components.
Using the same infrastructure you could easily create an automated
administration site. By default it gives you a standard interface (which is
defined in the configuration), but as it encounters other components, i.e. a
newsticker, the MidCom framework loads the MidCom's own admin interface. Here a
clear abstraction between layout and the application itself is very important
to provide a way to automagically merge the different administration
interfaces into a single admin site.
9. Advanced Layout Engine
----------------------------
-> Replace the <[...]> Syntax for Style-Elements with custom functions to
enable dynamic style switching.
An enhanced Layout Engine could be created, still using styles and elements,
but not accessing them through midgard but through custom fuctions. The
advantage here is, that you are not bound to use the style accociated with the
active page, but any style available. Neccessary to do this is a new layer
replacing the <[...]> Syntax with custom function calls that access the Style
Tree directly. Using this Interface, you could do automatic mapping between the
Layout Snippets of the component and an accoicated Style.
10. Navigation Access Points (NAPs)
-----------------------------------
Each component should have a "navigation mode" for display that gives you
enough information to dynamically build navigation trees. It should not be
neccessary to know the internals of a component to be able to build a
navigation system. Therefore several functions give you an abstract access to
this information.
11. Debugging
-------------
===============================================================================
$Id: midgard-components.txt,v 1.6 2002/03/05 17:07:08 torben Exp $
midgard-components.txt.sig
Description: PGP signature
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
